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
routing_profile
enum<string>
default:balanced
Available options:
quality_first,
balanced,
cost_optimized

Response

Call accepted

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:
carrier_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.