The export API provides RAW data available in Salted CX so you can import it into your data storage, analytics solution, business intelligence, or AI tools.

The API is intended for low-frequency batch use, such as daily exports. We might restrict access to the API or rate-limit its use due to excessive usage. The API limit for an exported date range is 24 hours. You have to export data in 24 hours batches.

Authentication

All endpoints require a valid API key in the Authorization header:

Authorization: Bearer <your-api-key>

Ask a Salted CX contact person to share the API Key with you in a secure way.

Workflow

Initiate an export via POST /api/v1/export — returns an exportId and a statusUrl

Poll the status via GET /api/v1/export/{exportId}/status until status is COMPLETED

Download the CSV files using the downloadUrls from the completed status response (URLs are valid for 1 hour)

Endpoints

POST `/api/v1/export`

Initiates an asynchronous export. The export runs in the background; use the status endpoint to track progress.

Query Parameters

Parameter	Required	Description
`from`	Yes	Start of the date range (ISO 8601), e.g. `2024-01-01T00:00:00Z`. See Filtering semantics below.
`to`	Yes	End of the date range (ISO 8601), e.g. `2024-01-02T00:00:00Z`. See Filtering semantics below.
`include`	No
`contact`	No	Email or phone number to filter by a specific customer profile

Filtering semantics

For each dataset, a record is exported if either of the following holds:

The engagement linked to the record started in the [from, to) range (engagement.start_time).

