The Data Connection Formula

For a Data Connection to work you must follow the correct formula structure:

DC_{UUID}:{primary_key}:{API parameters - Optional}:{return field}:{fallback value - Optional}

Example:

[%DC_efb445ba-bd30-4f86-9dfd-70c650778f:[%LOYALTY_TIER%]::Discount:10%]

Another way to think about the formula is:

DC_{Which Data Connection}:{What is a primary key}:{API parameters for additional filtering - Optional}:{what data to fetch to a template}:{fallback value if there is no data - Optional}

What is a UUID

UUID is a unique identifier for a Data Connection. It allows the system to identify the correct data source to retrieve your content later.

Example: DC_123e4567-e89b-12d3-a456-426614174000

It can be found in the Opti-X UI on a Details page or when created via API.

What is a Primary key structure

A primary key structure is a unique identifier you define for your Data Connection when creating it. Then in the formula builder you link it to the data in Optimove. As a result, the formula includes a Primary key value.

Examples:

[%campaign_id%]

[%user_id%]

[%product_id%]

Based on the primary key value, the formulas are:

• Dynamic: The formula contains one or more personalization tags. Results will be keyed per primary key—meaning they are specific to each user, product, or campaign.
• Static: The formula does not contain personalization tags. Results will be keyed by the formula itself—meaning the same content is returned for all recipients.

What are API Placeholders (optional)

When creating Data Connections from a third-party API, you can use API placeholders to dynamically insert values into your API request. These placeholders allow you to pass additional query parameters beyond just the primary key, making it possible to filter and refine the data returned.

Extra filters that refine the data request (e.g., location, status).

Imagine you have a third-party API that returns product recommendations and includes an additional parameter for user location. You can use a placeholder for the location parameter, which will dynamically populate with each user's specific location at the time of the request.

[DC_123e4567-e89b-12d3-a456-4266140:[%CUSTOMER_ID%]:location=[%CITY%]:product_name:]

Placeholders must be identified when creating a Data Connection via API methods. Read more here.

What is a Return field

This is the content you want to display in your template. Choose a property from the file schema—such as Product Name or Discount—that exactly matches one field in the response/data.

Examples:

ProductURL

ProductName

What is a Fallback (optional)

A Fallback is an optional value that you can set in your Data Connection. It acts as a default or backup value returned in case the data you’re trying to retrieve is unavailable or missing.

Use Cases

You can use Customer Data and General Personalisation tags as Lookup Values in your Data Connections.

Use Case with general tags

In the example below, we have a Data Connection that contains promo codes generated for specific campaigns on a regular basis. The objective is to integrate these promo codes into a template and fetch only the promo codes corresponding to the active campaign.

For this example, your UUID is DC_123e4567-e89b-12d3-a456-426614174000, and campaign_id is your primary key. The data in your connection may look like this:

The lookup is campaign_id and its value is a personalization tag [%CAMPAIGN_ID%], and promocode is the content that the Data Connection will fetch.

Your formula will look like:

[DC_123e4567-e89b-12d3-a456-426614174000:[%CAMPAIGN_ID%]:promocode]

This formula fetches the relevant promo codes for the campaign and integrates it into your template.

Use Case with personalisation tags

For customer-specific data, you can use Customer Attributes as lookups in your Data Connections.

Let’s say you have Recommendations generated by an Opti-X placement, and you want to add product images and product names to your email template. After creating a Data Connection from the recommendations, you can fetch and display the product details dynamically in your message.

For this example, your UUID is DC_123e4567-e89b-12d3-a456-426614174000, and user_id is the primary key, which is the structure used by Opti-X recommendations.

The formula would look like this:

[DC_123e4567-e89b-12d3-a456-426614174000:[%CUSTOMER_ID%]:imageURL]