✅

Simon Real-time Content is an optional premium feature.

Contact your account manager to get started.

📘

Use case compatibility

Use of this feature requires coordination with solution architects to ensure that it can be deployed in a way that meets your desired use cases. Please reach out to your account manager for more details.

Overview

Real-time Content is an API client that fetches data from an external API at send time for dynamic content across all Simon-supported end-channels: email, SMS, push notifications, marketing cloud such as SFMC, and our data share suite.

Information such as inventory, personalized offers, and product recommendations change quickly. In order to provide the best experience for your consumers, Simon waits until the last possible minute to load this data, i.e. the content is rendered at send time.

API clients for real-time content are managed under Datasets. A dataset is created once the endpoint is successfully configured. Endpoints are accessible in Simon’s content builder under the Lookup tab. This feature is an expansion of our dynamic content, which uses Jinja. Customer attributes or static values may be used in query parameters. Making an API call takes a dictionary-like object in the format {'key': 'customer_attribute'} as the lookup key which would look like this in Jinja {{ lookups.api_dataset_name[{'key':'customer_attribute'}].field1 }}. Real-time content works with APIs that provide a response in JSON.

Examples

• Deals & promotions
• Product recommendations
• Inventory & pricing
• Localization (e.g. translation)
• 3rd party (e.g. TrustPilot)

API onboarding process

Simon has created a process to support you when onboarding new APIs. It includes the following steps:

1. API Intake form: Work with your account manager to provide information about the intended use and volume for the API.
2. Review: We'll review the intake form, clarify open questions and identify potential issues to be explored during set-up and testing.
3. API set-up: You set up the API configuration, as outlined below.
4. Testing: Together we'll test the API integration to validate the performance in a realistic setting.
5. Launch and monitoring: API-powered campaigns go live. Both you and we will monitor usage and performance.

This process is designed to develop a shared understanding across teams of the campaign plans and the intended use of the API in order to ensure a smooth roll-out. This is especially important for high volume campaigns.

📘

Consider the pros and cons of real-time content

Fetching content in real-time is less efficient and will take longer time than using contact properties, event data or lookups as content. Consider whether a batch ingestion approach might be preferable for your intended use and your data needs before deciding to use real-time content.

Adding a new endpoint for use with real-time content

1. From the left navigation, click Datasets.
2. Click Create Dataset.
3. Select Real Time Content and click Next.

There are three parts to the API set-up: endpoint, authentication and response. Each one is covered in more detail, below.

The API name must be unique, and cannot include special characters or spaces.

📘

Who is the right person to set up a new API?

We recommend that a technical user set up a new API, since it requires a good understanding of the technical details of that API.

Endpoint

This section specifies the core aspects of how to call the API. This includes the HTTP method (GET or POST) and endpoint URL. In addition, you can specify the parameters that will be passed to the API.

Parameters

We support dynamic values and parameters in three different places:

• URL (dynamic path and query parameters)
• Headers (only static parameters)
• JSON payload

Static parameter values can be included directly in the dataset configuration under the respective section (e.g. a specific content type in the header). These don't need any special syntax.

You can also specify dynamic parameters, by using double curly brackets, {{ }}. This will make this parameter a required key when this API is used for content. For example, if you will be using a weather API to check for the weather based on city_name, whenever this API is used as content (e.g. inside a subject line), you will need to provide a value for city_name.

When adding a dynamic parameter, you will be required to provide a Test Value and can optionally include a Dynamic Value. The test value will be used when you do a test call from the dataset builder by clicking on Run. The Dynamic Value will make it easier to use the API, by pre-populating that parameter with a contact or event property when you click to insert content from the API response within the content builder (e.g. templates).

Including dynamic values in the endpoint URL

The provided endpoint URL can provide dynamic values, e.g. to add a dynamic part to the path. Use the {{<parameter_name>}} format to specify parameters that are part of the URL, as in: <https://api.weather.com/weather_conditions/v1/{{location_id}}/{{timeperiod}}>.

Query parameters

You can also easily add query parameters in this section. There is no special syntax required. If a parameter contains a static value, enter the value into Test Value field and leave Dynamic Value empty.

Additional headers

This section allows you to specify additional headers to be included in the API call.

Request body

Nested JSON is supported for request body parameter. Use double curly brackets, {{ }}, to add a Test and Dynamic Value fields. Static parameters do not need special syntax.

Authentication

Currently, supported Authentication Methods for an API are:

• Public
• API-key
• OAuth 2.0 (password credentials and client credentials)
• Certificate

API keys can be configured as query parameters or within the endpoint set-up.

Response

Simon accepts JSON response, including nested JSON.

Retry strategy

The following behavior can be specified for retries:

• Timeout: Seconds before timing out the request
• Retry tries: Number of retry attempts before aborting.
• Retry delay in seconds: Seconds before retrying if a retryable code is returned.
• Retry backoff: Backoff multiplier. For example, 2 will double the backoff for each retry, and 1 means no backoff.
• Retry wait random minimum: Minimum random seconds to add to the wait before each retry. 0 = no wait.
• Retry wait random maximum: Maximum random seconds to add to the wait before each retry. 0 = no wait.

Response code behavior

Specify HTTP response code behavior to prevent content error resulting in blocked campaigns.

• Retryable codes: Status codes that trigger retry mechanism configured in the section above. Default is 504.
• Accepted codes: Status codes that signal the request was properly processed and return a response body that can be used in content. Default is 200.
• Null override status codes: Override non-transient error codes with Null value (e.g. to have 404 to result in an empty response).

Caching

Caching API responses is highly encouraged, where applicable, to improve send speed. Here are some scenarios where caching makes sense:

• The same response can be used for multiple contacts, e.g., translation, inventory.
• The same response for a single contact will be used in multiple places, e.g. multiple places of a template.

To disable caching, set the Caching TTL to -1.

Saving the API

You can save a dataset at any time. After saving, clicking on Run will make a call to the API, using any specified Test Values for parameters. The result will be displayed above the endpoint configuration. After you are finished setting up the dataset, it will need to be published in order for it to become accessible as a content source under the Lookups tab in the content builders. Simon will complete this step for you once you have determined that the API is ready to be set live.

Using real-time content

After the dataset is published, it can be used as a content source. The API will appear under the Lookups tab in the content builder and custom context editor. Clicking on a property for the lookup will insert the jinja code with the specified API parameters. If you specified a source for Dynamic Values in your dataset, those will be automatically included. If not, the supplied static Test Values will be inserted instead.

Making an API call takes a dictionary-like object in the format {'key': 'customer_attribute'} as the lookup key which would look like this in Jinja {{ lookups.api_dataset_name[{'key':'customer_attribute'}].field1 }}.