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 secrets from SessionSecretsField; both last 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.

secrets
Secrets · object | null

Secrets for this session only, read by tools as {{secrets.NAME}}; a name here overrides the workspace secret. Never shown to the model or returned.

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 credentials go in secrets (this session's own, where the request takes them) or a workspace secret, read as {{secrets.NAME}} by a tool.

Response

Successful Response

Which call this is, and what resolving it complained about.

session_id
string<uuid>
required
warnings
string[]
required