Place an outbound call
const url = 'https://api.caller9.app/v1/studios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/calls';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"to":"+15551234567","destination":"hybrid:1"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Studio ID (UUID).
Request Bodyrequired
Section titled “Request Bodyrequired”object
NANP (US/Canada) number to dial. Any common formatting is accepted, e.g. (555) 123-4567 or +15551234567.
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.)
Request that the caller ID be withheld from the callee.
Example
{ "to": "+15551234567", "destination": "hybrid:1"}Responses
Section titled “Responses”Call placed. Use guid with the /v1/calls/{call}/… actions.
object
The new call’s id.
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.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Missing, invalid, expired or revoked API key.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
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).
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Not found, or belongs to another organization.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Too many requests for this API key. Retry after Retry-After seconds.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Headers
Section titled “Headers”Seconds until the rate-limit window resets.
The carrier rejected the dial (failed to place call).
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}