Set up Integration Fields

This article explains how to integrate with third-party services using Prismic's Integration Fields.


This document explains how to set up an Integration Fields API endpoint. Want to learn how to add an Integration Field to your content model? See Configure Integration Fields.

This feature isn't yet available for everyone

Integration Fields is still in beta. It is being progressively deployed to all repositories. If you don't see the Integration Fields tab in your repository's settings, you can request access via the Prismic community forum.

Prismic's Integration Fields allow you to integrate third-party data — such as from e-commerce catalogs or custom APIs — into your repository.

There are three ways you can integrate a third-party data source using Integration Fields:

  1. Pull data from a custom read API
  2. Push data from a custom write API
  3. Automatically sync with a Shopify catalog

Pull data into Prismic from a custom API

To pull data into Integration Fields, you must create your own API that conforms to the format prescribed below.

In your repository, navigate to the Settings > Integration Fields.

Select Custom API.

Select pull data from my endpoint, and fill in the Custom API details:

Catalog Name

required

The name of your Custom API catalog. This is shown in the Custom Type Builder.

Description

required

A description for your Custom API catalog. This is shown in the Custom Type Builder.

Endpoint

required

The endpoint of your Custom API. The API must output JSON in the specified format (see below).

Access Token

An access token for your Custom API catalog.

Click Save. The Integration Field will automatically begin to crawl and sync your Custom API.

Custom API format

Your Custom API format must be compatible with Integration Fields. The API can have the following properties:

result_size

number (required)

The total number of items to index.

results

array (required)

An array with the results. It must be sorted by the last_update field, and have a maximum of 50 items per page.  See information on pagination, below.

results[index].id

string

The unique ID of the item.

results[index].title

string

The title of the item. This is shown in the document editor.

results[index].description

string

The description of the item. This is shown in the document editor.

results[index].image_url

string

The image url of the item. This is shown in the document editor.

results[index].last_update

string

The timestamp of the last update for an item, sorted from newest to oldest

results[index].blob

object

An object with the item's data. This is what appears in the in the document in the Prismic API response.

Here is an example of what your custom API should look like:

Copy
{
  "results_size": 1,
  "results": [
    {
      "id": "1",
      "title": "Item Title",
      "description" : "Description of the item.",
      "image_url" : "https://images.unsplash.com/photo-1577401239170-897942555fb3?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1600&q=80",
      "last_update" : 1509364426938,
      "blob": {
        "sku": "1",
        "title": "First item",
        "description": "Description of first item.",
        "image_url": "https://images.unsplash.com/photo-1577401239170-897942555fb3?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1600&q=80"
      }
    }
  ]
}

Pagination

The results array can have a maximum of 50 items. If your API contains more than 50 items, then you will need to set up pagination. 

The page number for the API must be passed as a parameter in the URL, so you'll pass ?page=1, for the first page, then ?page=2, and so on.

Automatic content updating

If a change is made in your external API, Prismic will automatically update the data to ensure that you always have the most up-to-date content. The content refresh currently happens every 30 minutes, though interval may change in the future.

Use your Integration Field data

Add your Integration Field to a Custom Type and then add a catalog item to a Prismic document.

The first time you sync your Integration Field, it can take some time to update.


Push data to Prismic from a custom API

Integration Fields has a write API that allows you to push data to Prismic so you can create, modify, or delete catalog items via a dedicated enpoint.

Configure the write API

Go to Settings > Integrations Fields in your repository, Click on Custom API, and select Push data to Prismic. Only Administrators can edit the Integration Fields configuration.

Enter the Catalog name and description, and then click on Create my Integration Field.

Once your Integration Field is created, you can click on it to view the write API endpoint as well as the access token you'll need to interact with your API.

The Integration Fields write API allows you to create, update and delete items, or reset the entire catalog.

To do so, send a POST request to the endpoint specifying the type of action you want to perform, with necessary information in the header and body.

Let's go over each of the steps to push to your custom catalog.

Get your API endpoint

In your repository, go to Settings > Integration Fields. Scroll down until you find your active Integration Field write API. Click on the pencil edit button; it will open the configuration. From there, copy the endpoint, which will have the following structure:

https://if-api.prismic.io/if/write/<your_repo_and_catalog_names>

