Skip to content

Place an outbound call

POST
/v1/studios/{studio}/calls
curl --request POST \
--url https://api.caller9.app/v1/studios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "to": "+15551234567", "destination": "hybrid:1" }'

Dials a North American (NANP) phone number from the studio’s configured outbound caller ID and lands the call on on-air line N once it is answered. The call appears in the live queue immediately (status on-air) and can be moved or ended like any other call, even before the far end answers.

API keys may only use hybrid:N destinations; browser is reserved for signed-in operators and returns 403 for API keys. Requires a full-access key. Not available on demo accounts. The studio must have an outbound caller ID set.

studio
required
string format: uuid

Studio ID (UUID).

Media typeapplication/json
object
to
required

NANP (US/Canada) number to dial. Any common formatting is accepted, e.g. (555) 123-4567 or +15551234567.

string
destination
required

Where the call lands once answered: hybrid:N for on-air line N. (browser is available to signed-in operators only; API keys receive 403.)

string
/^hybrid:\d+$/
privacy

Request that the caller ID be withheld from the callee.

boolean

Example

{
"to": "+15551234567",
"destination": "hybrid:1"
}

Call placed. Use guid with the /v1/calls/{call}/… actions.

Media typeapplication/json
object
ok
required
boolean
guid
required

The new call’s id.

string

Example

{
"ok": true
}

Invalid request. Possible error values: invalid JSON body, invalid NANP number, invalid destination, set an outbound caller ID for this studio in Settings first.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Forbidden: read-only key; API key requested the browser destination (API keys cannot place a call to Browser); or demo account (outbound calling is not available on demo accounts).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.

The carrier rejected the dial (failed to place call).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}