The record itself was updated in the [from, to) range (the dataset's own updated_at column — e.g. customer.updated_at, turn.updated_at).

This means the export captures both new activity and changes to previously-existing records (for example, a renamed customer, a re-categorised service, or a reviewed turn whose review was edited) within the window.

Note on mass updates: If a bulk operation touches updated_at on many rows (for example, during a data migration), the export for that window can be substantially larger than usual. The 24-hour range limit bounds the maximum exposure.

Constraints

The date range (to minus from) must not exceed 24 hours

from must be before to

Response (200)

{
  "exportId": 12345,
  "statusUrl": "api/v1/export/12345/status"
}

Property	Type	Description
`exportId`	Long	The ID of the export.
`statusUrl`	String	The URL to poll for the export result.

Errors (400)

Code	Description
`INVALID_DATE_RANGE`	`from` is not before `to`, or range exceeds 24 hours
`INVALID_INCLUDE`	Unknown dataset name in `include`
`EMPTY_INCLUDE`	`include` parameter is present but empty
`CONTACT_NOT_FOUND`	The `contact` value could not be resolved
`NO_CUSTOMERS_FOR_CONTACT`	Contact was found but has no associated customer records

GET `/api/v1/export/{exportId}/status`

Returns the current status of an export job. Once completed, includes presigned download URLs.

Response (200)

{
  "exportId": "a1b2c3d4-...",
  "status": "COMPLETED",
  "downloadUrls": {
    "engagement": "https://s3.eu-..../engagements.csv?...",
    "customer": "https://s3.eu-..../customers.csv?...",
    "turn": "https://s3.eu-..../turns.csv?...",
    "review": "https://s3.eu-..../reviews.csv?...",
    "agent": "https://s3.eu-..../agents.csv?...",
    "service": "https://s3.eu-..../services.csv?..."
  },
  "error": null
}

Status Values

Status	downloadUrls	Description
`PROCESSING`	empty `{}`	Export is running
`COMPLETED`	populated	Files are ready to download (URLs valid for 1 hour)
`FAILED`	empty `{}`	Export failed — see `error` field

404 — Export not found or does not belong to your account.

GET `/api/v1/export/history`

Returns the most recent exports for your account (up to 100).

Response (200): Array of status objects (same shape as the status endpoint).

Datasets & CSV Columns

engagement (engagements.csv)

Column	Type	Description
`pid`	uuid	Engagement ID
`external_id`	string	External system ID
`name`	string	Engagement name
`link`	string	Link to the engagement
`agent_pid`	uuid	Agent ID
`agent_name`	string	Agent name
`contact_pid`	uuid	Customer ID
`contact_name`	string	Customer name
`conversation_start_time`	timestamp	Start of the conversation
`start_time`	timestamp	Start of the engagement
`end_time`	timestamp	End of the engagement
`conversation_id`	uuid	Conversation ID
`conversation_external_id`	string	External conversation ID
`channel_type`	string	Channel type (CHAT, EMAIL, VOICE...)
`direction`	string	Inbound / Outbound
`status`	string	Engagement status
`type`	string	Engagement type
`outcome_type`	string	Outcome type
`service_level`	string	Service level
`terminated_by`	string	Who terminated the engagement
`initiated_by`	string	Who initiated the engagement
`resolution`	string	Resolution
`channel`	string	Channel name
`queue`	string	Queue name
`team`	string	Team name
`department`	string	Department name
`outcome`	string	Outcome name
`outcome_category`	string	Outcome category
`reason`	string	Reason name
`reason_category`	string	Reason category
`case_name`	string	Case name
`platform`	string	Platform name
`source`	string	Source name
`language`	string	Language
`channel_vendor`	string	Channel vendor
`category`	string	Category
`campaign`	string	Campaign
`priority`	string	Priority
`menu_path`	string	Menu path
`flow`	string	Flow name
`service`	string	Service name
`company_contact`	string	Company contact name
`brand`	string	Brand
`topic_category`	string	Topic category
`topic`	string	Topic
`attribute_01` — `attribute_04`	string	Custom attributes
`agent_location`	string	Agent location
`agent_role`	string	Agent role
`agent_organization`	string	Agent organization
`external_agent_name`	string	External agent name
`cost`	decimal	Cost
`engagement_time`	integer	Engagement time (ms)
`focus_time`	integer	Focus time (ms)
`hold_time`	integer	Hold time (ms)
`invitation_time`	integer	Invitation time (ms)
`menu_time`	integer	Menu time (ms)
`preparation_time`	integer	Preparation time (ms)
`wait_time`	integer	Wait time (ms)
`wrap_up_time`	integer	Wrap-up time (ms)
`total_time`	long	Total time (ms)
`engagement_fact_01` — `engagement_fact_03`	decimal	Custom facts
`wait_for_customer_time`	integer	Wait for customer time (ms)
`order_agent_engagements`	integer	Order of agent engagements in conversation
`total_conversation_agent_engagements`	integer	Total agent engagements in conversation
`adaptability`	decimal	AI-scored adaptability
`adherence`	decimal	AI-scored adherence
`clarity`	decimal	AI-scored clarity
`completeness`	decimal	AI-scored completeness
`customer_satisfaction`	decimal	AI-scored customer satisfaction
`empathy`	decimal	AI-scored empathy
`expressed_satisfaction`	decimal	AI-scored expressed satisfaction
`language_skills`	decimal	AI-scored language skills
`persuasion`	decimal	AI-scored persuasion
`severity`	decimal	AI-scored severity
`understanding`	decimal	AI-scored understanding

customer (customers.csv)

Column	Type	Description
`pid`	uuid	Customer ID
`external_id`	string	External system ID
`name`	string	Customer name
`link`	string	Link to the customer
`type`	string	Customer type
`category`	string	Category
`segment`	string	Segment
`organization`	string	Organization
`region`	string	Region
`country`	string	Country
`state`	string	State

turn (turns.csv)

Column	Type	Description
`pid`	uuid	Turn ID
`engagement_pid`	uuid	Parent engagement ID
`turn_time`	timestamp	Timestamp of the turn
`turn_time_relative_ms`	integer	Time relative to engagement start (ms)
`response_to`	uuid	PID of the turn this responds to
`participant`	string	AGENT or CUSTOMER
`type`	string	Turn type
`origin`	string	Origin
`category`	string	Turn category
`duration`	integer	Duration (ms)
`length`	integer	Character length
`sentiment`	decimal	Sentiment score
`confidence`	decimal	Confidence score
`quality`	decimal	Quality score
`external_id`	string	External ID
`content`	string	Turn text content
`content_agent`	string	Agent-side content
`content_customer`	string	Customer-side content
`language_agent`	string	Agent language
`language_customer`	string	Customer language
`language_content`	string	Content language

review (reviews.csv)

Column	Type	Description
`pid`	uuid	Review ID
`engagement_pid`	uuid	Reviewed engagement ID
`turn_pid`	uuid	Reviewed turn ID (if applicable)
`reviewer_pid`	uuid	Reviewer ID
`reviewer_name`	string	Reviewer name
`question_pid`	uuid	Question ID
`question_name`	string	Question text
`question_type`	string	Question type
`question_built_in`	boolean	Whether question is built-in
`question_description`	string	Question description
`question_business_goal`	string	Question business goal
`question_category_pid`	uuid	Question category ID
`question_category_name`	string	Question category name
`review_time`	timestamp	Timestamp
`review_session_id`	string	Review session ID
`status`	string	Review status
`sampling`	string	Sampling method
`type`	string	Review type
`kind`	string	Review kind
`answer_pid`	uuid	Answer ID
`answer_name`	string	Answer text
`answer_reason_pid`	uuid	Answer reason ID
`answer_reason`	string	Answer reason text
`confidence`	decimal	Confidence score
`score`	decimal	Score
`answer_score`	decimal	Answer score
`worst_score`	decimal	Worst possible score
`best_score`	decimal	Best possible score
`comment`	string	Reviewer comment
`comment_translated`	string	Translated comment
`comment_language`	string	Comment language
`comment_translated_language`	string	Translated language
`verified`	string	Whether verified
`verified_by`	string	Verified by
`verification_comment`	string	Verification comment
`answer_type`	string	Answer type
`version`	string	Version
`form_id`	string	Form ID
`engagement_start_time`	timestamp	Engagement start time
`agent_pid`	uuid	Agent ID

agent (agents.csv)

Column	Type	Description
`pid`	uuid	Agent ID
`external_id`	string	External system ID
`name`	string	Agent name
`status`	string	Agent status
`type`	string	Agent type
`hourly_cost`	decimal	Hourly cost
`engagement_cost`	decimal	Per-engagement cost
`team`	string	Team
`department`	string	Department
`location`	string	Location
`organization`	string	Organization
`role`	string	Role
`manager`	string	Manager name

service (services.csv)

Column	Type	Description
`pid`	uuid	Service ID
`external_id`	string	External system ID
`name`	string	Service name
`status`	string	Service status
`partner`	string	Partner name
`partner_manager`	string	Partner manager name
`vertical`	string	Vertical
`region`	string	Region
`country`	string	Country
`tier`	string	Tier
`partner_size`	string	Partner size
`partner_tier`	string	Partner tier
`category`	string	Category
`attribute_01` — `attribute_03`	string	Custom attributes

Example

The example below shows how to run the export from your console or terminal.

# 1. Start export
curl -X POST "https://api.eu.salted.cx/api/v1/export?from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z&include=engagement,turn" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response: {"exportId":"abc-123","statusUrl":"api/v1/export/abc-123/status"}

# 2. Poll status
curl "https://api.eu.salted.cx/api/v1/export/abc-123/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. When status is COMPLETED, download CSVs from the downloadUrls
curl -o engagements.csv "https://s3.eu-....engagements.csv?X-Amz-..."
curl -o turns.csv "https://s3.eu-....turns.csv?X-Amz-..."

Table of contents

Authentication

Workflow

Endpoints

POST /api/v1/export

Query Parameters

Filtering semantics

Constraints

Response (200)

Errors (400)

GET /api/v1/export/{exportId}/status

Response (200)

Status Values

GET /api/v1/export/history

Datasets & CSV Columns

engagement (engagements.csv)

customer (customers.csv)

turn (turns.csv)

review (reviews.csv)

agent (agents.csv)

service (services.csv)

Example

POST `/api/v1/export`

GET `/api/v1/export/{exportId}/status`

GET `/api/v1/export/history`