POST
Create Outbound Call

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

One phone call: who to dial, from which of your numbers, and what runs.

vars comes from AgentPlanRequest and lasts exactly as long as this call.

from_phone_number_id
string<uuid>
required
to
string
required
agent
AgentConfig · object | null

A complete agent definition, run for this call and stored nowhere. Mutually exclusive with agent_id.

agent_id
string<uuid> | null

An agent in this workspace. Mutually exclusive with agent.

agent_override
AgentOverride · object | null

Changes layered on top of whichever base was named. Absent keys keep the base value, an explicit null clears the field, objects deep-merge and lists replace.

agent_team
AgentTeam · object | null

Run several agents on this call, defined here. Mutually exclusive with agent_id / agent / agent_version / agent_override.

agent_version

Which version of agent_id to run. Omit for the published one. "draft" runs the unpublished working copy — validated and tool-pinned at request time, and refused with the publish errors if it does not hold together.

userdata
Userdata · object | null
vars
Vars · object | null

Values for the variables the agents on this session declare, read as {{vars.name}} in a prompt, a greeting and a tool. They override each agent's declared default and reach every agent the session runs, including a handoff target. Unlike userdata, which describes the PERSON and is kept on their contact record, these describe THIS session and are gone with it. Strings only; an empty string is a deliberate blank, not a request for the default. The model can see them, so put credentials in a workspace secret and read {{secrets.NAME}} from a tool instead.

Response

Successful Response

conversation_id
string<uuid>
required
session_id
string<uuid>
required
status
string
required
agent_version
integer | null
warnings
string[]