Using your Data Connections

Data Connections enable you to power personalized campaigns in Optimove by integrating static or dynamic data. This guide shows you how to upload data to a Data Connection and use Data Connection Formulas to deliver tailored content in Optimove Personalize Banners and Optimove Channels, such as emails or SMS. Whether you're managing customer profiles or real-time data, these steps will help you enhance your marketing efforts.

Prerequisites

Before you begin, ensure you have:

• An Optimove Personalize account and authentication keys (x-api-key and x-brand-key) from the Optimove Personalize UI.
• A Data Connection created via the POST /connections endpoint, with a unique data_connection_uuid. See the Data Connections Guide for details.
• Tools like cURL, Postman, or a programming language (e.g., Python, JavaScript) for API requests.

Upload Data to a Data Connection

The POST /connections/{data_connection_uuid}/upload_data endpoint allows you to insert up to 5000 JSON objects into a Data Connection, such as customer profiles or product data.

Note: Update and Upload share the same complete‑replacement behaviour (fields you don’t send are removed). Please review the Safe Usage Guidelines before running updates.

Request Body Breakdown

Each JSON object must include a field matching the primary key specified when creating the Data Connection (e.g., id).

Example: Basic Data Upload

Upload two customer records to a Data Connection with id as the primary key.

curl -X POST "http://api.opti-x.optimove.net/api/data-connections/v1/connections/{data_connection_uuid}/upload_data" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "x-brand-key: YOUR_BRAND_KEY" \
     -d '{
         "data": [
             {"id": 1, "name": "John Doe"},
             {"id": 2, "name": "Jane Smith"}
         ]
     }'

 

Notes

• Replace {data_connection_uuid} with your Data Connection’s UUID.
• The Content-Type header must be application/json.
• See the API Reference for full details.

Example: Batching Large Uploads

For uploads exceeding 5000 records, use batch_uuid and set batch_completed to false until the final request.

First batch (partial)

curl -X POST "http://api.opti-x.optimove.net/api/data-connections/v1/connections/{data_connection_uuid}/upload_data" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "x-brand-key: YOUR_BRAND_KEY" \
     -d '{
         "data": [{"id": 1, "name": "John Doe"}],
         "batch_uuid": "123e4567-e89b-12d3-a456-426614174000",
         "batch_completed": false
     }'

Second batch (partial)

curl -X POST "http://api.opti-x.optimove.net/api/data-connections/v1/connections/{data_connection_uuid}/upload_data" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "x-brand-key: YOUR_BRAND_KEY" \
     -d '{
         "data": [{"id": 2, "name": "Jane Smith"}],
         "batch_uuid": "123e4567-e89b-12d3-a456-426614174000",
         "batch_completed": false
     }'

Final batch (complete)

curl -X POST "http://api.opti-x.optimove.net/api/data-connections/v1/connections/{data_connection_uuid}/upload_data" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "x-brand-key: YOUR_BRAND_KEY" \
     -d '{
         "data": [{"id": 3, "name": "Fred Albert"}],
         "batch_uuid": "123e4567-e89b-12d3-a456-426614174000",
         "batch_completed": true
     }'

Figure 1: Upload data in batches to manage large datasets efficiently.

Integrate with Optimove Personalize Banners and Optimove Channels

Once your Data Connection is set up with uploaded data or an external API, use Data Connection Formulas to fetch personalized content for Optimove Personalize Banners (e.g., dynamic website banners) or Optimove Channels (e.g., email, SMS).

Create a Data Connection Formula

A formula specifies how to query a Data Connection and extract a field. It has five segments separated by colons: DC_{UUID}:{primary_key}:{API_parameters}:{return_field}:{fallback_value}.

Steps:

• Identify your Data Connection’s data_connection_uuid from the Optimove Personalize UI.
• Define the primary_key structure (e.g., [%CUSTOMER_ID%] for a personalization tag).
• Specify API_parameters for placeholders in API-based Data Connections (e.g., filter=active_users). Leave empty (::) if not applicable.
• Choose the return_field to extract (e.g., product_url).
• Set an optional fallback_value for errors (e.g., default_url).
• Add the formula in the Optimove Personalize UI under Banners or Channels settings.

Example: Upload-Based Formula:
Fetch a product URL for a customer from uploaded data:

DC_9ce27b8c-8b16-427a-8d00-f40b816bc092:[%CUSTOMER_ID%]::product_url:default_url

• DC_9ce27b8c-8b16-427a-8d00-f40b816bc092: Data Connection UUID.
• [%CUSTOMER_ID%]: Primary key using a personalization tag.
• ::: Empty API parameters.
• product_url: Field to return.
• default_url: Fallback value.

Example: API-Based Formula:
For an API-based Data Connection with a {filter} placeholder:

DC_9ce27b8c-8b16-427a-8d00-f40b816bc092:[%CUSTOMER_ID%]:filter=active_users:product_name:default_product

Use Case

Upload customer purchase history to a Data Connection and use a formula to display personalized product recommendations in an Optimove email campaign, such as a product_url for recently viewed items.

Troubleshooting

Common issues and solutions:

• Invalid JSON Format (422): Ensure each object in data includes the primary key and is valid JSON. Check for missing commas or brackets.
• Exceeding 5000-Record Limit: Split large uploads into multiple requests using batch_uuid and batch_completed.
• Authentication Error (401): Verify your x-api-key and x-brand-key are correct and not expired. Retrieve new keys from the Optimove Personalize UI.
• Formula Errors: Ensure all placeholders in API-based formulas are provided in the API_parameters segment and match the Data Connection’s configuration.