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.

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
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
to
string
Example:

"+14155550123"

agent_id
string
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; pending until the media edge finalizes the call.