Preview available phone numbers
Search for phone numbers that match your criteria. This is a preview
only and does not reserve anything. A number returned here may be claimed
by another request before you order it; if that happens, your order
returns 409 INSUFFICIENT_INVENTORY and you can search again and retry.
area_code is the 3-digit area code (NPA) and matches numbers beginning
with +1 followed by that code. pattern is a substring match on the
E.164 number, so "555" matches "+1415555...". quantity defaults to
10 and is capped at 100.
Requires the numbers:write scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/phone-numbers/search" \ -H "Content-Type: application/json" \ -d '{ "area_code": "415", "number_type": "local", "pattern": "555", "quantity": 5 }'{
"success": true,
"data": [
{
"number": "+14155550123",
"number_type": "local"
},
{
"number": "+14155550456",
"number_type": "local"
}
]
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}