IllyVoIPdevelopers

Phone Numbers

Search DID numbers

Returns purchasable numbers for a country/region selection.

Try in API Playground ↗Sign in to prepare and run this request.
GET/api/v1/dids/numbers

Before you start

Provide a supported country/region and search options.

Result

Choose an available number, then obtain a fresh order quote.

Charges and safe retries

Search availability is not a purchase or reservation.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X GET "https://api.illyvoip.com/api/v1/dids/numbers?country_iso=CA&region_code=249&number_type=local&limit=10" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/dids/numbers?country_iso=CA&region_code=249&number_type=local&limit=10", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/dids/numbers?country_iso=CA&region_code=249&number_type=local&limit=10');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY')
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/dids/numbers?country_iso=CA&region_code=249&number_type=local&limit=10",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"]
    },
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request parameters

Query parameters

country_isostringrequired

Country ISO2 code.

region_codestringoptional

Optional region code returned by /api/v1/dids/catalog/regions for that country. Some destinations use numeric codes. Omit this parameter when no region filter is needed.

limitintegeroptional

Maximum returned numbers or quantity-order products (1–200; default 50).

default 100minimum 1maximum 500
offsetintegeroptional

Quantity-order products only: start at zero, then use meta.next_offset until null. Keep country, type, region and limit unchanged. Not supported for selectable-number inventory.

Request behavior

Use this right before order creation to present live inventory. regulation.address_scope identifies local or national address restrictions when applicable. For request-only destinations, the response has order_mode: quantity, manual_review_required: true and a products list instead of selectable numbers. Use limit and offset to page through products; meta.total_products gives the matching total and meta.next_offset is null on the last page.

Availability can change between requests. Select a returned product reference, obtain a quote, then submit the quantity and required documents/address. A successful request waits for staff review; it does not mean the number is active. region_code is optional: only send it when /api/v1/dids/catalog/regions returned a region for the selected country.

Some destinations use numeric region codes such as 249. If the country has no regional split, omit region_code entirely, for example /api/v1/dids/numbers?country_iso=BE&number_type=local&limit=10.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • data: Endpoint-specific result object. Its nested fields are shown in the sample response.
  • meta: Additional documented result metadata; consult the example for this endpoint.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

