> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server.

# Phone numbers

> Provision, manage, and release SMS- and voice-enabled phone numbers

Phone numbers are carrier-grade, SMS- and voice-enabled numbers. You can provision new numbers, attach them to agents, list existing numbers, retrieve messages for a number, and release numbers when no longer needed.

**SMS compliance:** Receiving inbound SMS works out of the box. To send outbound SMS, US carriers require 10DLC (10-Digit Long Code) registration. Fill out the [registration form](https://agentphone.ai/register), it takes about 5 minutes and we submit everything to the carriers for you. If you can't figure it out, [schedule a call](https://calendar.app.google/kJQSTCyNYTphvCGm7) and we'll handle the registration for you. Voice calls (inbound and outbound) are not affected and work immediately.

## Create number

Provision a new SMS-enabled phone number.

```
POST /v1/numbers
```

### Request body

| Field      | Type           | Required | Default | Description                                                                                                                          |
| ---------- | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `country`  | string         | No       | `"US"`  | Two-letter country code for the number (e.g., `"US"`, `"CA"`)                                                                        |
| `areaCode` | string or null | No       | null    | Preferred area code (US/CA only, e.g., `"415"`). Best-effort — if unavailable, a random number in the requested country is returned. |
| `agentId`  | string or null | No       | null    | Optionally attach the number to an agent immediately                                                                                 |

### Example

```bash
curl -X POST "https://api.agentphone.ai/v1/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "areaCode": "415",
    "agentId": "agt_abc123"
  }'
```

```json
{
  "id": "num_xyz789",
  "phoneNumber": "+15551234567",
  "country": "US",
  "status": "active",
  "agentId": "agt_abc123",
  "createdAt": "2025-01-15T10:45:00Z"
}
```

## List numbers

List all phone numbers for this project.

```
GET /v1/numbers
```

### Query parameters

| Parameter | Type    | Required | Default | Description                           |
| --------- | ------- | -------- | ------- | ------------------------------------- |
| `limit`   | integer | No       | 20      | Number of results to return (max 100) |
| `offset`  | integer | No       | 0       | Number of results to skip (min 0)     |

### Example

```bash
curl -X GET "https://api.agentphone.ai/v1/numbers?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Look up a number

Check line-type intelligence for any phone number before you message it: whether it is a mobile, landline, or VoIP line, its country, and whether the handset supports RCS. Useful for keeping agents from spending messages on numbers that can never receive them.

```
GET /v1/numbers/lookup
```

Billed at \$0.009 per number looked up.

### Query parameters

| Parameter      | Type   | Required | Description                                                    |
| -------------- | ------ | -------- | -------------------------------------------------------------- |
| `phoneNumbers` | string | Yes      | Comma-separated E.164 numbers to look up, up to 25 per request |

### Example

```bash
curl -X GET "https://api.agentphone.ai/v1/numbers/lookup?phoneNumbers=%2B14155551234,%2B15551230000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "phoneNumber": "+14155551234",
      "lineType": "mobile",
      "country": "US",
      "rcsEnabled": true
    },
    {
      "phoneNumber": "+15551230000",
      "lineType": "landline",
      "country": "US",
      "rcsEnabled": false
    }
  ]
}
```

`lineType` is `"mobile"`, `"landline"`, or `"voip"`; fields are `null` when a number cannot be resolved. Accounts with a negative balance receive a `402` before any lookup runs.

## Delete number (release)

Release (delete) a phone number.

This action:

1. Releases the number back to the carrier pool
2. Marks the number as `"released"` in the database
3. Keeps all messages and conversation history for audit purposes

This action is irreversible. The number cannot be recovered once released.

```
DELETE /v1/numbers/{number_id}
```

### Example

```bash
curl -X DELETE "https://api.agentphone.ai/v1/numbers/num_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get messages for number

Get messages for a specific phone number. Supports cursor-based pagination via `before`/`after` timestamps.

```
GET /v1/numbers/{number_id}/messages
```

### Query parameters

| Parameter | Type                      | Required | Default | Description                                      |
| --------- | ------------------------- | -------- | ------- | ------------------------------------------------ |
| `limit`   | integer                   | No       | 50      | Number of messages to return (max 200)           |
| `before`  | string (datetime) or null | No       | null    | Return messages before this timestamp (ISO 8601) |
| `after`   | string (datetime) or null | No       | null    | Return messages after this timestamp (ISO 8601)  |

### Example

```bash
curl -X GET "https://api.agentphone.ai/v1/numbers/num_xyz789/messages?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "id": "msg_001",
      "from_": "+15559876543",
      "to": "+15551234567",
      "body": "Hi, I need help with my order",
      "receivedAt": "2025-01-15T12:00:00Z"
    }
  ],
  "hasMore": false
}
```