Skip to main content
GET
/
api
/
phone-numbers
/
{phone-number}
curl -X GET "https://api.zudu.ai/api/phone-numbers/+14155551234" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \

{
  "message": "Phone number retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "phone_number": "+14155551234",
    "nickname": "Main Office Line",
    "organization_id": "org_1234567890",
    "area_code": 415,
    "phone_number_type": "ZUDU_TWILIO",
    "number_provider": "twilio",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456",
    "inbound_agent_version": 1,
    "outbound_agent_version": 1,
    "inbound_webhook_url": "https://example.com/webhook",
    "inbound_trunk_id": "trunk_inbound_abc123",
    "outbound_trunk_id": "trunk_outbound_def456",
    "dispatch_rule_id": "dispatch_xyz789",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
Retrieve complete details for a specific phone number in your organization. 
curl -X GET "https://api.zudu.ai/api/phone-numbers/+14155551234" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \

{
  "message": "Phone number retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "phone_number": "+14155551234",
    "nickname": "Main Office Line",
    "organization_id": "org_1234567890",
    "area_code": 415,
    "phone_number_type": "ZUDU_TWILIO",
    "number_provider": "twilio",
    "inbound_agent_id": "agent_123",
    "outbound_agent_id": "agent_456",
    "inbound_agent_version": 1,
    "outbound_agent_version": 1,
    "inbound_webhook_url": "https://example.com/webhook",
    "inbound_trunk_id": "trunk_inbound_abc123",
    "outbound_trunk_id": "trunk_outbound_def456",
    "dispatch_rule_id": "dispatch_xyz789",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }

​
Path Parameters

​
phone-number
string
required
The phone number to retrieve in E.164 formatExample: +14155551234Note: The phone number should be URL-encoded if it contains special characters (e.g., %2B14155551234 for +14155551234)

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Response Fields

​
phone_number
string
The phone number in E.164 format
​
nickname
string
Nickname/label for the phone number (if set)
​
organization_id
string
The organization ID the phone number belongs to
​
area_code
integer
Area code (for US numbers)
​
phone_number_type
string
Type of phone number (e.g., ZUDU_TWILIO, CUSTOM)
​
number_provider
string
Provider name (e.g., twilio, plivo)
​
inbound_agent_id
string
Agent ID assigned for inbound calls (or null if not assigned)
​
outbound_agent_id
string
Agent ID assigned for outbound calls (or null if not assigned)
​
inbound_agent_version
integer
Inbound agent version (if set)
​
outbound_agent_version
integer
Outbound agent version (if set)
​
inbound_webhook_url
string
Webhook URL for inbound calls (if set)
​
inbound_trunk_id
string
LiveKit inbound trunk ID (if set)
​
outbound_trunk_id
string
LiveKit outbound trunk ID (if set)
​
dispatch_rule_id
string
LiveKit dispatch rule ID (if set)
​
created_at
string
ISO 8601 timestamp when the phone number was created
​
updated_at
string
ISO 8601 timestamp when the phone number was last updated

​
Error Responses

​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Not Found - Phone number does not exist
{
  "message": "Phone number not found",
  "status": "error",
  "error": "Phone number '+14155551234' does not exist in organization 'org_1234567890'"
}
​
error
string
Internal Server Error - Failed to retrieve phone number
{
  "message": "Failed to retrieve phone number",
  "status": "error",
  "error": "Database connection failed"
}

​
Notes

  • Results are automatically scoped to your organization based on the API key (organization ID is automatically extracted)
  • Phone numbers should be URL-encoded in the path (e.g., %2B for +)
  • The response includes all phone number configuration including agent assignments and trunk IDs
  • Use this endpoint to check if a phone number exists and view its current configuration
  • Fields may be null if they haven’t been set (e.g., inbound_agent_id, outbound_agent_id)