Skip to main content
GET
/
purchasePhoneNumbers
/
fetchAvailableNumbers
curl -X GET "https://api.zudu.ai/purchasePhoneNumbers/fetchAvailableNumbers?countryCode=US&contains=555" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \

{
  "TWILIO": {
    "Local": {
      "pricing": "1.30",
      "numbers": [
        "+15551234567",
        "+15555551234"
      ]
    },
    "Mobile": {
      "pricing": "1.30",
      "numbers": [
        "+15559876543"
      ]
    },
  "PLIVO": {
    "Local": {
      "pricing": "1.20",
      "numbers": [
        "+15551111111"
      ]
    }
}
Search for available phone numbers from all configured providers (Twilio, Plivo, etc.) with optional filtering. 
curl -X GET "https://api.zudu.ai/purchasePhoneNumbers/fetchAvailableNumbers?countryCode=US&contains=555" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \

{
  "TWILIO": {
    "Local": {
      "pricing": "1.30",
      "numbers": [
        "+15551234567",
        "+15555551234"
      ]
    },
    "Mobile": {
      "pricing": "1.30",
      "numbers": [
        "+15559876543"
      ]
    },
  "PLIVO": {
    "Local": {
      "pricing": "1.20",
      "numbers": [
        "+15551111111"
      ]
    }
}

​
Query Parameters

​
countryCode
string
required
Two-letter country code (ISO 3166-1 alpha-2)Examples: US, GB, CA, AUExample: US
​
contains
string
Optional search filter - phone numbers containing this stringExample: "555" - Returns numbers containing “555”Useful for finding numbers with specific area codes or patterns.

​
Headers

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

​
Response Structure

The response is organized by provider, then by number type:
  • Provider (e.g., TWILIO, PLIVO): Top-level key
    • Type (e.g., Local, Mobile, Toll-Free): Number type
      • pricing: Monthly cost in USD (with markup applied)
      • numbers: Array of available phone numbers

​
Response Fields

​
pricing
string
Monthly cost in USD (includes provider markup)Example: "1.30" means $1.30/month
​
numbers
array
Array of available phone numbers in E.164 format

​
Error Responses

​
error
string
Bad Request - Invalid country code or missing required parameter

​
Notes

  • Results are grouped by provider and number type
  • Pricing includes a markup over provider costs
  • Numbers are shown in E.164 format (e.g., +15551234567)
  • Use the contains parameter to filter by area code or specific digits
  • Availability is real-time - numbers may be purchased by others