Guides

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, it takes about 5 minutes and we submit everything to the carriers for you. If you can’t figure it out, schedule a call 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

FieldTypeRequiredDefaultDescription
countrystringNo"US"Two-letter country code for the number (e.g., "US", "CA")
areaCodestring or nullNonullPreferred area code (US/CA only, e.g., "415"). Best-effort — if unavailable, a random number in the requested country is returned.
agentIdstring or nullNonullOptionally attach the number to an agent immediately

Example

$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"
>  }'
1{
2  "id": "num_xyz789",
3  "phoneNumber": "+15551234567",
4  "country": "US",
5  "status": "active",
6  "agentId": "agt_abc123",
7  "createdAt": "2025-01-15T10:45:00Z"
8}

List numbers

List all phone numbers for this project.

GET /v1/numbers

Query parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo20Number of results to return (max 100)
offsetintegerNo0Number of results to skip (min 0)

Example

$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

ParameterTypeRequiredDescription
phoneNumbersstringYesComma-separated E.164 numbers to look up, up to 25 per request

Example

$curl -X GET "https://api.agentphone.ai/v1/numbers/lookup?phoneNumbers=%2B14155551234,%2B15551230000" \
>  -H "Authorization: Bearer YOUR_API_KEY"
1{
2  "data": [
3    {
4      "phoneNumber": "+14155551234",
5      "lineType": "mobile",
6      "country": "US",
7      "rcsEnabled": true
8    },
9    {
10      "phoneNumber": "+15551230000",
11      "lineType": "landline",
12      "country": "US",
13      "rcsEnabled": false
14    }
15  ]
16}

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

$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

ParameterTypeRequiredDefaultDescription
limitintegerNo50Number of messages to return (max 200)
beforestring (datetime) or nullNonullReturn messages before this timestamp (ISO 8601)
afterstring (datetime) or nullNonullReturn messages after this timestamp (ISO 8601)

Example

$curl -X GET "https://api.agentphone.ai/v1/numbers/num_xyz789/messages?limit=10" \
>  -H "Authorization: Bearer YOUR_API_KEY"
1{
2  "data": [
3    {
4      "id": "msg_001",
5      "from_": "+15559876543",
6      "to": "+15551234567",
7      "body": "Hi, I need help with my order",
8      "receivedAt": "2025-01-15T12:00:00Z"
9    }
10  ],
11  "hasMore": false
12}