Where <your_repo_and_catalog_names> is a string made up of your repository and catalog name.

In this example endpoint, we will assume that the repository name is your_repo_name and the catalog ID is my_catalog.

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog

Create a POST request

By sending a POST request to your endpoint, you can create, update or delete items in your catalog. The way you write your endpoint will define the action that will take effect:

To create or update items, use the main endpoint:

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog

To delete one or more items, use /deleteItems:

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog/deleteItems

To reset the entire catalog, use /reset:

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog/reset

Add a body to the request

The body of the POST requests will depend on the action you want to perform:

  • To create items: include an array with the new items following the format specified below.
  • To update items: include an array with the existing items and their updated values following the format specified below.
  • To delete one or multiple items: include an array with the ID of each item to delete.
  • To reset the entire catalog: no body is required.

Item format

Items POSTed to the write API should follow the following format. For more information on these properties, see "Custom API format," above.

Copy
{
  "id": "my_item_id",
  "title": "Item Title",
  "description" : "Description of the item.",
  "image_url" : "http://...",
  "last_update" : 1509364426938,
  "blob": {
    "sku": "827",
    "title": "First Item",
    "description": "Description of first item...",
    "image_url": "https://..."
  }
}

Add an authorization token

Include a Bearer token in the authorization of the POST request. To find your token in your active, click on the pencil edit button on your Integration Field settings, and scroll down to find the token section.

Putting it all together

Here are full examples of raw POST requests to create, update, or delete items; or reset the entire catalog of your Integration Field write API.

You can run a test in a third-party API platform, like Postman.

To create or update:

Copy
// Example POST request to Create or Update a catalog with 500+ items

POST /if/write/your-repo-name--my_catalog HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 514
[
  {
    "id": "0",
    "title": "My Item number 0",
    "description": "Lorem ipsum",
    "image_url": "https://if-test-custom-api.herokuapp.com/asset/0",
    "last_update": 1591670070,
    "blob": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  },
  {
    "id": "1",
    "title": "My Item number 1",
    "description": "Lorem ipsum",
    "image_url": "https://if-test-custom-api.herokuapp.com/asset/1",
    "last_update": 1591670070,
    "blob": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  }
]

To delete:

Copy
// Example POST request to delete three items from a catalog with 500+ items

POST /if/write/your-repo-name--my_catalog/deleteItems HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 514
["id-0", "id-1", "id-2"]

To reset:

Copy
// Example POST request to reset a catalog, deleting 500+ items

POST /if/write/your-repo-name--my_catalog/reset HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 0

Use your Integration Field data

Add your Integration Field to a Custom Type and then add a catalog item to a Prismic document.

The first time you sync your Integration Field, it can take some time to update.

Sync with a Shopify catalog

Prismic has a built-in integration with Shopify.

Get your credentials from Shopify

Create or log in to your Shopify account.

On the Admin page, click on Apps in the left navigation menu. Then, click on the Manage private apps link at the bottom of the App page.

If you are a new user, you have to click the Enable Private App Development button to enable the creation of your private apps in Shopify.

Next, click Create private app. Give a name to your private app and an email for emergency communication. Make sure that all the Admin API permissions are set to Read Access.

Click on Save. A modal will pop up where you can click on Create app.

In the API admin panel, provide open API access to your store. You will find the API key, Password, and Secret Key. You will use these credentials in the next step.

Create a Shopify Integration Field

In your repository, navigate to the Settings > Integration Fields.

Select Shopify, and fill in the Shopify Settings. The API key, password, and shared secret can all be copy and pasted directly from your Shopify App settings.

Catalog name

required

A name for your Shopify catalog. This will be shown in the Custom Type builder.

Description

required

A description for your Shopify catalog. This will be shown in the Custom Type builder.

Endpoint

required

The API endpoint of your Shopify catalog with the following format: your-store.myshopify.com. Without HTTPS.

API key

required

The API key for your Shopify catalog.

Password

required

The password for your Shopify catalog.

Shared Secret

The shared secret for your Shopify catalog.

Click on Save. The Integration Field will automatically begin to crawl and sync your Shopify catalog.

Add the Integration Field to a Custom Type.

Finally, go to a document and add a product to the Integration Field. Save, and Publish your document!


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.