Ingest API

Ingest API

We provide Ingest API that enables you to enhance existing data in Salted CX with attributes and facts that are important for your business. You can also use the Ingest API to integrate Salted CX with a platform that is not supported out of the box by Salted CX.

Before You Start

Before you start it is good to have understanding of these topics:

  • Logical Model — enables you to understand the data structure expected by Salted CX. The Ingest API expects the data that matches the Logical Model and individual files uploaded to Salted CX represent items in individual data sets.
  • Ingest Data Format — enables to understand file naming convention, file format and supported values in the uploaded file.

Get Access to Ingest API

Access to Ingest API requires these information that you need to ask us via [email protected]:

  • Account ID — UUID that is unique identifier of the customer account and the associated domain
  • Secret API Key — long random characters that authorize your code to upload the data
  • Source ID — UUID that identifies the data source. We recommend to ask for separate Source IDs if you have multiple implementations that provide data via Ingest API from different sources.

The above information is all you need to upload data to Salted CX. Keep these information is a secure storage such as AWS Secrets Manager or its equivalent in a different infrastructure. Although Only Secret API Key is sensitive we recommend that you do not use any of these in you code and retrieve it via environmental variables or directly from a secrets management service.

Upload Process

The upload process has these steps:

  1. Prepare the data into a batch of compressed JSONL files to a single ZIP file. Check ingest data format for details on the format of the JSONL files.
  1. Request upload link from the Ingest API. This requires passing the authorization token in the request headers.
curl --location 'https://api.eu.salted.cx/api/v1/ingest/upload-url' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Secret API Key>' \
-d '{
          "ingestionSourceId":<Source ID>"
    }'
  1. Upload the prepared ZIP file from step 1 to the upload link retrieved in step 2 using HTTP PUT method.
curl --location --request PUT '<Upload link from step 2>' \
--data-binary '@/<Path to ZIP file from step 1>'

Uploading Media for Attachments

Turns can reference attachments such as images, PDFs and other files (for example files attached to emails). If the attachment files are not already stored in an S3 bucket that Salted CX can read (see the Access to Recordings section below), or they are only available behind short-lived URLs or on-premise, you can upload them directly to Salted CX before ingesting the turns that reference them.

The media upload process has these steps:

  1. Request a signed upload URL from the Ingest API for each file. Pass the authorization token in the request headers and the MIME type of the file in the body.
curl --location 'https://api.eu.salted.cx/api/v1/ingest/media/upload-url' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Secret API Key>' \
-d '{
      "mimeType": "application/pdf"
    }'

The response contains the following fields:

  • url — presigned URL to upload the file to using HTTP PUT.
  • mediaPid — UUID identifying the media. Use it as the attachment pid when ingesting the turn.
  • path — relative path of the file within your account storage. Use it as the attachment path when ingesting the turn.
{
  "url": "https://<presigned-upload-url>",
  "mediaPid": "2e021b2e-c98d-4152-8a6c-34fe39dbcc2c",
  "path": "year=2026/month=03/day=12/2e021b2e-c98d-4152-8a6c-34fe39dbcc2c.pdf"
}
  1. Upload the file to the presigned URL using HTTP PUT. Set the Content-Type header to the same MIME type you requested in step 1.
curl --location --request PUT '<url from step 1>' \
-H 'Content-Type: application/pdf' \
--data-binary '@/path/to/file.pdf'
  1. Reference the uploaded media as an attachment of a turn in turn.jsonl. Use the returned mediaPid as the attachment pid and the returned path as the attachment path. See the Turn section in Ingest Data Format for the full attachment format.
ℹ️
The presigned upload URL is short lived. Request it shortly before uploading the file. You only need to upload a given file once — you can then reference the same mediaPid/path from multiple turns.

Access to Recordings

If you want users to playback recordings from the customer journey.

Salted CX needs permissions to read the files from S3.

Follow AWS documentation to provide S3 folder permissions with Salted CX account.

Best Practices

Use a dedicated account for testing purposes if your integration is not yet thoroughly tested. Currently the API supports only additive changes of data or modification of existing data. In case you need to delete data please reach to use [email protected].

Limits

The API has the following limits:

  • Maximum size of a single batch is 1GB
  • Maximum number batches per 15 minute is 1,000
  • Total data size uploaded in 15 minutes is 10GB

Pricing

Adding data using Ingest API influences costs as it creates engagements and other data set items that may impact the overall price for Salted CX.

Ingest Data Format

Ingest Data Format

Export API

Export API