Skip to main content
GET
/
v1
/
phone-numbers
curl "https://api.ringyo.ai/v1/phone-numbers?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": [
    {
      "id": "pn_abc123",
      "phone_number": "+18005551234",
      "friendly_name": "Main Business Line",
      "country": "US",
      "region": "CA",
      "capabilities": {
        "voice": true,
        "sms": true
      },
      "status": "active",
      "default_agent_id": "agent_abc123",
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "id": "pn_def456",
      "phone_number": "+14155559876",
      "friendly_name": "Sales Line",
      "country": "US",
      "region": "CA",
      "capabilities": {
        "voice": true,
        "sms": false
      },
      "status": "active",
      "default_agent_id": null,
      "created_at": "2024-01-12T10:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 2
}

Request

Retrieve a list of all phone numbers associated with your account.

Headers

Authorization
string
required
Bearer token for authentication. Format: Bearer YOUR_API_KEY

Query Parameters

limit
integer
default:"20"
Number of phone numbers to return (1-100)
cursor
string
Pagination cursor from a previous response
status
string
Filter by status: active, pending, inactive
country
string
Filter by country code (e.g., US, GB, CA)

Response

data
array
Array of phone number objects
has_more
boolean
Whether there are more results available
next_cursor
string
Cursor for fetching the next page
total
integer
Total number of phone numbers
curl "https://api.ringyo.ai/v1/phone-numbers?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": [
    {
      "id": "pn_abc123",
      "phone_number": "+18005551234",
      "friendly_name": "Main Business Line",
      "country": "US",
      "region": "CA",
      "capabilities": {
        "voice": true,
        "sms": true
      },
      "status": "active",
      "default_agent_id": "agent_abc123",
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "id": "pn_def456",
      "phone_number": "+14155559876",
      "friendly_name": "Sales Line",
      "country": "US",
      "region": "CA",
      "capabilities": {
        "voice": true,
        "sms": false
      },
      "status": "active",
      "default_agent_id": null,
      "created_at": "2024-01-12T10:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 2
}

Phone Number Object

FieldTypeDescription
idstringUnique identifier
phone_numberstringE.164 formatted number
friendly_namestringDisplay name
countrystringTwo-letter country code
regionstringState/region code
capabilitiesobjectVoice and SMS capabilities
statusstringactive, pending, inactive
default_agent_idstringAgent for incoming calls
created_atstringISO 8601 timestamp

Error Codes

CodeDescription
invalid_cursorThe pagination cursor is invalid
invalid_countryCountry code is not valid