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`
`to`	Yes	End of the date range (ISO 8601), e.g. `2024-01-02T00:00:00Z`
`include`	No	Comma-separated list of datasets to export. Default: all. Valid values: `engagement`, `customer`, `turn`, `review`, `agent`
`contact`	No	Email or phone number to filter by a specific customer profile

Constraints

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

from must be before to

Response (200)

{
  "exportId": "a1b2c3d4-...",
  "statusUrl": "api/v1/export/a1b2c3d4-.../status"
}

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

customer (customers.csv)

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

turn (turns.csv)

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

review (reviews.csv)

Column	Description
`pid`	Review ID
`engagement_pid`	Reviewed engagement ID
`turn_pid`	Reviewed turn ID (if applicable)
`reviewer_pid`	Reviewer ID
`reviewer_name`	Reviewer name
`question_pid`	Question ID
`question_name`	Question text
`review_time`	Timestamp
`review_session_id`	Review session ID
`status`	Review status
`sampling`	Sampling method
`type`	Review type
`kind`	Review kind
`answer_pid`	Answer ID
`answer_name`	Answer text
`answer_reason_pid`	Answer reason ID
`answer_reason`	Answer reason text
`confidence`	Confidence score
`score`	Score
`answer_score`	Answer score
`worst_score`	Worst possible score
`best_score`	Best possible score
`comment`	Reviewer comment
`comment_translated`	Translated comment
`comment_language`	Comment language
`comment_translated_language`	Translated language
`verified`	Whether verified
`verified_by`	Verified by
`verification_comment`	Verification comment
`answer_type`	Answer type
`version`	Version
`form_id`	Form ID
`engagement_start_time`	Engagement start time
`agent_pid`	Agent ID

agent (agents.csv)

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

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

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)

Example

POST `/api/v1/export`

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

GET `/api/v1/export/history`