Guides

Managing Data Connections

Suggest Edits

Managing data in your Data Connections ensures your campaigns in Optimove stay accurate and up-to-date. Whether you’re updating customer profiles, deleting outdated records, or setting expiration rules, this guide helps you maintain your Data Connections efficiently. Learn how to handle data expiration, update or delete items by primary key, and upload new data.

Prerequisites

Before you begin, ensure you have:

ℹ️

Note: Replace YOUR_API_KEY and YOUR_BRAND_UUID in examples with your actual x-api-key and x-brand-key values.

Data Expiration

Data in a Data Connection can expire under two conditions:

  • Connected to a 3rd Party API:
    • If a Time-to-Live (TTL) value is set (greater than 0), data fetched from the external API is cached for the specified TTL (in seconds) and expires afterward. For example, a TTL of 3600 means data expires after 1 hour.
    • If the TTL is set to 0, data is not cached and expires immediately after use.
  • Uploaded via API:
    • When uploading data, you can specify a TTL (in seconds) in the request. The data expires after this duration. For example, a TTL of 86400 means data expires after 1 day.
    • If the ttl field is omitted or set to null, the data does not expire.

💡

Tip: Use a TTL of 3600 (1 hour) for frequently updated 3rd party data, or 86400 (1 day) for uploaded data that changes daily.

Update Items by Primary Key

Update or overwrite existing data using the Update Data endpoint. Specify the primary_key, updated data, and an optional ttl.

Example: Update Data

curl --request PUT \
  --url https://api.opti-x.optimove.net/api/data-connections/v1/connections/41ddf098-90b4-4a5d-a3d1-0fd8da3bfb89/update_data \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-brand-key: YOUR_BRAND_UUID' \
  --data '[
    {
        "primary_key": 54490,
        "data": {"key": "value"},
        "ttl": null
    }
]'

Response

A successful update returns a confirmation:

{
    "status": "success",
    "updated_records": 1
}

ℹ️

Note: Setting ttl to null means the updated data does not expire. Specify a TTL (in seconds) if you want the data to expire (e.g., 86400 for 1 day).

For more details, refer to the API Reference.

Diagram showing the workflow for updating data in a Data Connection using the PUT /update_data endpoint.

Figure 1: Workflow for updating data in a Data Connection.

Delete Items by Primary Key

Delete specific data by providing a list of primary_keys using the Delete Data endpoint.

Example: Delete Data

curl --request POST \
  --url https://api.opti-x.optimove.net/api/data-connections/v1/connections/41ddf098-90b4-4a5d-a3d1-0fd8da3bfb89/delete_data \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-brand-key: YOUR_BRAND_UUID' \
  --data '{
    "primary_keys": ["4942985", "2", "1e6bbf91"]
}'

Response

A successful deletion returns a confirmation:

{
    "status": "success",
    "deleted_records": 3
}

Upload Data

To upload new data to your Data Connection, follow the steps outlined in these guides:

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.

Use Case

Suppose you’re managing customer data for a loyalty program in Optimove. You upload customer purchase amounts to a Data Connection but later need to update a customer’s purchase_amount after a return (using update_data). Additionally, you delete inactive accounts (using delete_data) to keep your data current. Finally, you set a TTL of 86400 seconds (1 day) for the updated data to ensure it expires if not refreshed.

Troubleshooting

Common issues and solutions:

  • Authentication Error (401): Verify your x-api-key and x-brand-key are correct and not expired. Regenerate them from the Opti-X UI.
  • Invalid Primary Key (400): Ensure the primary_key exists in the Data Connection. Check your primary_keys list for typos or invalid entries.
  • Rate Limit Exceeded (429): Slow down your requests or contact support to increase your rate limit.

Updated 3 months ago