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.

Create number

Provision a new SMS-enabled phone number.

POST /v1/numbers

Request body

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

Example

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

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

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

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
}