API Docs
Voxbi Cockpit APIs
All endpoints

Place a phone number order

Submit a phone number order. Must be called as multipart/form-data because KYC document files are part of the request. Call POST /numbers/orders/check first to obtain the address-specific kycRequirements.

You may attach your own order_id (any short string, max 64 chars) - it will be echoed back to you in the response, in GET /numbers/orders/{id}, and in the asynchronous webhook payload below. If you omit it, the upstream provider will generate one and we'll backfill it on your row.

Order fulfilment is asynchronous. This endpoint returns 201 as soon as the order is accepted upstream. The final outcome (success or rejection) will be delivered to your webhook URL (if provided) and is queryable via GET /numbers/orders/{id}.

Webhook payload

When the order reaches its final state we POST to your webhook URL the exact same body as GET /numbers/orders/{id} (the schema below). Read the status field to tell success from rejection:

  • status: "success" - numbers and phone_numbers are populated.
  • status: "error" - error_message carries the rejection reason.
HTTP: IntegrationApiKey

API key created on the Cockpit Integrations page (an "API key" integration). It is a bearer token owned by the customer's PBX and limited to the scopes selected when the key was created (e.g. phone-numbers, push-configuration).

Send it in the Authorization header:

Authorization: Bearer <api_key>

Manage keys (create / reveal / revoke) from Integrations → New integration → API key.

HTTP Authorization Scheme
bearer

Request body · required

Request schema
No request body schema.

Responses

Order accepted upstream and persisted on our side.
Response schema
idstring · uuid
Internal order id assigned by us. Use this with `GET /numbers/orders/{id}` to fetch the latest state. NOT the value echoed in the asynchronous webhook payload - that one is `order_id` (your own reference).
example: 550e8400-e29b-41d4-a716-446655440000
order_idstring | null
Your customer reference, supplied via the `order_id` field in `POST /numbers/orders` (or `POST /numbers/orders/{id}`). Echoed back here, in `GET /numbers/orders/{id}`, and at the top level of the asynchronous webhook payload (which is this same object) as `order_id`.
length: 0–64
example: po-2026-00042
customer_namestring
Legal name of the customer the numbers were ordered for, as supplied on create (and editable on retry).
example: ACME GmbH
statusstring
Lifecycle state of this order. * `requested`: sent upstream, awaiting fulfilment. * `submission_failed`: rejected during synchronous submission; editable + retryable. * `processing`: async success callback received; provisioning in progress. * `success`: provisioning complete; `numbers` is populated. * `error`: async rejection; terminal. * `processing_failed`: internal processing exhausted retries; admin-only retry.
enum: created requested submission_failed processing success error processing_failed
example: requested
addressobject
streetstring
example: Adenauerallee
street_numberstring
example: 1
postal_codestring
example: 53113
citystring
example: Bonn
area_codestring | null
Country-conditional (e.g. set for CH); null otherwise.
countrystring
example: DE
formatted_addressstring | null
Single-line, comma-separated address derived from the persisted components (street + number, postal code + city, country). Empty components are dropped.
example: Adenauerallee 1, 53113 Bonn, DE
quantityinteger
example: 1
prefixstring | null
Dial prefix in E.164 (country + area code if applicable).
example: +49228
numbersarray<string>
E.164-formatted numbers assigned to this order. Empty (`[]`) until the order reaches `success` - they are never returned synchronously by `POST /numbers/orders` (which only ever returns `requested`); they arrive later via the webhook and then appear here on `GET /numbers/orders/{id}`.
[]string
phone_numbersarray<object>
The assigned numbers, in the same shape as `GET /numbers` (id, number, name, is_active, call_flow), so you can read each number's id and current call flow and act on it directly (e.g. `PUT /numbers/{id}/call-flow`). Populated once the order reaches `success`.
idstring · uuid
example: 550e8400-e29b-41d4-a716-446655440000
numberstring
Phone number in E.164 format.
example: +12125550100
namestring | null
example: Customer Support
is_activeboolean
example: 1
call_flow_idstring | null · uuid
example: 550e8400-e29b-41d4-a716-446655440100
call_flowobject | null
idstring · uuid
namestring
enabledboolean
error_messagestring | null
Short error reason when status is `error` or `submission_failed`.
webhook_urlstring | null
The webhook URL we will POST the final outcome to.
webhook_statusstring
enum: not_required pending retrying delivered failed cancelled
webhook_next_retry_atstring | null · date-time
created_atstring · date-time
updated_atstring · date-time
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
Validation failed. `errors` maps each rejected field to its messages. If the order reached the carrier and was rejected there, it is persisted as a retryable `submission_failed` order and returned in `data` (the full order, same shape as `GET /numbers/orders/{id}`); use `data.id` to edit + retry it via `POST /numbers/orders/{id}`. When `data` is absent, no order was created.
Response schema
message*string
errors*object
Free-form object
dataobject
Present only for a carrier rejection (a retryable order was persisted). The full order - same shape as `GET /numbers/orders/{id}` - whose `id` you pass to `POST /numbers/orders/{id}` to edit + retry. Absent for local validation errors.
post https://cockpit.voxbi.com/api/v1/numbers/orders
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/numbers/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/numbers/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

const data = await response.json();
console.log(data);
import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/numbers/orders',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/numbers/orders', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
No request example provided.
{ … }
"id": "550e8400-e29b-41d4-a716-446655440000",
"order_id": "po-2026-00042",
"customer_name": "ACME GmbH",
"status": "requested",
"address": { … },
"street": "Adenauerallee",
"street_number": "1",
"postal_code": "53113",
"city": "Bonn",
"area_code": null,
"country": "DE"
},
"formatted_address": "Adenauerallee 1, 53113 Bonn, DE",
"quantity": 1,
"prefix": "+49228",
"numbers": [],
"phone_numbers": [],
"error_message": null,
"webhook_url": "https://your-app.example/hooks/number-order",
"webhook_status": "pending",
"webhook_next_retry_at": null,
"created_at": "2026-05-12T10:36:47+00:00",
"updated_at": "2026-05-12T10:36:47+00:00"
}
{ … }
"error": "Authorization Token is missing"
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"message": "The customer name field is required. (and 9 more errors)",
"errors": { … }
"customer_name": [ … ],
"The customer name field is required."
],
"street": [ … ],
"The street field is required."
],
"street_number": [ … ],
"The street number field is required."
],
"postal_code": [ … ],
"The postal code field is required."
],
"city": [ … ],
"The city field is required."
],
"country": [ … ],
"The country field is required."
],
"area_code": [ … ],
"The area code field is required."
],
"quantity": [ … ],
"The quantity field must be at least 1."
],
"webhook": [ … ],
"The webhook field must be a valid URL."
],
"order_id": [ … ]
"The order id field must not be greater than 64 characters."
]
}
}