To get this feature - request it through our form.

Data Connections lets you integrate real-time, personalized content from external sources into your Opti-X campaigns and templates. This guide shows you how to set them up using the Opti-X Admin interface or API. Whether you’re uploading CSV or JSON files, connecting existing Placements, or automating with an API, follow these steps to get started.

Through the Opti-X Admin Interface

To create a new Data Connection using the Opti-X Admin interface, navigate to the “Data Connections” page in the Admin interface; this can be found under the “Data” section in the left-hand navigation bar. From this page, you can see all your existing Data Connections and click the “Create Data Connection” button to create a new one.

Clicking the “Create Data Connection” button will launch the Data Connection Wizard, where you must select the data source type you would like to use for your Data Connection.

• Supported Data Connection source types from this method include:
  • Uploading CSV or JSON files
  • Creating a Data Connection powered by an existing Opti-X Placement 

Using API Methods

For more automated and extended capabilities, you are able to use API calls to create and update Data Connections. With API methods your technical team can also set up additional placeholders — special tags that let you pass additional parameters (like location, category, or status) into the data request. 

💡 Tip: We recommend using this option if your content is highly dynamic and updates frequently - such as daily or even hourly. 

Example:

Your dynamic content is organized by Template ID and includes several properties, including  language.

When using API methods to set up your Data Connection, your technical team can configure:

• Template ID as the primary key, and

• Language as an additional API parameter (a dynamic placeholder).

This setup means that when you send a message, the system will query the external source with both the Template ID and the Language, ensuring the content retrieved is not only the right template but also in the correct language for each customer.

Your additional API Placeholder parameters will also require lookup values, personalisation tags, general tags or exact values can be used.

✅ Important:
Even when using API methods, it’s crucial to properly define and understand the Primary Key of your Data Connection. This element will help us to retrieve the content correctly. Read Why Primary Key Matters. A similar concept applies to API Placeholders. 

For more details on creating Data Connections via API please see here.

Creating a New Data Connection Using File Upload

When selecting a file as the data source type of your Data Connection, you can upload a CSV or JSON file in any structure — our system is fully flexible with how your data is organized.

The only constraint is a maximum data size limit of 1 MB per primary key (one unique record). No additional data mapping is required on your part; simply upload the file, and we’ll handle the rest.

First Step. Selecting the file you would like to upload.

Note that Data Connections are only supporting CSV and JSON file types for file uploads.

Second Step. Defining a name and description for the Data Connection.

• This should be a short descriptive name so that you can identify and use the Data Connection later in templates and Opti-X Banners.
• The name has to be unique, no special characters are allowed.

Third Step. Selecting a property that will act as a primary key for this Data Connection.

A primary key is a unique identifier for each piece of data in your file. Think of it like a name tag for every row of data. This tag helps the system know exactly which piece of information you're referring to so it can match and organize everything correctly.

We’ll parse your file and automatically return the available fields you can choose from as a primary key. The structure is flexible — you’re not limited to predefined formats.

Later in this article we cover examples of primary keys and how they are used - dive in. 

For nested JSON files, you will see the file's structure and its parameters at different levels. In this case primary key must not contain nested objects inside.

{
  "product": {
    "id": 123,
    "name": "Soccer Ball",
    "details": {
      "category": "Sports",
      "price": 29.99
    }
  }
}

Fourth Step. Summary is the last step in reviewing the details before saving the new Data Connection.

Once you have clicked the Save button at the end of the creation wizard, Opti-X will begin to upload and process your Data Connection. You will be returned to the “Data Connections” screen where you can see your newly created Data Connection.

Creating a New Data Connection Using Placements

When selecting Placement, you can select an Opti-X placement that has already been created to be the data source for your Data Connection.

First Step. Selecting which placement you would like to use.

Second Step. Defining a name and description for the Data Connection.

• This should be a short descriptive name so that you can identify and use the Data Connection later in templates and Opti-X Banners.
• The name has to be unique, no special characters are allowed.

Third Step. Summary is the last step to review the details before saving the new Data Connection. There is no need to define primary key - it’s defined automatically as a user id.

Editing and Uploading More Data to Existing Data Connection

Actions available for different data source types:

Editing Data Connection

You can manage and edit your Data Connections created through CSV or JSON upload in the UI through the Editor tab.

What You Can Do

1. Edit Files: Work with .csv and .json files directly in the editor.
2. Search: Look up specific data entries quickly.
3. Add Data: Manually insert new rows or data points.
4. Modify Existing Data: Adjust the values in existing rows manually.
5. Delete Rows: Remove rows as needed.
6. Other Actions: Perform basic operations like copy, cut, and paste.

What You Cannot Do

• Add New Fields: It’s not possible to introduce new columns or fields to the dataset within the editor.

Uploading New Data

• Use the Upload tab to add more records to an existing Data Connection.
• Uploaded files will append records by default to the current dataset.
• Click Save to finalize changes. The system will process the new data shortly.

Updating Data via API

Choosing the Right Endpoint

You have two main API endpoints for updating data, and picking the correct one is crucial.

• Update API -PUT/connections/{dc_uuid}/update_data: Use this endpoint to update existing entries only. If the primary key doesn't exist, the API will return a 404 error.
• Upload API - POST/connections/{dc_uuid}/upload_data: This endpoint performs an "upsert" operation. It will create a new entry if the primary key is missing or update the entry if it already exists.

See the API reference for further details: Update Data, Upload Data, Schema, Query.

A Safe Workflow for API Updates

To ensure a smooth and safe update process and prevent accidental data deletion, follow these steps:

1. Get Structure (Optional): You can use the GET /connections/{dc_uuid}/schema endpoint to retrieve the data structure and confirm the field names and types. This optional step is useful for verifying that your update will match the expected format.
2. Get Current Values: Use the POST /connections/{dc_uuid}/query endpoint to retrieve the current entries for the primary keys you plan to change.
3. Build Your Update Object: Start with the full entry you just retrieved. Modify the specific fields you intend to change, but be sure to include all other existing fields to prevent them from being deleted. You can also add any new fields here.
4. Send a Small Test Batch: Before performing a large-scale update, send a small test batch to confirm that the changes work as expected.

Managing Data Connections

When you open the “Data Connections” page in Opti-X you will be presented with a table of all the existing Data Connections that you and other users of your Opti-X brand have previously created.

From this page you can:

• Search and filter your Data Connections by their data source types (File, Placement or API).
• Sort the table by Type, Last Update and Status to find the one you are looking for.
• View Data Connections created via API so you know what else is available to use and when it was last updated.

❓ Why Do I See “0 Rows” in My Data Connection?

Seeing 0 rows is expected behavior for Data Connections created using API methods

This happens because:

• We don’t call the API continuously - the request is only made at the time of execution, such as during message send or placement rendering.

• Until that moment, there’s no preview or stored result to show - so row count remains at 0.

You’ll see the same behavior for Placements, since they’re a productized way of connecting to our Recommend API, which also executes in real time.