Core concepts - Synthesys Docs

How agents, voices, phone numbers, calls, conversations, contacts, campaigns and your wallet relate to each other.

An agent uses a phone number to call someone. That call produces a call log and usually a recording. Your wallet pays for it.

Who makes the call

AgentsThe AI that holds the conversation. Read-only through the API.VoicesCloned voices an agent can speak with. Read-only through the API.Phone numbersThe numbers your agents call from. Read-only through the API.

What a call produces

CallsPOST /v1/calls accepts one outbound call and returns a callId you can track from that moment.ConversationsThe thread with one contact, including its status and extracted fields. Not every outbound call creates one.Call logsThe record of one call that ran: duration, outcome, summary and transcript.RecordingsThe audio for a call log, available through a signed download link.

A call and a call log are different records with different IDs. A call exists as soon as you request it, and it ends as completed or failed. A call log exists once the call has run. Its directCallId points back to the call.

Who gets called

ContactsThe people you call. Create, update and delete them through the API.AudiencesGroups of contacts, static or matched by conditions. Create and manage them through the API.CampaignsAn agent calling an audience from one number. Read-only through the API.

What pays for it

WalletYour prepaid balance and its transaction history.BillingYour usage by type and the current unit prices.

Before a queued call is dialed, a hold for its maximum duration is placed on your wallet. If the hold can't be covered, the call fails with the failure_code insufficient_balance.

The life of a call

POST /v1/calls checks the request, the agent and the phone number. A problem at this stage returns an error, and nothing is queued.
An accepted call returns 201 with a callId. Its status is queued.
The call waits for the recipient's calling hours and a free line, then funds are held. Its status is dialing.
The call goes out. Its status is in_progress.
The call ends as completed or failed. A failed call has a failure_code that says why.

Read the status at any point with GET /v1/calls/{id}. See Calls.

How the IDs connect

These fields link the resources. Field casing differs between resources, so use the names exactly as shown.

Resource	Field	Points to
Agent	`voiceCloneId`	Voice
Agent	`knowledgeBaseId`	Knowledge base
Agent	`followUpSequenceId`	Follow-up sequence
Phone number	`assignedAgentId`	Agent
Call	`agent_id`	Agent
Call	`phone_number_id`	Phone number
Conversation	`agentId`	Agent
Call log	`agent_id`	Agent
Call log	`directCallId`	Call (its `id`)
Recording	`call_log_id`	Call log (its `call_id`)
Campaign	`assistant_id`	Agent
Campaign	`audience_id`	Audience
Campaign	`phone_number_id`	Phone number

Audiences link to contacts directly. GET /v1/audiences/{id}/members returns contact objects.

provider_call_id appears on calls, call logs and recordings. It is the same ID on all three, so quote it when you ask about a call.

Where to set things up

The API doesn't create agents, voices, phone numbers or campaigns. Set those up in the dashboard, then use the API to run calls and read results.