Call Center API

Everything here lives under /callcenter/* on the same base URL as the rest of the REST API. It’s only available when the server has Telnyx configured (TELNYX_API_KEY set) — if it isn’t, every endpoint below except GET /callcenter/status returns 503. Authentication: every endpoint requires X-API-Key header or ?api_key= query parameter. Authorization: Bearer is not accepted here — see the error catalog note on why this differs from /tts/synthesize and /stt/transcribe. Billing: calls and numbers are paid from the account’s prepaid balance (Pricing and billing). Buying a number and placing calls need a first top-up: before it, those endpoints answer 402 with {"code": "billing.topup_required", "error": "…"}. With less than $0.25 of balance they answer 402 billing.insufficient_balance, and while a payment is disputed, billing.account_disputed. Account scope: every endpoint acts only on the account that owns the key. The agents and numbers you list are your own. Assign, release, dial and bulk-dial work only with numbers you own and agents you own. A number or agent that belongs to another account answers 404 (403 for a from number you don’t own), whether or not it exists. The API needs a key that belongs to an account (401 otherwise).

`GET /callcenter/status` — Provisioning Status

The one endpoint that works even without Telnyx configured — use it to check whether the rest of this API is usable before calling anything else.

Response

{
  "enabled": true,
  "provider": "telnyx"
}

`GET /callcenter/agents` — List Agents

Returns every agent on the account, for populating a “route to agent” picker.

Response

{
  "agents": [
    { "id": "34da7ae3-0d46-4827-8739-ca6a25dc756c", "name": "Front Desk", "voice": "F2", "language": "es" }
  ]
}

`GET /callcenter/numbers/search` — Search Available Numbers

Search the inventory of purchasable numbers, before committing to buy one. Only local numbers are offered, in the US, Spain, the UK, Germany, France, Italy and Portugal; any other country_code returns 400. monthly_cost and upfront_cost in the results are the carrier’s own figures, not what you pay: every Lokutor number is $5 a month from your balance (phone.number_per_month in the rate card).

Query Parameters

Parameter	Type	Default	Description
`country_code`	`string`	`"US"`	ISO country code
`region_code`	`string`	—	State/area code filter (e.g. area code digits)

Response

{
  "numbers": [
    {
      "phone_number": "+14755750358",
      "monthly_cost": "1.00000",
      "upfront_cost": "1.00000",
      "currency": "USD",
      "region": "CT",
      "locality": "RIDGEFIELD"
    }
  ]
}

cURL

curl -s "https://api.lokutor.com/callcenter/numbers/search?country_code=US&region_code=CT" \
  -H "X-API-Key: sk_your_key_here" | jq .

`GET /callcenter/numbers` — List Owned Numbers

Returns every number on the account, merged with its agent binding (if any).

Response

{
  "numbers": [
    { "id": "1234567890", "phone_number": "+14755750358", "status": "active", "connection_id": "2972204047848703963", "agent_id": "34da7ae3-..." }
  ],
  "total": 1
}

`POST /callcenter/numbers` — Buy a Number

Purchases a number you have already found via search — phone_number must be an exact result from /callcenter/numbers/search, not an arbitrary string. There’s no “buy a random number for this country” shortcut; searching first is required.

This rents the number for $5 a month from your balance: the first month is charged when you buy it, then once a month. There’s no confirmation step at the API level; the caller is the confirmation step. Buying a number needs a first top-up (402 billing.topup_required before it) and at least the first month in the balance (402 billing.insufficient_balance). A number whose own carrier price exceeds what a Lokutor number includes is refused with 400 before anything is charged — pick another local number.

If the balance cannot pay a month, the number is kept for 30 days, still answering calls while the balance allows; after that it is released, and a released number cannot be recovered. A call on a number is billed like any agent session (platform time per second and the language model per token) plus the phone line per started minute, by direction and country: a call your agent receives is priced by the country of your number, one it makes (dial, bulk dial) by the destination, landline or mobile. For example, a received call on a Spanish number is

0.035 a minute of line, about 8.7¢ a minute in all; a call made to a Spanish mobile is

0.105 a minute of line, about 15.7¢ in all. Every country’s rate is in Pricing and billing and in the rate card. A call to your number while the balance is under $0.25 is not answered.

Request

{
  "phone_number": "+14755750358",
  "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c"
}

Parameter	Type	Required	Description
`phone_number`	`string`	Yes	Exact E.164 number from a prior search
`agent_id`	`string`	No	Bind inbound calls on this number to an agent immediately

Response (200)

The number was purchased and is already showing as owned.

{
  "phone_number": "+14755750358",
  "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c"
}

Response (202)

The order was placed, but Telnyx hasn’t finished activating it yet (the API polls briefly, then gives up and returns this instead of blocking indefinitely). It’ll show up in GET /callcenter/numbers shortly after.

{
  "phone_number": "+14755750358",
  "agent_id": "",
  "note": "order placed, but the number isn't showing as owned yet — it should appear in My Numbers shortly"
}

cURL

curl -X POST https://api.lokutor.com/callcenter/numbers \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14755750358", "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c"}'

`POST /callcenter/numbers/{id}/assign` — Assign a Number to an Agent

Rebinds an already-owned number to route inbound calls to a different agent (or, with agent_id: "", no agent).

Request

{ "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c" }

Response

{ "phone_number": "+14755750358", "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c" }

`DELETE /callcenter/numbers/{id}` — Release a Number

Releases the number back to Telnyx and removes its agent binding. {id} is the Telnyx number ID from GET /callcenter/numbers (n.id), not the phone number itself.

This is irreversible — you lose the number.

Response

{ "deleted": "1234567890" }

`POST /callcenter/dial` — Place One Outbound Call

Request

{
  "from": "+14755750358",
  "to": "+15551234567",
  "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c",
  "consent_confirmed": true,
  "context": "Following up on the quote sent Tuesday"
}

Parameter	Type	Required	Description
`from`	`string`	Yes	A number you own (E.164)
`to`	`string`	Yes	Destination number (E.164)
`agent_id`	`string`	No	Which agent answers when the call connects
`consent_confirmed`	`boolean`	Yes	Must be explicitly `true` — see below
`context`	`string`	No	Free-text injected into the agent’s prompt for this call only, never persisted elsewhere

An outbound call is billed as agent time and tokens plus the line per started minute at the destination’s rate (Pricing and billing); a call nobody answers costs nothing. Placing calls needs a first top-up (402 billing.topup_required before it). You can call landlines in every supported country, and mobiles in Spain, France, Germany, Austria, the UK, Ireland, the US and Canada. Mobiles in Portugal, Italy, the Netherlands, Belgium, Luxembourg and Switzerland are above the carrier rate Lokutor allows: dialling one returns 400 with that reason, and nothing is billed.

consent_confirmed isn’t a default-true convenience flag — omit it or send false and the request is rejected with 400. It asserts you have a lawful basis to make this specific call (consent, an existing business relationship, etc.) and is written to an audit log (call_consent_log) alongside the call. It documents that you made the assertion; it doesn’t verify it. Outbound calling still needs a real consent/TCPA policy behind it — this is a gate and a paper trail, not a compliance program.

Response

{
  "call_id": "v3:AAAA...",
  "from": "+14755750358",
  "to": "+15551234567",
  "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c"
}

cURL

curl -X POST https://api.lokutor.com/callcenter/dial \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"from":"+14755750358","to":"+15551234567","agent_id":"34da7ae3-...","consent_confirmed":true}'

`POST /callcenter/bulk-dial` — Create a Bulk Dial Batch

Queues up to 500 calls at once. Each row dials independently, at its own scheduled time (or immediately) — this runs server-side on a background scheduler, so it keeps going even if you close the tab, and even the “dial now” rows go through the same pacing as scheduled ones.

Request

{
  "from": "+14755750358",
  "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c",
  "name": "September follow-ups",
  "consent_confirmed": true,
  "rows": [
    { "phone_number": "+15551234567", "name": "Jane Doe", "context": "Renewal due Oct 1" },
    { "phone_number": "+15557654321", "scheduled_at": "2026-09-10T14:00:00Z" }
  ]
}

Parameter	Type	Required	Description
`from`	`string`	Yes	A number you own
`agent_id`	`string`	No	Agent for every call in this batch
`name`	`string`	No	Display name for the batch
`consent_confirmed`	`boolean`	Yes	Same rule as `/callcenter/dial` — asserts lawful basis to call every number on the list
`rows`	`array`	Yes	1–500 rows
`rows[].phone_number`	`string`	Yes	Destination number
`rows[].name`	`string`	No	Contact name
`rows[].context`	`string`	No	Per-call context for the agent’s prompt
`rows[].scheduled_at`	`string` (ISO 8601)	No	When to dial this row — omitted or in the past means “as soon as possible”

Response

{ "batch_id": "b3f1...", "rows_created": 2 }

`GET /callcenter/bulk-dial` — List Batches

Returns every batch created by the authenticated account, most recent first, each with a live status breakdown.

Response

{
  "batches": [
    {
      "id": "b3f1...",
      "from_number": "+14755750358",
      "name": "September follow-ups",
      "created_at": "2026-09-04T12:00:00Z",
      "row_counts": { "pending": 1, "dialing": 0, "sent": 1, "failed": 0 },
      "total_rows": 2
    }
  ]
}

`GET /callcenter/bulk-dial/{id}` — Batch Detail

Returns one batch with every row, each annotated with its conversation summary once the call has happened.

Response

{
  "id": "b3f1...",
  "from_number": "+14755750358",
  "rows": [
    {
      "id": "r1...",
      "phone_number": "+15551234567",
      "contact_name": "Jane Doe",
      "status": "sent",
      "scheduled_at": "2026-09-04T12:00:01Z",
      "conversation": { "...": "see Conversation object" }
    }
  ]
}

Row status is one of pending, dialing, sent, failed.

Errors — the Authorization: Bearer caveat that applies to every endpoint on this page
REST API — discovery and health endpoints
My First Agent — set up the agent you’ll route these calls to

Get Started

SDK

API Reference

Resources

Call Center API

`GET /callcenter/status` — Provisioning Status

Response

`GET /callcenter/agents` — List Agents

Response

`GET /callcenter/numbers/search` — Search Available Numbers

Query Parameters

Response

cURL

`GET /callcenter/numbers` — List Owned Numbers

Response

`POST /callcenter/numbers` — Buy a Number

Request

Response (200)

Response (202)

cURL

`POST /callcenter/numbers/{id}/assign` — Assign a Number to an Agent

Request

Response

`DELETE /callcenter/numbers/{id}` — Release a Number

Response

`POST /callcenter/dial` — Place One Outbound Call

Request

Response

cURL

`POST /callcenter/bulk-dial` — Create a Bulk Dial Batch

Request

Response

`GET /callcenter/bulk-dial` — List Batches

Response

`GET /callcenter/bulk-dial/{id}` — Batch Detail

Response

​GET /callcenter/status — Provisioning Status

​Response

​GET /callcenter/agents — List Agents

​Response

​GET /callcenter/numbers/search — Search Available Numbers

​Query Parameters

​Response

​cURL

​GET /callcenter/numbers — List Owned Numbers

​Response

​POST /callcenter/numbers — Buy a Number

​Request

​Response (200)

​Response (202)

​cURL

​POST /callcenter/numbers/{id}/assign — Assign a Number to an Agent

​Request

​Response

​DELETE /callcenter/numbers/{id} — Release a Number

​Response

​POST /callcenter/dial — Place One Outbound Call

​Request

​Response

​cURL

​POST /callcenter/bulk-dial — Create a Bulk Dial Batch

​Request

​Response

​GET /callcenter/bulk-dial — List Batches

​Response

​GET /callcenter/bulk-dial/{id} — Batch Detail

​Response

​Related Pages

`GET /callcenter/status` — Provisioning Status

Response

`GET /callcenter/agents` — List Agents

Response

`GET /callcenter/numbers/search` — Search Available Numbers

Query Parameters

Response

cURL

`GET /callcenter/numbers` — List Owned Numbers

Response

`POST /callcenter/numbers` — Buy a Number

Request

Response (200)

Response (202)

cURL

`POST /callcenter/numbers/{id}/assign` — Assign a Number to an Agent

Request

Response

`DELETE /callcenter/numbers/{id}` — Release a Number

Response

`POST /callcenter/dial` — Place One Outbound Call

Request

Response

cURL

`POST /callcenter/bulk-dial` — Create a Bulk Dial Batch

Request

Response

`GET /callcenter/bulk-dial` — List Batches

Response

`GET /callcenter/bulk-dial/{id}` — Batch Detail

Response

Related Pages