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

{
  "message": "Available phone numbers retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "available_count": 2,
    "phone_numbers": [
      {
        "phone_number": "+14155551234",
        "nickname": "Main Office Line",
        "area_code": 415,
        "phone_number_type": "ZUDU_TWILIO",
        "number_provider": "twilio",
        "inbound_agent_id": null,
        "outbound_agent_id": null,
        "created_at": "2024-01-15T10:30:00Z"
      },
      {
        "phone_number": "+14155555678",
        "nickname": "Support Line",
        "area_code": 415,
        "phone_number_type": "CUSTOM",
        "number_provider": "twilio",
        "inbound_agent_id": null,
        "outbound_agent_id": null,
        "created_at": "2024-01-14T09:20:00Z"
      }
    ]
  }
Retrieve a list of all phone numbers in your organization that are currently available (not assigned to any inbound or outbound agent). 
curl -X GET "https://api.zudu.ai/api/phone-numbers/available" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \

{
  "message": "Available phone numbers retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "available_count": 2,
    "phone_numbers": [
      {
        "phone_number": "+14155551234",
        "nickname": "Main Office Line",
        "area_code": 415,
        "phone_number_type": "ZUDU_TWILIO",
        "number_provider": "twilio",
        "inbound_agent_id": null,
        "outbound_agent_id": null,
        "created_at": "2024-01-15T10:30:00Z"
      },
      {
        "phone_number": "+14155555678",
        "nickname": "Support Line",
        "area_code": 415,
        "phone_number_type": "CUSTOM",
        "number_provider": "twilio",
        "inbound_agent_id": null,
        "outbound_agent_id": null,
        "created_at": "2024-01-14T09:20:00Z"
      }
    ]
  }

​
Headers

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

​
Response Fields

​
organization_id
string
The organization ID
​
available_count
integer
Total number of available phone numbers
​
phone_numbers
array
Array of available phone number objectsEach phone number object contains:
  • phone_number: Phone number in E.164 format
  • nickname: Optional nickname/label for the number
  • area_code: Area code (for US numbers)
  • phone_number_type: Type of phone number (e.g., ZUDU_TWILIO, CUSTOM)
  • number_provider: Provider name (e.g., twilio, plivo)
  • inbound_agent_id: Always null for available numbers
  • outbound_agent_id: Always null for available numbers
  • created_at: Creation timestamp

​
Error Responses

​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Internal Server Error - Failed to retrieve available phone numbers
{
  "message": "Failed to retrieve available phone numbers",
  "status": "error",
  "error": "Database connection failed"
}

​
Notes

  • A phone number is considered “available” if both inbound_agent_id and outbound_agent_id are null
  • Results are automatically scoped to your organization based on the API key (organization ID is automatically extracted)
  • Use this endpoint to find phone numbers that can be assigned to agents
  • Phone numbers can be assigned to agents using the update endpoint (PATCH /api/phone-numbers/{phone-number})