Skip to content

Create a voice agent or twin

POST
/voice/agents

Create a new voice agent or twin bound to the caller’s org.

Org is pinned server-side from the API key. created_by_email is likewise pinned to the calling principal (str(user.id), the same identifier POST /voice/dialer/sessions uses for user_email) - it is never read from the request body, since an org-wide API key has no independent human identity to attribute a twin to beyond the key itself.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Body for creating a voice agent or twin.

Org is pinned server-side from the API key - never read from the body. created_by_email is likewise pinned to the calling principal (used upstream for one-twin-per-user enforcement and SDR/booking attribution); an org-wide API key has no per-human identity to attribute to beyond the key itself, so it is set to the same identifier the dialer-session and call routes already use for user_email.

Deliberately NOT exposed here (follow-up, not an oversight): twin-only fields tone_profile, channels, and persona_source_user_id. They only apply when entity_type="twin" and none of this PR’s priority surfaces (ad-hoc call, dialer sessions, dispositions) need them.

object
agent_id
Any of:
string
agent_status

Initial status.

string
default: active
Allowed values: active inactive archived
entity_type

“agent” or “twin”.

string
default: agent
Allowed values: agent twin
identity
required

Communication-channel identity for a voice agent (mirrors V2 IdentityV2).

object
avatar_url
Any of:
string
calendar
Any of:
integer
phone
Any of:
string
voice
Any of:
string
is_template

Save this as a reusable template rather than a live agent.

boolean
knowledge
Any of:

Knowledge-collection attachments for a voice agent.

object
collections

Collection IDs (max 4).

Array<string>
persona
required

Persona / prompt configuration for a voice agent (mirrors V2 PersonaV2).

object
agent_name
required

Display name of the agent.

string
assertiveness_level
required

0.0=passive, 1.0=assertive.

number
<= 1
company_name_pronunciation
Any of:
string
conciseness_level
required

0.0=verbose, 1.0=brief.

number
<= 1
description
required

Brief summary of the agent’s purpose.

string
formality_level
required

0.0=casual, 1.0=formal.

number
<= 1
inbound_instructions
Any of:
string
outbound_instructions
Any of:
string
outbound_voicemail_prompt
Any of:
string
persona
required

Personality and behavior description.

string
role
required

Agent role (e.g. “SDR”, “AE”, “Receptionist”, “CSM”).

string
template_id
Any of:
string
use_company_knowledge

Also draw on the org-wide knowledge base.

boolean
default: true

Responses

201

Successful Response

object
data
required

Envelope for single-agent operations (create / get / update).

object
agent
Any of:

Complete agent configuration, as returned by create/get/update.

object
agent_id
required
string
agent_status
required
string
created_at
Any of:
created_by_email
Any of:
string
entity_type
required
string
id
required
integer
identity
required

Communication-channel identity for a voice agent (mirrors V2 IdentityV2).

object
avatar_url
Any of:
string
calendar
Any of:
integer
phone
Any of:
string
voice
Any of:
string
is_template
required
boolean
knowledge
required

Knowledge-collection attachments for a voice agent.

object
collections

Collection IDs (max 4).

Array<string>
org_id
required
string
persona
required

Persona / prompt configuration for a voice agent (mirrors V2 PersonaV2).

object
agent_name
required

Display name of the agent.

string
assertiveness_level
required

0.0=passive, 1.0=assertive.

number
<= 1
company_name_pronunciation
Any of:
string
conciseness_level
required

0.0=verbose, 1.0=brief.

number
<= 1
description
required

Brief summary of the agent’s purpose.

string
formality_level
required

0.0=casual, 1.0=formal.

number
<= 1
inbound_instructions
Any of:
string
outbound_instructions
Any of:
string
outbound_voicemail_prompt
Any of:
string
persona
required

Personality and behavior description.

string
role
required
string
template_id
Any of:
string
updated_at
Any of:
use_company_knowledge
required
boolean
message
Any of:
string
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string