Skip to main content
POST
Place or schedule a phone call
This capability is in beta. Behavior can change before general availability.
Supply E.164 numbers unless ignoreE164Validation is enabled. scheduledAt must be 60 seconds to 30 days ahead. Selected-resource keys must supply agentId. Use Idempotency-Key to retry safely. Reusing it for different input returns idempotency_key_reuse. An identical replay returns the original result with Idempotent-Replayed: true. Organization call admission and concurrency limits still apply.

Authorizations

Authorization
string
header
required

An API key (tars_sk_…) sent as Authorization: Bearer <key>. Each operation names the permission it needs. Create keys in Settings → Integrations → API keys.

Headers

Idempotency-Key
string

Replays the original answer for 24 hours. The same key with another body returns idempotency_key_reuse.

Required string length: 1 - 255

Body

application/json

Place or schedule a phone call.

fromNumber
string
required
Pattern: ^\+[1-9]\d{6,14}$
toNumber
string
required
Pattern: ^\+[1-9]\d{6,14}$
agentId
string

The voice agent id. Required when the key is limited to selected resources.

Maximum string length: 128
variables
object
metadata
object

At most 16 KB.

customSipHeaders
object
ignoreE164Validation
boolean
default:false

Skip E.164 validation of fromNumber and toNumber to dial internal numbers on an imported SIP trunk.

destinationTimezone
string | null

IANA timezone of the recipient, used for the calling-hours check when the contact has none.

scheduledAt
integer | null

When to place the call, in milliseconds, between 60 seconds and 30 days ahead.

language
string | null

Locale for this call only, for example es-419. It must be one of the agent's languages.

Response

The call was placed.

The call was registered and is being dialled.

callId
string
required
status
any
required
scheduled
any
required
warnings
object[]