Guides

Data Connections API

Suggest Edits

ℹ️

Note: To enable this feature, request it through our form.

Data Connections enable you to integrate static or real-time data into Optimove using APIs. You can upload CSV or JSON files for stable datasets, like customer profiles, or connect to external APIs for dynamic data, such as real-time inventory. This guide provides step-by-step instructions to set up and manage Data Connections, with full endpoint details in the API Reference.

Prerequisites

Before you begin, ensure you have the following:

  • An Opti-X account. This will be set up for you after you request the feature.
  • Authentication keys (x-api-key and x-brand-key) from the Opti-X UI under Developer Tools.
  • Tools like cURL, Postman, or a programming language (e.g., Python, JavaScript) for making API requests.

ℹ️

Note: You don't need an Opti-X license to use this feature.

Screenshot of Opti-X UI showing where to find authentication keys.
Figure 1: Locate your x-api-key and x-brand-key in the Opti-X UI Developer Tools section.

Choosing a Data Connection Type

Data Connections come in two types, each suited for different use cases:

  • Upload-Based Data Connection: Best for static data that updates infrequently, such as customer profiles or product catalogs. Upload CSV or JSON files to store data directly in Optimove.
  • API-Based Data Connection: Ideal for dynamic, real-time data, like inventory levels or personalized recommendations. Connect to an external API to fetch data when queried.

💡

Tip: Use upload-based Data Connections for weekly updates and API-based ones for real-time needs.

Create a Data Connection

You can create a Data Connection to store uploaded data or connect to an external API. Follow these steps to get started.

Upload-Based Data Connection

  1. Log in to the Opti-X UI and navigate to Developer Tools to retrieve your x-api-key and x-brand-key.
  2. Prepare your Data Connection details, including a name, a primary key (e.g., user_id to uniquely identify records), and an optional description.
  3. Use the API to create the Data Connection. See the API Reference for the POST /connections endpoint details.
  4. Verify the response includes a unique data_connection_uuid for your new connection.

ℹ️

Note: The primary key cannot be changed after creation, so choose it carefully.

API-Based Data Connection

Request Body Breakdown

The POST /connections endpoint requires a request body with the following fields:

  • name (str): The name of the Data Connection.
  • primary_key (str): The primary key field for the Data Connection. Note: This cannot be changed via PUT requests after creation.
  • description (str, optional): A description of the Data Connection.
  • external_api_details (object, optional): Details for the external API for this Data Connection.
    • url (str): The URL of the external API.
    • http_method (str): The HTTP method to use (e.g., GET, POST).
    • headers (object, optional): The headers to send with the API request.
    • body (object, optional): The body of the API request.
    • ttl (int): Time-to-live for the API data in seconds. Set to 0 to not cache API data. The default value is 30 seconds.
    • timeout (int): Timeout for the API request in seconds.
    • retries (int): Number of retries for failed external API requests.
    • is_batch_endpoint (bool): Specifies if this Data Connection will be used to make batch API requests.
    • sample_placeholder_values (object): Key-value pairs to substitute any placeholders in the url, headers, or body in order to make a test call to the external API to validate the given API request details.

Placeholders in API Details

To allow your API to fetch more dynamic or personalized content, the url, headers, and/or body in external_api_details may contain placeholders. These are populated at request time when querying your Data Connection via the /query endpoint and are specified in the following format: {placeholder_key}. For example, if your url is set to https://api.example.com/data?filter={filter}, then {filter} is a placeholder key, and a value for filter must be passed when making the API request to the /query endpoint.

Example: Creating an API-Based Data Connection

Here’s an example of creating a Data Connection that fetches data from an external API with a placeholder:

curl -X POST "http://api.opti-x.optimove.net/api/data-connections/v1/connections" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "x-brand-key: YOUR_BRAND_KEY" \
     -d '{
         "name": "External API Connection",
         "primary_key": "id",
         "description": "Fetches user data from an external API",
         "external_api_details": {
             "url": "https://api.example.com/data?filter={filter}",
             "http_method": "GET",
             "headers": {"Authorization": "Bearer YOUR_TOKEN"},
             "ttl": 60,
             "timeout": 10,
             "retries": 3,
             "is_batch_endpoint": false,
             "sample_placeholder_values": {"filter": "active_users"}
         }
     }'

Steps to Create an API-Based Data Connection

  1. Gather your x-api-key and x-brand-key from the Opti-X UI.
  2. Define your Data Connection details, including a name, primary key, and external API settings (e.g., URL, HTTP method, and optional placeholders for dynamic queries).
  3. Create the Data Connection via the API. Check the API Reference for the POST /connections endpoint.
  4. Confirm the data_connection_uuid in the response.
Diagram showing the workflow of upload-based vs. API-based Data Connections.

Figure 2: Upload-based Data Connections store static data, while API-based ones fetch dynamic data from external APIs.

Manage Data Connections

Once created, you can list, fetch, update, or delete Data Connections to suit your needs.

List All Data Connections

Retrieve a list of all your Data Connections to view their details, such as names and primary keys. Use the API as described in the API Reference for the GET /connections endpoint.

Fetch a Specific Data Connection

Check the details of a single Data Connection by its data_connection_uuid. See the API Reference for the GET /connections/{data_connection_uuid} endpoint.

Update a Data Connection

Modify a Data Connection’s name or description (note: the primary key cannot be changed). Refer to the API Reference for the PUT /connections/{data_connection_uuid} endpoint.

Delete a Data Connection

Remove a Data Connection when it’s no longer needed. Check the API Reference for the DELETE /connections/{data_connection_uuid} endpoint.

⚠️

Warning: Deleting a Data Connection is irreversible and removes all associated data.

Upload and Query Data

After creating a Data Connection, you can upload data to it or query its contents.

Upload Data

For upload-based Data Connections, send CSV or JSON data to store in Optimove. See the API Reference for the POST /connections/{data_connection_uuid}/upload_data endpoint.

Example Use Case: Upload a CSV of customer profiles with fields like user_id, name, and email for weekly campaign targeting.

Query Data

Retrieve data from a Data Connection, either from uploaded files or an external API. Use the API as detailed in the API Reference for the POST /connections/{data_connection_uuid}/query endpoint.

Example Use Case: Query an API-based Data Connection to fetch real-time product availability for a personalized email campaign.

ℹ️

Note: Although querying to ensure the data is present is an option, Optimove performs those checks for you during data retrieval.

Advanced Operations

The Data Connections API supports additional features, such as:

  • Schema Retrieval: View the structure of a Data Connection’s data. See the API Reference for the GET /connections/{data_connection_uuid}/schema endpoint.
  • References Management: Link Data Connections to other resources (e.g., mail, SMS). Check the API Reference for endpoints like POST /connections/{data_connection_uuid}/references.
  • Emarsys Integration: Perform external content lookups for Emarsys campaigns. Refer to the API Reference for the POST /connections/{data_connection_uuid}/external-content/emarsys endpoint.
  • Batch Queries: Query multiple records efficiently. See the API Reference for the POST /connections/{data_connection_uuid}/api_batch_query endpoint.

Troubleshooting

Common issues and solutions:

  • Authentication Error (422): Verify your x-api-key and x-brand-key are correct and not expired. Retrieve new keys from the Opti-X UI.
  • Connection Fails: Ensure the external API URL is accessible and supports the specified HTTP method (e.g., GET, POST).
  • Data Not Found: Confirm the data_connection_uuid is valid and the data has been uploaded or the external API is responding.

Further Reading

Updated 1 day ago