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 Opti-X 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 Opti-X account and authentication keys (x-api-key and x-brand-key) from the Opti-X 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.

ℹ️

Note: Replace the data_connection_uuid in examples with the UUID from your Data Connection.

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

💡

Tip: For uploads exceeding 5000 records, generate a batch_uuid and set batch_completed to false until the final request to delay querying.

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
     }'

⚠️

Warning: Exceeding the 5000-record limit per request will cause an error. Use batching for large datasets.

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

Integrate with Opti-X 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 Opti-X 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 Opti-X 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 Opti-X 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

ℹ️

Note: For API-based Data Connections, include all placeholder values in the API_parameters segment, using static values or personalization tags.

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 Opti-X UI.
• Formula Errors: Ensure all placeholders in API-based formulas are provided in the API_parameters segment and match the Data Connection’s configuration.