Skip to content

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.

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 · multipart/form-data

Request schema
customer_name*string
Legal name of the customer the numbers are ordered for. Required; forwarded to the carrier, which records and may validate it.
length: 0–255
example: ACME GmbH
street*string
example: Adenauerallee
street_number*string
example: 1
postal_code*string
example: 53113
city*string
example: Bonn
area_codestring | null
Country-conditional. Required for some countries (e.g. Switzerland, `CH`, where it would be something like `43`) and rejected (422) for others - it is `null` for the `DE` example here. Use the same value you sent to `POST /numbers/orders/check`.
length: 0–16
country*string
example: DE
quantity*integer
≥ 1
example: 1
webhookstring | null · uri
Optional URL we POST to once the order is fulfilled. The order is accepted asynchronously (this endpoint returns `201` with status `requested`), so the assigned numbers - or a rejection - are delivered here later, not in this response. See **Webhooks** in the *Phone Number Orders* introduction for the events, headers and signature. The same state can also be fetched from `GET /numbers/orders/{id}`.
length: 0–500
example: https://your-app.example/hooks/number-order
order_idstring | null
Deprecated - use `custom_order_reference` instead (same meaning, new name). Still accepted for backward compatibility. Sending both `order_id` and `custom_order_reference` with *different* values is rejected (422); sending both with the same value is fine.
length: 0–64deprecated
example: po-2026-00042
custom_order_referencestring | null
Optional customer reference (any short string, max 64 chars), opaque to us and to the carrier. Echoed back in the response, in `GET /numbers/orders`, in `GET /numbers/orders/{id}`, and in every webhook payload (the webhook body is the same order object). If omitted (and `order_id` is not sent either), the upstream provider generates one and we backfill it on your row.
length: 0–64
example: po-2026-00042
kycobject
KYC documents, one entry per `documentType` returned by `POST /numbers/orders/check` for the country. Required when `kyc_required_at_order` is `true`; optional when `false`, in which case you can send them later with `POST /numbers/orders/{id}/documents`. Send file documents as a file part `kyc[<documentType>]` and identifier-only documents as a form field `kyc[<documentType>]=<value>`. Accepted file types: `application/pdf`, `image/jpeg`, `image/png`. For an OR group returned by the check endpoint (an array of types), provide any one of the listed `documentType`s.
business_registration_certificatefile · application/pdf
Business registration certificate (file part `kyc[business_registration_certificate]`). PDF, JPEG or PNG.
example: certificate.pdf
utility_billfile · application/pdf
Utility bill (file part `kyc[utility_bill]`). PDF, JPEG or PNG.
example: bill.pdf
id_documentfile · image/jpeg
Identity document (file part `kyc[id_document]`). PDF, JPEG or PNG.
example: passport.jpg
business_registration_numberstring
Identifier-only document, sent as a plain form field `kyc[business_registration_number]`. **Required for a French order (`country` `FR`)**: the company's SIRET, at order time, even when `kyc_required_at_order` is `false`. Spaces are stripped.
length: 0–255
example: BE-12345

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, and `POST /numbers/orders/{id}/documents` to send KYC documents. Also the `id` in every webhook payload (the webhook body is this same object). Your own reference is `custom_order_reference`.
example: 550e8400-e29b-41d4-a716-446655440000
order_idstring | null
DEPRECATED: same value as `custom_order_reference`, kept for existing integrations. Read `custom_order_reference` instead.
length: 0–64deprecated
example: po-2026-00042
custom_order_referencestring | null
Your own reference for the order, supplied as `custom_order_reference` (or the deprecated `order_id`) on `POST /numbers/orders`. Echoed back here, in `GET /numbers/orders` (filterable by it) and in every webhook payload. If you sent none, the carrier's generated one is backfilled here.
length: 0–64
example: po-2026-00042
order_referencestring | null · uuid
The carrier's own identifier for this order (a UUID they assign). Null until the order is placed. This is the reference the carrier says to use to identify the order, and it is distinct from `custom_order_reference` (your own reference, opaque to the carrier). Not settable by you.
example: 01a0ae76-0000-4000-8000-000000000000
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. * `success_kyc_required`: the numbers are provisioned (`numbers` is populated) but the carrier has not validated the KYC yet; see `kyc`. Moves to `success` once the KYC is validated. * `error`: async rejection; terminal. * `processing_failed`: internal processing exhausted retries; admin-only retry. * `canceled`: a reseller closed a `submission_failed` order that provably never reached the carrier; terminal. Nothing was canceled at the carrier and no webhook is sent.
enum: created requested submission_failed processing success success_kyc_required error processing_failed canceled
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`.
kycobject
The order's KYC (know-your-customer) progress with the carrier. Present on every order, including orders placed with KYC deferred (`kyc_required_at_order: false` on `POST /numbers/orders/check`), where `missing` lists what is still to be sent via `POST /numbers/orders/{id}/documents`.
statestring | null
Overall KYC state. * `pending`: no verdict yet. * `validated`: the carrier signed the KYC off (`validated_at` is set). * `rejected`: not validated and at least one provided document is rejected. Null until the carrier has reported on this order.
enum: pending validated rejected null
example: pending
validated_atstring | null · date-time
When the carrier validated the KYC. Null until then.
providedarray<object>
Documents the carrier has on file, with their individual verdict.
Each item — One KYC document the carrier has on file for the order, with the carrier's verdict on it.
document_typestring | null
The KYC document type code (the `documentType` you uploaded it under).
example: utility_bill
statusstring | null
The carrier's verdict on this document. * `pending`: received, not reviewed yet. * `accepted`: reviewed and accepted. * `rejected`: reviewed and refused; see `rejection_reason` and upload a replacement. * `unknown`: the carrier reported a status we do not recognize.
enum: pending accepted rejected unknown null
example: accepted
rejection_reasonstring | null
Why the carrier refused the document. Null unless `status` is `rejected`.
created_atstring | null · date-time
When the carrier received the document (a replacement carries a new value).
example: 2026-05-12T11:15:03+00:00
updated_atstring | null · date-time
When the carrier last changed the document (for example reviewed it).
example: 2026-05-13T08:02:41+00:00
missingarray<object>
Documents still needed. Each entry is either an object (that exact document is needed) or an array of objects (provide any ONE of them), like `kycRequirements` on the check endpoint.
[]object
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' \
  -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);
Sample request · multipart/form-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_certificate": "certificate.pdf",
"utility_bill": "bill.pdf",
"id_document": "passport.jpg",
"business_registration_number": "BE-12345"
}
}
{ … }
"id": "550e8400-e29b-41d4-a716-446655440000",
"order_id": "po-2026-00042",
"custom_order_reference": "po-2026-00042",
"order_reference": "01a0ae76-0000-4000-8000-000000000000",
"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,
"kyc": { … },
"state": "pending",
"validated_at": null,
"provided": [],
"missing": [ … ]
[ … ],
{ … },
"document_type": "business_registration_certificate",
"notes": "Handelsregister"
},
{ … }
"document_type": "utility_bill",
"notes": "Dated within 3 months"
}
],
{ … }
"document_type": "id_document",
"notes": 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."
]
}
}