Conturi de telefonie

7 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
GET	`/telephony/accounts`	List the tenant's carrier accounts ordered by name, paginated
POST	`/telephony/accounts`	Create a carrier account binding a provider to a stored credential, returning the new account
GET	`/telephony/accounts/{id}`	Fetch one carrier account with its credential binding, health and number-sync state
PATCH	`/telephony/accounts/{id}`	Update a carrier account's name, credential binding, default flag or settings, returning the refreshed row
DELETE	`/telephony/accounts/{id}`	Delete a carrier account
POST	`/telephony/accounts/{id}/health`	Live carrier health check; the result is persisted so the UI can show drift
GET	`/telephony/providers`	The capability matrix (§188). Clients render buttons from this rather than from a hard-coded list

Endpoint-uri

List the tenant's carrier accounts ordered by name, paginated

GET/telephony/accounts

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/telephony/accounts" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/accounts`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

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/accounts');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$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.get(
    f"{os.environ['CALLAGENT_API_URL']}/telephony/accounts",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped array

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    "string"
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "pages": 1
  }
}

Create a carrier account binding a provider to a stored credential, returning the new account

POST/telephony/accounts

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Request body keys are camelCase (e.g. providerCredentialId, externalAccountId, isDefault), not the snake_case the rest of the wire format uses

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`provider`	`twilio` · `telnyx` · `didww` · `plivo` · `zadarma` · `didlogic` …	da	§8.1. The telephony providers CallAgent can terminate or originate through. The value is what is stored in `phone_numbers.provider`, `sip_trunks.provider` and `provider_credentials.provider` — keep them stable, they are persisted.
`name`	string	da	max 255 chars
`description`	string \| null	—	max 500 chars
`providerCredentialId`	string \| null	—
`externalAccountId`	string \| null	—	max 255 chars
`isDefault`	boolean \| null	—
`settings`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/telephony/accounts" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "provider": "twilio",
       "name": "Support Line",
       "isDefault": true
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/accounts`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "provider": "twilio",
    "name": "Support Line",
    "isDefault": true
  }),
});

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/accounts');

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([
    'provider' => 'twilio',
    'name' => 'Support Line',
    'isDefault' => true,
]),
]);

$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/accounts",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "provider": "twilio",
      "name": "Support Line",
      "isDefault": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`data`-wrapped `TelephonyAccount`

Erori

Status	Când apare
`422`	Validation failed, or the referenced provider credential does not exist

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "organization_id": "01JQ0000000000000000000000",
    "provider": "twilio",
    "name": "Support Line",
    "description": "string",
    "provider_credential_id": "01JQ0000000000000000000000",
    "external_account_id": "01JQ0000000000000000000000",
    "external_account_label": "string",
    "is_subaccount": true,
    "parent_external_account_id": "01JQ0000000000000000000000",
    "voice_webhook_url": "https://example.com/hook",
    "status_webhook_url": "https://example.com/hook",
    "sms_webhook_url": "https://example.com/hook",
    "is_default": true,
    "active": true,
    "health_status": "string",
    "health_checked_at": "2026-01-01T12:00:00+00:00",
    "health_message": "string",
    "numbers_synced_at": "2026-01-01T12:00:00+00:00",
    "numbers_count": 1,
    "capabilities": {},
    "settings": {},
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "deleted_at": "2026-01-01T12:00:00+00:00"
  }
}

Fetch one carrier account with its credential binding, health and number-sync state

GET/telephony/accounts/{id}

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/telephony/accounts/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/accounts/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

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/accounts/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$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.get(
    f"{os.environ['CALLAGENT_API_URL']}/telephony/accounts/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped `TelephonyAccount`

Erori

Status	Când apare
`404`	No such account for this tenant

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "organization_id": "01JQ0000000000000000000000",
    "provider": "twilio",
    "name": "Support Line",
    "description": "string",
    "provider_credential_id": "01JQ0000000000000000000000",
    "external_account_id": "01JQ0000000000000000000000",
    "external_account_label": "string",
    "is_subaccount": true,
    "parent_external_account_id": "01JQ0000000000000000000000",
    "voice_webhook_url": "https://example.com/hook",
    "status_webhook_url": "https://example.com/hook",
    "sms_webhook_url": "https://example.com/hook",
    "is_default": true,
    "active": true,
    "health_status": "string",
    "health_checked_at": "2026-01-01T12:00:00+00:00",
    "health_message": "string",
    "numbers_synced_at": "2026-01-01T12:00:00+00:00",
    "numbers_count": 1,
    "capabilities": {},
    "settings": {},
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "deleted_at": "2026-01-01T12:00:00+00:00"
  }
}

Update a carrier account's name, credential binding, default flag or settings, returning the refreshed row

PATCH/telephony/accounts/{id}

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Request body keys are camelCase (e.g. providerCredentialId, externalAccountId, isDefault), not the snake_case the rest of the wire format uses

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	—	max 255 chars
`description`	string \| null	—	max 500 chars
`providerCredentialId`	string \| null	—
`externalAccountId`	string \| null	—	max 255 chars
`isDefault`	boolean \| null	—
`active`	boolean \| null	—
`settings`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X PATCH "$CALLAGENT_API_URL/telephony/accounts/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "isDefault": true,
       "active": true
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/accounts/01JQ0000000000000000000000`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "isDefault": true,
    "active": true
  }),
});

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/accounts/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'isDefault' => true,
    'active' => true,
]),
]);

