Skip to main content
GET
/
v1
/
phone-numbers
/
{phone_number_id}
curl https://api.ringyo.ai/v1/phone-numbers/pn_abc123?include=stats \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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",
  "stats": {
    "total_calls": 5420,
    "total_minutes": 18500,
    "calls_this_month": 342,
    "minutes_this_month": 1156
  },
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-15T12:30:00Z"
}

​
Request

Retrieve detailed information about a specific phone number.

​
Headers

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

​
Path Parameters

​
phone_number_id
string
required
The unique identifier of the phone number (e.g., pn_abc123)

​
Query Parameters

​
include
string
Comma-separated list of additional data: stats, recent_calls

​
Response

​
id
string
Unique identifier for the phone number
​
phone_number
string
The phone number in E.164 format
​
friendly_name
string
Display name for the phone number
​
country
string
Two-letter country code
​
region
string
State or region code
​
capabilities
object
Object with voice and sms boolean fields
​
status
string
Current status: active, pending, inactive
​
default_agent_id
string
Agent ID for handling incoming calls
​
stats
object
Usage statistics (when include=stats)
​
created_at
string
ISO 8601 creation timestamp
curl https://api.ringyo.ai/v1/phone-numbers/pn_abc123?include=stats \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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",
  "stats": {
    "total_calls": 5420,
    "total_minutes": 18500,
    "calls_this_month": 342,
    "minutes_this_month": 1156
  },
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-15T12:30:00Z"
}

​
Error Codes

CodeDescription
phone_number_not_foundThe specified ID does not exist
unauthorizedYou don’t have access to this phone number