Place a phone number order (pbx)
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 custom_order_reference (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_id is the deprecated name for the same field: it is
still accepted, but sending both order_id and custom_order_reference
with different values is rejected (422) - identical values are fine.
The response also carries order_reference, the carrier's own identifier
for the order (a UUID); use it to identify the order with the carrier
(e.g. their support, or their KYC-document endpoint).
KYC at order, or after
POST /numbers/orders/check returns kyc_required_at_order. When true, send the
KYC documents listed in kycRequirements with this request. When false (your
account's contract lets documents follow the order), kyc is optional here: the
order is placed without it, and you send the documents later with
POST /numbers/orders/{id}/documents. The order's kyc block (state,
provided, missing) shows what is still owed, and the webhook tells you when
each document is reviewed and when the KYC is validated.
Asynchronous outcome and webhooks
Order fulfilment is asynchronous. This endpoint returns 201 as soon as the
order is accepted upstream. Progress is delivered to your webhook URL (if
provided) as one signed POST per event (order.fulfilled, order.failed,
order.canceled, kyc.document_accepted, kyc.document_rejected,
kyc.validated), and the current state is always queryable via
GET /numbers/orders/{id}. Every body is the same order object as
GET /numbers/orders/{id} plus event, delivery_id and, on document events,
kyc_document. The Webhooks part of the Phone Number Orders introduction
describes every event, the X-Voxbi-* headers, the retry schedule and how to
verify the signature (the signing secret is managed in Cockpit under Settings, API
keys and secrets, Webhook signing secret). Each event also has its own entry in
the reference's Webhooks section, in viewers that show one.
Documents already on file
For an order on a shared (deferred) carrier contract, documents your account
already holds for the order's address (for example from an earlier order or
from the Account verification page in Cockpit) may be sent to the carrier
automatically once the address verification has been approved. The order's
kyc.provided then lists them and kyc.document_* webhook events may follow. Nothing
is attached automatically to an order on a contract that requires KYC at order
time, and documents uploaded through this API are not kept for later orders.
France: SIRET required at order time
A French order (country FR) must carry the company's SIRET as
kyc[business_registration_number] on this request, even when
kyc_required_at_order is false. It cannot be sent later with
POST /numbers/orders/{id}/documents. Without it the order is refused with 422.
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 · multipart/form-data
ACME GmbHAdenauerallee153113BonnDE1https://your-app.example/hooks/number-orderpo-2026-00042po-2026-00042kycobject
certificate.pdfbill.pdfpassport.jpgBE-12345Responses
550e8400-e29b-41d4-a716-446655440000po-2026-00042po-2026-0004201a0ae76-0000-4000-8000-000000000000ACME GmbHcreated requested submission_failed processing success success_kyc_required error processing_failed canceledrequestedaddressobject
Adenauerallee153113BonnDEAdenauerallee 1, 53113 Bonn, DE1+49228numbersarray<string>
phone_numbersarray<object>
550e8400-e29b-41d4-a716-446655440000+12125550100Customer Support1550e8400-e29b-41d4-a716-446655440100call_flowobject | null
kycobject
pending validated rejected nullpendingprovidedarray<object>
utility_billpending accepted rejected unknown nullaccepted2026-05-12T11:15:03+00:002026-05-13T08:02:41+00:00missingarray<object>
not_required pending retrying delivered failed cancelledAuthorization Token is missingerrors*object
https://cockpit.voxbi.com/api/v1/numbers/orders
curl -X POST 'https://cockpit.voxbi.com/api/v1/numbers/orders' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-F 'customer_name=ACME GmbH' \
-F 'street=Adenauerallee' \
-F 'street_number=1' \
-F 'postal_code=53113' \
-F 'city=Bonn' \
-F 'area_code=string' \
-F 'country=DE' \
-F 'quantity=1' \
-F 'webhook=https://your-app.example/hooks/number-order' \
-F 'order_id=po-2026-00042' \
-F 'custom_order_reference=po-2026-00042' \
-F 'kyc[business_registration_certificate]=@certificate.pdf' \
-F 'kyc[utility_bill]=@bill.pdf' \
-F 'kyc[id_document]=@passport.jpg' \
-F 'kyc[business_registration_number]=BE-12345'
const body = new FormData();
body.append('customer_name', 'ACME GmbH');
body.append('street', 'Adenauerallee');
body.append('street_number', '1');
body.append('postal_code', '53113');
body.append('city', 'Bonn');
body.append('area_code', 'string');
body.append('country', 'DE');
body.append('quantity', '1');
body.append('webhook', 'https://your-app.example/hooks/number-order');
body.append('order_id', 'po-2026-00042');
body.append('custom_order_reference', 'po-2026-00042');
body.append('kyc[business_registration_certificate]', fileInput.files[0]); // certificate.pdf
body.append('kyc[utility_bill]', fileInput.files[0]); // bill.pdf
body.append('kyc[id_document]', fileInput.files[0]); // passport.jpg
body.append('kyc[business_registration_number]', 'BE-12345');
const response = await fetch('https://cockpit.voxbi.com/api/v1/numbers/orders', {
method: 'POST',
headers: { Authorization: `Bearer ${YOUR_TOKEN}` },
body,
});
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}'},
data={
'customer_name': 'ACME GmbH',
'street': 'Adenauerallee',
'street_number': '1',
'postal_code': '53113',
'city': 'Bonn',
'area_code': 'string',
'country': 'DE',
'quantity': '1',
'webhook': 'https://your-app.example/hooks/number-order',
'order_id': 'po-2026-00042',
'custom_order_reference': 'po-2026-00042',
'kyc[business_registration_number]': 'BE-12345',
},
files={
'kyc[business_registration_certificate]': open('certificate.pdf', 'rb'),
'kyc[utility_bill]': open('bill.pdf', 'rb'),
'kyc[id_document]': open('passport.jpg', 'rb'),
},
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$ch = curl_init('https://cockpit.voxbi.com/api/v1/numbers/orders');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_TOKEN']);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'customer_name' => 'ACME GmbH',
'street' => 'Adenauerallee',
'street_number' => '1',
'postal_code' => '53113',
'city' => 'Bonn',
'area_code' => 'string',
'country' => 'DE',
'quantity' => '1',
'webhook' => 'https://your-app.example/hooks/number-order',
'order_id' => 'po-2026-00042',
'custom_order_reference' => 'po-2026-00042',
'kyc[business_registration_certificate]' => new CURLFile('certificate.pdf'),
'kyc[utility_bill]' => new CURLFile('bill.pdf'),
'kyc[id_document]' => new CURLFile('passport.jpg'),
'kyc[business_registration_number]' => 'BE-12345',
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
{ … }
"kyc": { … }
{ … }
"address": { … },
"kyc": { … },
"missing": [ … ]
[ … ],
{ … },
{ … }
{ … }
{ … }
private, must-revalidatekeep-aliveapplication/jsonOrigin6057