# AgentLine Phone Numbers

Each agent has at most one active number. Numbers are US only and cost $2.00 a
month, debited from the balance. One number handles outbound calls, inbound
calls, and inbound SMS.

## Buy

Always ask the human for a preferred area code first (for example 212, 415,
310). If none is available, ask for another.

```bash
curl -s -X POST https://api.agentline.cloud/v1/numbers \
  -H "Authorization: Bearer $AGENTLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agt_xxx","country":"US","number_type":"local","area_code":"415"}'
```

| Field | Notes |
|---|---|
| `agent_id` | Agent to assign the number to. Required. |
| `country` | `US` only. Default `US`. |
| `number_type` | `local` (default) or `tollfree`. |
| `area_code` | Preferred 3-digit US area code. |

A `402 insufficient_balance` response means the account needs credit. Tell the
human to top up at https://agentline.cloud

## List and Get

```bash
curl -s https://api.agentline.cloud/v1/numbers \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"

curl -s https://api.agentline.cloud/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Each number has its assigned agent, country, and status (`active` or
`released`).

## Reassign

Move a number to another agent. The target agent must not already have an
active number. The number stays active.

```bash
curl -s -X PATCH "https://api.agentline.cloud/v1/numbers/NUMBER_ID/reassign?agent_id=agt_other" \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Deleting an agent detaches its number without releasing it. Reassign it to
reuse it.

## Attach an Existing Number

Attach a number that was bought outside this account:

```bash
curl -s -X POST "https://api.agentline.cloud/v1/numbers/attach?phone_number=%2B12125551234&agent_id=agt_xxx" \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

## Release

Only when the human explicitly asks.

```bash
curl -s -X POST https://api.agentline.cloud/v1/numbers/NUMBER_ID/release \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Release is destructive. It unrents the number from the carrier; it cannot be
recovered, and calls and texts to it stop. It is refused while a call is in
progress or a lease is still active.

Next: https://agentline.md/calls.md

AgentLine: https://agentline.cloud | API: https://api.agentline.cloud | All guides: https://agentline.md