> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lokutor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Agent Quickstart

> Put a dashboard agent on a phone number with the Call Center API: find the agent, search for a local number, buy it bound to the agent, take a call, and place an outbound call.

This guide puts one of your agents on a phone number, so that anyone who calls the number talks to it. It uses the [Call Center API](/api-reference/call-center) with `curl`; the dashboard can do the same steps without code.

## Before you start

* An agent created in the [dashboard](https://app.lokutor.com). Its prompt, voice, language and tools are what callers get.
* An API key in `LOKUTOR_API_KEY` ([Authentication](/authentication)).
* A first top-up on the account. Phone numbers and outbound calls are not paid by the welcome credit: before the first top-up these endpoints answer `402` `billing.topup_required`.

A number costs **\$5 a month** from your balance, charged when you buy it and then monthly. Calls are billed as agent time and language-model tokens plus the phone line per started minute, by country ([Pricing and billing](/pricing#phone-calls)).

## 1. Find your agent's id

```bash theme={null}
curl -s https://api.lokutor.com/callcenter/agents \
  -H "Authorization: Bearer $LOKUTOR_API_KEY"
```

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

## 2. Search for a number

Only local numbers are offered, in the US (`US`), Spain (`ES`), the UK (`UK`), Germany (`DE`), France (`FR`), Italy (`IT`) and Portugal (`PT`). Narrow the search with `region_code` or `locality`; results come 15 per page (`page=2` for more).

```bash theme={null}
curl -s "https://api.lokutor.com/callcenter/numbers/search?country_code=ES&locality=Madrid" \
  -H "Authorization: Bearer $LOKUTOR_API_KEY"
```

Pick a `phone_number` from the results. The `monthly_cost` shown there is the carrier's figure, not your price.

## 3. Buy it, bound to the agent

<Warning>This rents the number and charges the first month immediately. There is no confirmation step.</Warning>

```bash theme={null}
curl -X POST https://api.lokutor.com/callcenter/numbers \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+34910000000", "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c"}'
```

`200` means the number is yours and already routed to the agent. `202` means the order was placed and the number appears in `GET /callcenter/numbers` shortly.

## 4. Call it

Call the number from any phone. The agent answers with its first message and holds the conversation. The call appears in the dashboard with its transcript.

A call to your number is not answered while the account balance is under \$0.25.

## 5. Route it to another agent later

`{id}` is the number's `id` from `GET /callcenter/numbers`, not the phone number itself.

```bash theme={null}
curl -X POST https://api.lokutor.com/callcenter/numbers/1234567890/assign \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "another-agent-id"}'
```

## Outbound calls

The same number can call out. `consent_confirmed: true` is required and records that you have a lawful basis to call this person.

```bash theme={null}
curl -X POST https://api.lokutor.com/callcenter/dial \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "+34910000000", "to": "+34600000000", "agent_id": "34da7ae3-0d46-4827-8739-ca6a25dc756c", "consent_confirmed": true}'
```

The response's `call_id` lets you [follow the call](/api-reference/call-center#get-/callcenter/call-monitor-—-follow-a-call) and [hang it up](/api-reference/call-center#hang-up-a-call). Which destinations can be dialled is listed under [`/callcenter/dial`](/api-reference/call-center#post-/callcenter/dial-—-place-one-outbound-call).

<Warning>
  These endpoints spend money and call real people. Do not let an AI agent or an automated job call them without a person approving each call.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.