Phone numbers

Phone numbers are SMS- and voice-enabled numbers provisioned through Twilio. 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.to/v1/numbers" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "country": "US",
>
    "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.to/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 from Twilio (the number goes back to Twilio’s 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.to/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.to/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
}