Outbound calls

1 endpoint. Every path below is relative to the API base URL and already includes the /api/v1 prefix — see conventions for authentication, pagination, errors and idempotency.

	Endpoint
POST	/telephony/calls	Originate an outbound call directly through the carrier after policy, routing, caller-ID and concurrency checks

Endpoints

Originate an outbound call directly through the carrier after policy, routing, caller-ID and concurrency checks

POST/telephony/calls

• No scope is enforced in the handler — any valid key may call it.
• Request body is camelCase (assistantId, phoneNumberId, callerId, answeringMachineDetection, idempotencyKey); the response is snake_case. Also returns 429 on concurrency limit

Request body

Field	Type	Required	Notes
assistantId	string | null	—	max 32 chars
squadId	string | null	—	max 32 chars
phoneNumberId	string | null	—
phoneNumber	string | null	—	max 32 chars
sipTrunkId	string | null	—
customerId	string | null	—	max 32 chars
campaignId	string | null	—	max 32 chars
customer	object	—
customer.number	string | null	—	max 64 chars
customer.name	string | null	—	max 255 chars
to	string | null	—	max 64 chars
callerId	string | null	—	max 32 chars
variables	string[] | null	—
metadata	string[] | null	—
assistantOverrides	string[] | null	—
customSipHeaders	string[] | null	—
answeringMachineDetection	boolean | null	—
recordingMode	disabled · mono · dual_channel · inherit · null | null	—
timeoutSeconds	integer | null	—	min 5. max 600
scheduledAt	string | null	—	date-time
idempotencyKey	string | null	—	max 128 chars

cURL

curl -X POST "$CALLAGENT_API_URL/telephony/calls" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "phoneNumberId": "+40712345678",
       "phoneNumber": "+40712345678",
       "customer": {
         "number": "+40712345678",
         "name": "Support Line"
       },
       "to": "+40712345678",
       "answeringMachineDetection": true,
       "recordingMode": "disabled",
       "timeoutSeconds": 30
     }'

JavaScript

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/calls`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phoneNumberId": "+40712345678",
    "phoneNumber": "+40712345678",
    "customer": {
      "number": "+40712345678",
      "name": "Support Line"
    },
    "to": "+40712345678",
    "answeringMachineDetection": true,
    "recordingMode": "disabled",
    "timeoutSeconds": 30
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

PHP

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/telephony/calls');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'phoneNumberId' => '+40712345678',
    'phoneNumber' => '+40712345678',
    'customer' => [
        'number' => '+40712345678',
        'name' => 'Support Line',
    ],
    'to' => '+40712345678',
    'answeringMachineDetection' => true,
    'recordingMode' => 'disabled',
    'timeoutSeconds' => 30,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

Python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/telephony/calls",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "phoneNumberId": "+40712345678",
      "phoneNumber": "+40712345678",
      "customer": {
        "number": "+40712345678",
        "name": "Support Line"
      },
      "to": "+40712345678",
      "answeringMachineDetection": True,
      "recordingMode": "disabled",
      "timeoutSeconds": 30
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
200	JSON object
201	data-wrapped object

Errors

Status	When it happens
403	Destination policy or an outbound route blocks it, or the caller ID is not owned
404	The given phoneNumberId or sipTrunkId does not exist in this organization
422	Validation failed, no destination was given, or nothing routes to the destination
501	The resolved telephony provider has no outbound-call implementation
502	The carrier rejected or failed the origination request

Example response, generated from the schema:

"string"