Response example
{
  "status": "success",
  "data": {
    "country_iso": "CA",
    "region_code": "249",
    "number_type": "local",
    "pricing": {
      "setup_fee": 1,
      "monthly_fee": 1,
      "per_minute_fee": 0.01,
      "connection_fee": 0,
      "currency": "EUR"
    },
    "regulation": {
      "documents_required": false,
      "address_required": false,
      "identity_required": false,
      "document_labels": [],
      "address_scope": null
    },
    "availability": {
      "estimated_quantity": 1832
    },
    "numbers": [
      {
        "number": "+12494251304",
        "product_reference": "didpr_E4x7a0example",
        "country_iso": "CA",
        "region_code": "249"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}
Response example
{
  "status": "success",
  "data": {
    "country_iso": "AL",
    "region_code": null,
    "number_type": "local",
    "pricing": {
      "setup_fee": 0,
      "monthly_fee": 10,
      "per_minute_fee": 0.03,
      "connection_fee": 0,
      "currency": "EUR"
    },
    "regulation": {
      "documents_required": true,
      "address_required": true,
      "identity_required": false,
      "document_labels": [
        "Proof of Address"
      ],
      "address_scope": null
    },
    "availability": {
      "estimated_quantity": 0
    },
    "numbers": [],
    "order_mode": "quantity",
    "manual_review_required": true,
    "products": [
      {
        "product_reference": "didpr_PUBLIC_PRODUCT_REFERENCE",
        "country_iso": "AL",
        "region_code": null,
        "number_type": "local",
        "pricing": {
          "setup_fee": 0,
          "monthly_fee": 10,
          "per_minute_fee": 0.03,
          "connection_fee": 0,
          "currency": "EUR"
        },
        "regulation": {
          "documents_required": true,
          "address_required": true,
          "identity_required": false,
          "document_labels": [
            "Proof of Address"
          ],
          "address_scope": null
        },
        "order_mode": "quantity",
        "manual_review_required": true
      }
    ]
  },
  "meta": {
    "count": 0,
    "product_count": 1,
    "total_products": 1,
    "limit": 50,
    "offset": 0,
    "next_offset": null
  }
}

anyOf schema alternatives

statusstringrequired
enum ["success"]
dataobjectrequired
View nested fields
country_isostringrequired
region_codestringrequired
number_typestringrequired
pricingobjectrequired
View nested fields
setup_feeintegerrequired
monthly_feeintegerrequired
per_minute_feenumberrequired
connection_feenumberrequired

Customer connection charge per incoming call in EUR, when available.

nullable true
currencystringrequired

Additional properties: not allowed.

regulationobjectrequired
View nested fields
documents_requiredbooleanrequired
address_requiredbooleanrequired
identity_requiredbooleanrequired
document_labelsarray<string>required
View nested fields

Array items

Type: string

address_scopestringrequired
nullable true

Additional properties: not allowed.

availabilityobjectrequired
View nested fields
estimated_quantityintegerrequired

Additional properties: not allowed.

numbersarray<object>required
View nested fields

Array items

numberstringrequired
product_referencestringrequired
country_isostringrequired
region_codestringrequired

Additional properties: not allowed.

Additional properties: not allowed.

metaobjectrequired
View nested fields
countintegerrequired

Additional properties: not allowed.

Additional properties: not allowed.

statusstringrequired
enum ["success"]
dataobjectrequired
View nested fields
country_isostringrequired
region_codestringrequired
nullable true
number_typestringrequired
pricingobjectrequired
View nested fields
setup_feeintegerrequired
monthly_feeintegerrequired
per_minute_feenumberrequired
connection_feenumberrequired

Customer connection charge per incoming call in EUR, when available.

nullable true
currencystringrequired

Additional properties: not allowed.

regulationobjectrequired
View nested fields
documents_requiredbooleanrequired
address_requiredbooleanrequired
identity_requiredbooleanrequired
document_labelsarray<string>required
View nested fields

Array items

Type: string

address_scopestringrequired
nullable true

Additional properties: not allowed.

availabilityobjectrequired
View nested fields
estimated_quantityintegerrequired

Additional properties: not allowed.

numbersarray<value>required
View nested fields

Array items

Type: value

order_modestringrequired
manual_review_requiredbooleanrequired
productsarray<object>required
View nested fields

Array items

product_referencestringrequired
country_isostringrequired
region_codestringrequired
nullable true
number_typestringrequired
pricingobjectrequired
View nested fields
setup_feeintegerrequired
monthly_feeintegerrequired
per_minute_feenumberrequired
connection_feenumberrequired

Customer connection charge per incoming call in EUR, when available.

nullable true
currencystringrequired

Additional properties: not allowed.

regulationobjectrequired
View nested fields
documents_requiredbooleanrequired
address_requiredbooleanrequired
identity_requiredbooleanrequired
document_labelsarray<string>required
View nested fields

Array items

Type: string

address_scopestringrequired
nullable true

Additional properties: not allowed.

order_modestringrequired
manual_review_requiredbooleanrequired

Additional properties: not allowed.

Additional properties: not allowed.

metaobjectrequired
View nested fields
countintegerrequired
product_countintegerrequired
total_productsintegerrequired
limitintegerrequired
offsetintegerrequired
next_offsetintegerrequired
nullable trueminimum 0

Additional properties: not allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "anyOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "success"
          ]
        },
        "data": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "country_iso": {
              "type": "string"
            },
            "region_code": {
              "type": "string"
            },
            "number_type": {
              "type": "string"
            },
            "pricing": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "setup_fee": {
                  "type": "integer"
                },
                "monthly_fee": {
                  "type": "integer"
                },
                "per_minute_fee": {
                  "type": "number"
                },
                "connection_fee": {
                  "type": "number",
                  "nullable": true,
                  "description": "Customer connection charge per incoming call in EUR, when available."
                },
                "currency": {
                  "type": "string"
                }
              },
              "required": [
                "setup_fee",
                "monthly_fee",
                "per_minute_fee",
                "connection_fee",
                "currency"
              ]
            },
            "regulation": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "documents_required": {
                  "type": "boolean"
                },
                "address_required": {
                  "type": "boolean"
                },
                "identity_required": {
                  "type": "boolean"
                },
                "document_labels": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "address_scope": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "documents_required",
                "address_required",
                "identity_required",
                "document_labels",
                "address_scope"
              ]
            },
            "availability": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "estimated_quantity": {
                  "type": "integer"
                }
              },
              "required": [
                "estimated_quantity"
              ]
            },
            "numbers": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "number": {
                    "type": "string"
                  },
                  "product_reference": {
                    "type": "string"
                  },
                  "country_iso": {
                    "type": "string"
                  },
                  "region_code": {
                    "type": "string"
                  }
                },
                "required": [
                  "number",
                  "product_reference",
                  "country_iso",
                  "region_code"
                ]
              }
            }
          },
          "required": [
            "country_iso",
            "region_code",
            "number_type",
            "pricing",
            "regulation",
            "availability",
            "numbers"
          ]
        },
        "meta": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "count": {
              "type": "integer"
            }
          },
          "required": [
            "count"
          ]
        }
      },
      "required": [
        "status",
        "data",
        "meta"
      ]
    },
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "success"
          ]
        },
        "data": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "country_iso": {
              "type": "string"
            },
            "region_code": {
              "type": "string",
              "nullable": true
            },
            "number_type": {
              "type": "string"
            },
            "pricing": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "setup_fee": {
                  "type": "integer"
                },
                "monthly_fee": {
                  "type": "integer"
                },
                "per_minute_fee": {
                  "type": "number"
                },
                "connection_fee": {
                  "type": "number",
                  "nullable": true,
                  "description": "Customer connection charge per incoming call in EUR, when available."
                },
                "currency": {
                  "type": "string"
                }
              },
              "required": [
                "setup_fee",
                "monthly_fee",
                "per_minute_fee",
                "connection_fee",
                "currency"
              ]
            },
            "regulation": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "documents_required": {
                  "type": "boolean"
                },
                "address_required": {
                  "type": "boolean"
                },
                "identity_required": {
                  "type": "boolean"
                },
                "document_labels": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "address_scope": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "documents_required",
                "address_required",
                "identity_required",
                "document_labels",
                "address_scope"
              ]
            },
            "availability": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "estimated_quantity": {
                  "type": "integer"
                }
              },
              "required": [
                "estimated_quantity"
              ]
            },
            "numbers": {
              "type": "array",
              "items": {}
            },
            "order_mode": {
              "type": "string"
            },
            "manual_review_required": {
              "type": "boolean"
            },
            "products": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "product_reference": {
                    "type": "string"
                  },
                  "country_iso": {
                    "type": "string"
                  },
                  "region_code": {
                    "type": "string",
                    "nullable": true
                  },
                  "number_type": {
                    "type": "string"
                  },
                  "pricing": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "setup_fee": {
                        "type": "integer"
                      },
                      "monthly_fee": {
                        "type": "integer"
                      },
                      "per_minute_fee": {
                        "type": "number"
                      },
                      "connection_fee": {
                        "type": "number",
                        "nullable": true,
                        "description": "Customer connection charge per incoming call in EUR, when available."
                      },
                      "currency": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "setup_fee",
                      "monthly_fee",
                      "per_minute_fee",
                      "connection_fee",
                      "currency"
                    ]
                  },
                  "regulation": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "documents_required": {
                        "type": "boolean"
                      },
                      "address_required": {
                        "type": "boolean"
                      },
                      "identity_required": {
                        "type": "boolean"
                      },
                      "document_labels": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "address_scope": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "documents_required",
                      "address_required",
                      "identity_required",
                      "document_labels",
                      "address_scope"
                    ]
                  },
                  "order_mode": {
                    "type": "string"
                  },
                  "manual_review_required": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "product_reference",
                  "country_iso",
                  "region_code",
                  "number_type",
                  "pricing",
                  "regulation",
                  "order_mode",
                  "manual_review_required"
                ]
              }
            }
          },
          "required": [
            "country_iso",
            "region_code",
            "number_type",
            "pricing",
            "regulation",
            "availability",
            "numbers",
            "order_mode",
            "manual_review_required",
            "products"
          ]
        },
        "meta": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "count": {
              "type": "integer"
            },
            "product_count": {
              "type": "integer"
            },
            "total_products": {
              "type": "integer"
            },
            "limit": {
              "type": "integer"
            },
            "offset": {
              "type": "integer"
            },
            "next_offset": {
              "type": "integer",
              "nullable": true,
              "minimum": 0
            }
          },
          "required": [
            "count",
            "product_count",
            "total_products",
            "limit",
            "offset",
            "next_offset"
          ]
        }
      },
      "required": [
        "status",
        "data",
        "meta"
      ]
    }
  ]
}
400 The request failed validation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key or browser token is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account is not allowed to perform this operation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected service error occurred.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 The service is temporarily unavailable.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable, unavailable

Try this operation in Sandbox · Environment setup and limitations

List DID countriesList DID regionsGet DID routing configSave DID routing configList DID ordersCreate DID orderQuote DID orderCancel DID numberUpload DID documentsResubmit regulation

Search API operations, parameters, SDK and webhooks.