$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.patch(
    f"{os.environ['CALLAGENT_API_URL']}/telephony/accounts/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "isDefault": True,
      "active": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`404`	No such account for this tenant
`422`	Validation failed, or the referenced provider credential does not exist

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "organization_id": "01JQ0000000000000000000000",
    "provider": "twilio",
    "name": "Support Line",
    "description": "string",
    "provider_credential_id": "01JQ0000000000000000000000",
    "external_account_id": "01JQ0000000000000000000000",
    "external_account_label": "string",
    "is_subaccount": true,
    "parent_external_account_id": "01JQ0000000000000000000000",
    "voice_webhook_url": "https://example.com/hook",
    "status_webhook_url": "https://example.com/hook",
    "sms_webhook_url": "https://example.com/hook",
    "is_default": true,
    "active": true,
    "health_status": "string",
    "health_checked_at": "2026-01-01T12:00:00+00:00",
    "health_message": "string",
    "numbers_synced_at": "2026-01-01T12:00:00+00:00",
    "numbers_count": 1,
    "capabilities": {},
    "settings": {},
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "deleted_at": "2026-01-01T12:00:00+00:00"
  }
}

Delete a carrier account

DELETE/telephony/accounts/{id}

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.
Acest răspuns nu este împachetat în data.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/telephony/accounts/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/accounts/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

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/accounts/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$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.delete(
    f"{os.environ['CALLAGENT_API_URL']}/telephony/accounts/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`204`	No content

Erori

Status	Când apare
`404`	No such account for this tenant

Live carrier health check; the result is persisted so the UI can show drift

POST/telephony/accounts/{id}/health

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`id`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/telephony/accounts/01JQ0000000000000000000000/health" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/accounts/01JQ0000000000000000000000/health`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

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/accounts/01JQ0000000000000000000000/health');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$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/accounts/01JQ0000000000000000000000/health",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	JSON object

Erori

Status	Când apare
`404`	No such account for this tenant
`422`	The account has no provider credential, or the credential is incomplete
`501`	The provider has no adapter implemented
`502`	The carrier rejected the health call
`504`	The carrier could not be reached

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "status": "string",
    "latency_ms": 1,
    "message": "string",
    "details": {}
  }
}

The capability matrix (§188). Clients render buttons from this rather than from a hard-coded list

GET/telephony/providers

Handler-ul nu impune niciun scope — orice cheie validă îl poate apela.

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/telephony/providers" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/telephony/providers`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

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/providers');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$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.get(
    f"{os.environ['CALLAGENT_API_URL']}/telephony/providers",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Exemplu de răspuns, generat din schemă:

json

{
  "data": {}
}

Conturi de telefonie ​

Endpoint-uri ​

List the tenant's carrier accounts ordered by name, paginated ​

Create a carrier account binding a provider to a stored credential, returning the new account ​

Fetch one carrier account with its credential binding, health and number-sync state ​

Update a carrier account's name, credential binding, default flag or settings, returning the refreshed row ​

Delete a carrier account ​

Live carrier health check; the result is persisted so the UI can show drift ​

The capability matrix (§188). Clients render buttons from this rather than from a hard-coded list ​

Conturi de telefonie

Endpoint-uri

List the tenant's carrier accounts ordered by name, paginated

Create a carrier account binding a provider to a stored credential, returning the new account

Fetch one carrier account with its credential binding, health and number-sync state

Update a carrier account's name, credential binding, default flag or settings, returning the refreshed row

Delete a carrier account

Live carrier health check; the result is persisted so the UI can show drift

The capability matrix (§188). Clients render buttons from this rather than from a hard-coded list