Agents - Synthesys Docs

List the voice agents in your account and read their persona, script and settings.

An agent holds the persona, script and call settings used when it answers or places a call. These routes are read-only. Create and edit agents in the dashboard.

To place a call with an agent, pass its id to Calls. To configure one, see Post-call webhooks and Custom functions.

Endpoint	Request
List agents	GET`/v1/agents`
Get an agent	GET`/v1/agents/:id`

The agent object

Most top-level fields use camelCase. Many keys inside scriptDefinition and humanizationSettings use snake_case. Each object holds only the fields listed here, and a field with no value can be left out.

Attributes

idstringrequired

The agent's UUID. Use this ID in every /v1/agents/:id route.

namestringrequired

Same value as personaName.

displayNamestringrequired

The name you use to manage the agent in the dashboard.

personaNamestringrequired

The name the agent uses in conversation.

personaConfigobject | nullrequired

Structured persona details. See below.

slugstringrequired

URL-friendly name. Empty when the agent has none. The /v1 routes accept only id.

statusstringrequired

active or inactive.

typestringrequired

inbound, outbound or hybrid.

baseInstructionsstringrequired

The agent's base instructions. Empty when none are set.

scriptDefinitionobjectrequired

Greetings, prompt settings and call rules. See below.

humanizationSettingsobjectrequired

Behavior settings. See below.

crmFieldsConfigarray | null

CRM fields the agent works with, or null when none are set. Each item can have fieldName, field, label, required, type, fieldType, updateWithAI, possibleValues and aiInstructions.

knowledgeBaseIdstring

UUID of the attached knowledge base. Omitted when none is attached.

followUpSequenceIdstring

UUID of the attached follow-up sequence. Omitted when none is attached.

widgetConfigobject | null

Web widget settings: appearance, behavior, branding, triggers, isActive, created_at and updated_at. null when not set.

voiceCloneIdstring

UUID of the agent's custom voice. Omitted when it doesn't use one.

voicemailMessagestring | nullrequired

The message left on voicemail.

createdAtstringrequired

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

updatedAtstringrequired

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

personaConfig

namestringrequired

The conversational name.

rolestring

The agent's role.

companystring

The company the agent represents.

personalitystring[]

Personality traits.

tonestring

How the agent communicates.

scriptDefinition

tool_messagesobject

What the agent says while it uses its tools.

inbound_introstring

Greeting for inbound calls.

outbound_introstring

Greeting for outbound calls.

callback_introstring

Greeting for callbacks.

qualificationstring[]

Qualification items.

objectionsobject

Objection handling, as a map of objection to response.

closingstring

Closing text.

fallbackstring

Fallback text.

transferConditionsstring[]

Conditions for transferring a call.

transfersarray

Transfer destinations. Each has number, instructions and action, and can have mode, language, operatorMessage, fallbackMessage and countryCode.

base_instructionsarray

Instruction blocks with title, content and optional variant.

prompt_modestring

guided or advanced.

conversation_stepsarray

Guided steps with stepNumber, title, content and order.

advanced_promptstring

The prompt used in advanced mode.

stop_conditionsarray

Conditions for ending a call, with id, title, condition and order.

sms_actionsarray

SMS actions with id, name, triggers, requireConfirmation, messageContent and enabled.

maxDurationSecondsinteger

Maximum call length, in seconds.

first_message_modestring

assistant-speaks-first, assistant-speaks-first-with-model-generated-message or assistant-waits-for-user. inbound_first_message_mode, outbound_first_message_mode and callback_first_message_mode set this per call direction.

start_speaking_planobject

Has waitSeconds. inbound_start_speaking_plan, outbound_start_speaking_plan and callback_start_speaking_plan set this per call direction.

humanizationSettings

booking_enabledboolean

Whether the agent can book appointments.

calendar_configobject | null

The connected calendar, with calendar_name, timezone, assignment_strategy and assigned_user_name.

split_messagesboolean

Whether messages are split up.

message_delaynumber

Message delay, in seconds.

silenceTimeoutSecondsinteger

How long silence can last before a timeout.

interruptionEnabledboolean

Whether the caller can interrupt the agent.

backgroundSoundstring

off, office or custom.

personalityobject | null

Has traits, background and goals.

responseSpeedobject | null

Has typingSpeed and thinkingTime.

smsobject | null

SMS behavior: responseDelay, useEmoji and casualLanguage.

modelobject | null

Has temperature and maxTokens.

voiceobject | null

Has speed, stability, similarity_boost and style.

transcriberobject | null

Has language.

List agents

GET/v1/agentsread key

Returns your agents, newest first. See Pagination.

Query parameters

limitintegerdefault 50

Maximum results, from 1 to 100.

offsetintegerdefault 0

Number of results to skip.

Returns 400 when limit or offset is out of range or isn't digits only.

Request

curl "https://backend.synthesys.app/api/v1/agents?limit=10" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Sarah",
      "displayName": "Inbound sales",
      "personaName": "Sarah",
      "personaConfig": { "name": "Sarah", "role": "sales representative" },
      "slug": "inbound-sales",
      "status": "active",
      "type": "inbound",
      "baseInstructions": "Qualify the caller and book a demo.",
      "scriptDefinition": {
        "inbound_intro": "Hello! How can I help you today?",
        "outbound_intro": "Hello! How can I help you today?",
        "callback_intro": "Hello! How can I help you today?",
        "qualification": [],
        "objections": {},
        "transferConditions": []
      },
      "humanizationSettings": { "calendar_config": null },
      "crmFieldsConfig": null,
      "widgetConfig": null,
      "voicemailMessage": null,
      "createdAt": "2026-10-01T09:30:00+00:00",
      "updatedAt": "2026-10-20T14:05:00+00:00"
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0 }
}

Get an agent

GET/v1/agents/:idread key

Returns one agent by its UUID.

Returns 404 when the agent doesn't exist, was deleted or belongs to another account. An ID that isn't a valid UUID returns 400.

Path parameters

idstringrequired

The agent's UUID.

Request

curl https://backend.synthesys.app/api/v1/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Sarah",
    "displayName": "Inbound sales",
    "personaName": "Sarah",
    "personaConfig": { "name": "Sarah", "role": "sales representative" },
    "slug": "inbound-sales",
    "status": "active",
    "type": "inbound",
    "baseInstructions": "Qualify the caller and book a demo.",
    "scriptDefinition": {
      "inbound_intro": "Hello! How can I help you today?",
      "outbound_intro": "Hello! How can I help you today?",
      "callback_intro": "Hello! How can I help you today?",
      "qualification": [],
      "objections": {},
      "transferConditions": []
    },
    "humanizationSettings": { "calendar_config": null },
    "crmFieldsConfig": null,
    "widgetConfig": null,
    "voicemailMessage": null,
    "createdAt": "2026-10-01T09:30:00+00:00",
    "updatedAt": "2026-10-20T14:05:00+00:00"
  }
}