Skip to main content
POST
Create Outbound Call

Authorizations

Authorization
string
header
default:$CARTESIA_API_KEY
required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

Cartesia-Version
enum<string>
default:2026-03-01
required

API version header.

Available options:
2026-03-01
Example:

"2026-03-01"

Body

application/json

Request body for starting outbound calls from an agent phone number.

from_number_id
string
required

Phone number ID to place calls from. The attached provider handles outbound calling for this number.

agent_id
string
required

Agent that handles the outbound calls.

outbound_calls
AgentOutboundCallItem · object[]
required

Per-call destination and metadata configuration. Every destination dials immediately, so destinations beyond the organization's agent-call concurrency limit are rejected rather than queued. For larger lists, use POST /agents/calls/batches instead.

Minimum array length: 1
ringing_timeout_seconds
integer

Seconds to wait for the callee to answer before giving up. Omit to use the default (60 seconds).

Required range: 5 <= x <= 80
max_call_duration_minutes
integer

Optional maximum call duration in minutes.

Response

Outbound call requests accepted. Destinations succeed or fail individually, so check each calls entry for an error rather than relying on the status code alone.

calls
AgentOutboundCallItemResponse · object[]
required

Result for one destination, carrying either an agent_call_id or an error.