Call Center API

Everything here lives under /callcenter/* on https://api.lokutor.com. The routes exist only on a server with telephony configured; where it is not, they are not registered at all and answer 404. api.lokutor.com has telephony configured. For a step-by-step setup, see the Phone agent quickstart. Authentication: every endpoint takes an API key or wst_ ticket as Authorization: Bearer, X-API-Key or ?api_key= (Authentication). The key must belong to an account (401 otherwise). 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

Whether calling is enabled, and through which carrier.

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"`	`US`, `ES`, `UK`, `DE`, `FR`, `IT` or `PT`
`region_code`	`string`	—	Region or state, e.g. `CT`
`locality`	`string`	—	City, e.g. `Madrid`
`page`	`integer`	`1`	Results come 15 per page

Response

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

cURL

curl -s "https://api.lokutor.com/callcenter/numbers/search?country_code=US&region_code=CT" \
  -H "Authorization: Bearer $LOKUTOR_API_KEY"

`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.

{
  "id": "1234567890",
  "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 "Authorization: Bearer $LOKUTOR_API_KEY" \
  -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

There is no connection_id field: calls always go out through Lokutor’s outbound profile, which carries the destination-rate limits below. A connection_id in the body is ignored. 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 "Authorization: Bearer $LOKUTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"+14755750358","to":"+15551234567","agent_id":"34da7ae3-...","consent_confirmed":true}'

Use the returned call_id to follow the call or hang it up with POST /callcenter/hangup/{id}.

`GET /callcenter/call-monitor` — Follow a Call

GET /callcenter/call-monitor?call_id={call_id} returns the current state of a call your account placed:

{
  "status": "connected",
  "transcript": [ "…" ],
  "duration": 42,
  "end_reason": ""
}

status is dialing, ringing, connected or ended. A call that is not yours, or that the server does not know, reads as {"status": "ended", "transcript": [], "duration": 0}.

Live updates (Server-Sent Events)

GET /callcenter/sse/call-monitor?call_id={call_id} streams the same information. The first event is a snapshot (status, transcript, duration); then status, transcript (one new line in text), transcript_sync (the whole transcript) and ended (with end_reason) events follow as the call progresses. Each arrives as a data: line holding a JSON object with a type field. A : heartbeat comment is sent every 15 seconds. A browser EventSource cannot send headers, so pass a short-lived ticket (minted on your backend, see Authentication) as api_key:

const { ticket } = await fetch('/api/lokutor-ticket', { method: 'POST' }).then((r) => r.json());
const events = new EventSource(
  `https://api.lokutor.com/callcenter/sse/call-monitor?call_id=${encodeURIComponent(callId)}&api_key=${ticket}`
);
events.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'transcript') console.log(msg.text);
  if (msg.type === 'ended') events.close();
};

Hang Up a Call

POST /callcenter/hangup/{id} hangs up a call your account placed. {id} is the call_id from /callcenter/dial.

curl -X POST "https://api.lokutor.com/callcenter/hangup/$CALL_ID" \
  -H "Authorization: Bearer $LOKUTOR_API_KEY"

{ "status": "hangup_sent" }

`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.

Phone agent quickstart: buy a number and take a call
Errors: error codes, including the billing 402s
REST API: synthesis, transcription and discovery endpoints
My First Agent: build an agent to 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

`GET /callcenter/call-monitor` — Follow a Call

Live updates (Server-Sent Events)

Hang Up a Call

`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

​GET /callcenter/call-monitor — Follow a Call

​Live updates (Server-Sent Events)

​Hang Up a Call

​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

`GET /callcenter/call-monitor` — Follow a Call

Live updates (Server-Sent Events)

Hang Up a Call

`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