Conversations - Synthesys Docs

A conversation is a thread between one agent and one contact phone number. Conversations are read-only through this API. For transcripts, use call logs.

Endpoint	Request
List conversations	GET`/v1/conversations`
Get a conversation	GET`/v1/conversations/{id}`

The conversation object

Fields are in camelCase. The ID field is threadId, not id.

Attributes

threadIdstringrequired

The conversation's UUID.

agentIdstringrequired

The agent in this conversation.

contactPhonestringrequired

The contact's phone number.

assignedPhoneNumberstring

The phone number the agent used. Left out when there is none.

statusstringrequired

pending, active, completed, failed or transferred.

outcomeCategorystring

The conversation's outcome category. Left out when there is none.

channelsstring[]required

The channels used, such as voice. Empty when none are recorded.

tagsstring[]required

Tags on the conversation. Empty when there are none.

extractedFieldsobjectrequired

Values extracted from the conversation, as key and value pairs. Empty when there are none. Keys that look like internal identifiers, such as user_id, are left out.

createdAtstringrequired

When the conversation was created, as an ISO 8601 timestamp.

updatedAtstringrequired

When the conversation last changed, as an ISO 8601 timestamp.

List conversations

GET/v1/conversationsread key

Returns your conversations, newest first. Deleted conversations are left out.

Query parameters

limitintegerdefault 50

Maximum results, from 1 to 100.

offsetintegerdefault 0

Number of results to skip, up to 1,000,000.

agent_idstring

Only return conversations for this agent's UUID.

Errors

Status	When
`400`	`limit`, `offset` or `agent_id` is invalid. `details.issues` names the field.

Request

curl "https://backend.synthesys.app/api/v1/conversations?limit=10&agent_id=6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "threadId": "4d3c2b1a-0f9e-4d8c-b7a6-5e4d3c2b1a0f",
      "agentId": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
      "contactPhone": "+12025550123",
      "assignedPhoneNumber": "+15555550199",
      "channels": ["voice"],
      "tags": [],
      "extractedFields": {},
      "status": "completed",
      "createdAt": "2026-10-31T14:02:12.103Z",
      "updatedAt": "2026-10-31T14:05:20.511Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Get a conversation

GET/v1/conversations/{id}read key

Returns one conversation. The response doesn't include its messages.

Path parameters

idstringrequired

The conversation's threadId.

Errors

Status	When
`400`	The ID isn't a valid UUID.
`404`	No conversation with this ID exists on your account. `code` is `NOT_FOUND`.

Request

curl https://backend.synthesys.app/api/v1/conversations/4d3c2b1a-0f9e-4d8c-b7a6-5e4d3c2b1a0f \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "threadId": "4d3c2b1a-0f9e-4d8c-b7a6-5e4d3c2b1a0f",
    "agentId": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
    "contactPhone": "+12025550123",
    "assignedPhoneNumber": "+15555550199",
    "channels": ["voice"],
    "tags": [],
    "extractedFields": {},
    "status": "completed",
    "createdAt": "2026-10-31T14:02:12.103Z",
    "updatedAt": "2026-10-31T14:05:20.511Z"
  }
}