Bulk-order phone numbers by quantity
Order phone numbers by quantity and criteria rather than by an explicit
list. When your requested quantity can be filled immediately, the call
returns 200 OK with the assigned numbers, using the same response shape
as POST /v1/phone-numbers/orders. When the quantity cannot be filled
immediately, the call returns 202 Accepted with an order_id you can
poll using GET /v1/phone-numbers/bulk/{id}.
Only mode=atomic is supported today: either the full quantity is filled
at once, or the full quantity is ordered for you. immediate_partial is
not yet available and returns 422 VALIDATION_FAILED.
Sending an Idempotency-Key header is optional. When present, it is
honored for a 24-hour window so retries do not create duplicate orders.
Note that pattern only applies to immediately available numbers; numbers
ordered to fill a shortfall may not match the requested pattern.
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
Header Parameters
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/phone-numbers/bulk" \ -H "Content-Type: application/json" \ -d '{ "quantity": 100, "number_type": "local", "area_code": "415", "pattern": "555", "inbound_url": "https://customer.example/inbound", "status_url": "https://customer.example/status", "label": "support-pool", "mode": "atomic" }'{
"success": true,
"data": {
"order_id": null,
"status": "complete",
"quantity": 3,
"assigned_count": 3,
"pending_count": 0,
"assigned_numbers": [
"+14155557001",
"+14155557002",
"+14155557003"
]
}
}{
"success": true,
"data": {
"order_id": "f3a5b1c2-4d8e-4a91-9c3a-7b6e1d0f2a3b",
"status": "processing",
"quantity": 100,
"assigned_count": 0,
"pending_count": 100,
"assigned_numbers": []
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "INSUFFICIENT_CREDIT",
"message": "insufficient credit",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "INSUFFICIENT_INVENTORY",
"message": "insufficient inventory",
"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"
}
}
}