Assign specific phone numbers
Assign a specific set of E.164 phone numbers to your organization. The
assignment is all or nothing: if any requested number is no longer
available, the call returns 409 INSUFFICIENT_INVENTORY with an
available_count and a list of unavailable numbers, and no number is
assigned. Drop the unavailable numbers and retry with a fresh search.
You can set routing at order time: inbound_url, status_url,
campaign_id, and label. The inbound_url and status_url must use
https://.
When you set campaign_id, the campaign must exist in your organization,
be ACTIVE, and have a linked brand whose identity status is VERIFIED
or VETTED_VERIFIED.
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
application/json
application/json
application/json
curl -X POST "https://example.com/v1/phone-numbers/orders" \ -H "Content-Type: application/json" \ -d '{ "numbers": [ "+14155550123" ] }'{
"success": true,
"data": [
{
"id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e",
"number": "+14155550123",
"number_type": "local",
"inbound_url": "https://customer.example/inbound",
"status_url": "https://customer.example/status",
"label": "support-line",
"campaign_id": "b5d3c4e2-7f7e-44a1-8c12-2bcd9e3f0a01",
"sms_enabled": true,
"mms_enabled": true,
"created_at": "2026-04-26T12:00:00Z",
"updated_at": "2026-04-26T12:00:00Z"
}
]
}{
"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": "NOT_FOUND",
"message": "not found",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "INSUFFICIENT_INVENTORY",
"message": "insufficient inventory: requested 2, available 1",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
},
"data": {
"available_count": 1,
"unavailable": [
"+14155550456"
]
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}