Skip to main content
POST
Start an outbound agent call

Authorizations

Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Headers

Idempotency-Key
string
required

Required safe-retry key. Identical retries return the original call; a different body returns 409.

Maximum string length: 255

Body

application/json
from_number_id
string
required

Active managed-number ID to present as caller ID.

to
string
required

Supported E.164 destination: North America (+1), India (+91), or Australian geographic/mobile numbers (+61, without the domestic trunk zero). Country policy, destination consent and caller identity remain required. Australian number purchasing is not available; an existing owned source number can be connected separately.

Example:

"+14155550123"

agent_id
string
required

Omni agent that handles the connected call.

use_case
enum<string>
required

Declared calling purpose. Determines consent, identity, CNAM, and policy gates.

Available options:
transactional,
support,
sales,
collections,
survey
max_duration_seconds
integer
default:120

Carrier-enforced maximum duration for integration calls.

Required range: 30 <= x <= 600
client_reference
string

Stable client call identity; requires agent_release_id.

Pattern: ^[A-Za-z0-9:_-]{1,128}$
agent_release_id
string

Client release identifier pinned to this call; requires client_reference.

Pattern: ^[A-Za-z0-9:_-]{1,128}$
stop_requested
boolean

Recover or cancel the same intent without dialing an unstarted call. Requires client_reference. Excluded from the creation fingerprint.

routing_profile
enum<string>
default:balanced
Available options:
quality_first,
balanced,
cost_optimized

Response

Call accepted

version
integer
project_id
string
direction
enum<string>
Available options:
inbound,
outbound
from
string
destination_number_id
string | null
admission_mode
enum<string> | null
Available options:
client,
platform,
null
admission_status
enum<string> | null
Available options:
pending,
accept,
reject,
expired,
null
admission_expires_at
integer | null

Original pre-answer admission deadline, Unix ms.

max_duration_seconds
integer | null
client_reference
string | null
agent_release_id
string | null
stop_requested
boolean
object
string
Example:

"telephony.call"

id
string
Example:

"tcall_..."

from_number_id
string | null
to
string
Example:

"+14155550123"

dialing_mode
string

Present for a parallel human-call group.

Allowed value: "parallel"
destinations
string[]
Required array length: 2 - 4 elements
connected_to
string | null

Destination confirmed by the group connection result; null while unresolved.

lines
object[]
agent_id
string | null
call_type
enum<string>
Available options:
human
user_id
string
forwarding
object
transfer_enabled
boolean
held
boolean

Confirmed hold state of the connected human caller.

hold_pending
boolean

A caller hold/resume effect awaits confirmation.

transfers
object[]
use_case
enum<string>
Available options:
transactional,
support,
sales,
collections,
survey
routing_profile
enum<string>
Available options:
quality_first,
balanced,
cost_optimized
status
enum<string>
Available options:
queued,
dispatching,
ringing,
in_progress,
completed,
failed,
canceled,
dispatch_unknown
attempt_count
integer
Required range: 0 <= x <= 3
max_attempts
integer
Required range: 1 <= x <= 3
failure_reason
enum<string> | null
Available options:
network_unavailable,
congestion,
timeout,
no_answer,
busy,
rejected,
invalid_number,
identity_blocked,
compliance_blocked,
unknown,
null
created_at
integer

Unix ms.

updated_at
integer

Unix ms.

answered_at
integer | null

Unix ms.

ended_at
integer | null

Unix ms.

artifacts
object

Post-call artifact and billing readiness. Included on the single-call detail response. Artifact readiness and network billing readiness are independent; media_not_started means the terminal call never acquired a media session.