A custom data source allow you to import real-time information from other systems into Engage and make that data accessible in the Design studio, where it can be used in send-outs.

There are basically two ways to work with custom data sources.

API: In this setup data is fetched by a GET request from an REST API endpoint where a JSON response can be used as dynamic data in the message. Read further down about configuration.

Dynamic content providers: Typical use cases is to insert product recommendation or other image content from an external system. See this article for more information.

Adding a custom API data source

Configuration of custom data sources is done in the Configure Engage area of your Engage UI. 

Name: This is the name that will be shown in the Email Design Studio, allowing this data source to be selected there and the data from it to be used.

ID: This is the internal ID of the data source (lower case with underscore). This must be unique.

The API endpoint toggle will reveal these settings:

URL: This is the URL to the endpoint to be called to fetch the data. It can be static or can include parameters defined by {name}, as shown here.

Example 1: A static API endpoint:

https://yourdomain.com/api-endpoint

Example 2: A dynamic API endpoint with parameters. 

The parameters must be defined in the Input schema (under Parameters - see next section).

https://yourdomain.com/api-endpoint/{Site}/?id={ProductIds}

Authorization: Choose "None" or "API key" here (which reveals the following two fields).

Header key: Enter the name of the authorization key, for example "api-key".

Value: Enter the key secret.

Cache time in seconds: This specifies long Engage will cache the response. So if the exact same call is repeated inside the caching time, the cached response will be used inside of calling the endpoint again. Enter 0 here if you don't need it to be cached.

Output JSON schema: This JSON schema informs the system of the form of the return data. The properties listed here are made available in the Design studio and can be used as personalization fields, repeaters and display conditions. Example value for this schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "productList": {
      "title": "Product List",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNumber": {
            "title": "Article number",
            "type": "string",
          },
          "imageUrl": {
            "title": "Image url",
            "type": "string",
          },
          "link": {
            "title": "Link url",
            "type": "string",
          },
          "name": {
            "title": "Product title",
            "type": "string",
          },
          "leftinstock": {
            "title": "Number in stock",
            "type": "integer"
          },
          "releasedate": {
            "title": "Release date",
            "type": "string",
            "format": "date",
          },
          "oncampaign": {
            "title": "Ongoing campaign",
            "type": "boolean",
          },
       },
        "required": [
          "itemNumber",
          "imageUrl",
          "link",
          "name"
        ]
      }
    }
  }
}

The Output JSON parameters

The properties from the Output JSON schema can be used in your message in various ways:

For personalization: For example, you could add a personalized field for "release data" to a text and one for "link" to a button since these are properties returned from the data source.

The Design Studio will also allow the user to format the data, based on the data type, as in the example show for "Release date" above.

For display conditions: Properties can be used for display conditions like this:

For repeaters: Arrays in the schema can be presented using repeaters in Design Studio.

The Input JSON parameters

Sliding the Parameters toggle reveals the Input JSON schema. The JSON schema entered here corresponds to the parameters defined in the endpoint URL above. 

The JSON schema also defines the data type and description for the parameters for the form that is displayed in the UI for the user of the Design Studio. See the example below. 

An example value for this field would be the following:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "Site": {
        "title": "Website language",
            "type": "string"
        },
        "Numberof": {
            "title": "Number of products",
            "type": "integer",
            "minimum": 1,
            "maximum": 5
        },
        "Range": {
            "title": "Range",
            "type": "number",
            "minimum": 0.1,
            "maximum": 9.9
        },
        "Sortorder": {
            "title": "Sort order",
            "enum": [
                "lowestprice",
                "highestprice"
            ],
            "type": [
                "string"
            ]
        },
        "Productids": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    },
    "required": [
        "Productids", 
        "Sortorder"
    ]
}

Here are the data formats used in the URL and the corresponding one used in Design Studio:

For the example input JSON schema shown above, the Design Studio would show the following form for that data source. This now makes it easy as for the user to use the API endpoint data.

(Note that the fields here would initially be empty):

Article last reviewed 19 November 2025 08:52