List phone number orders (pbx)

List the orders placed by your PBX, newest first, paginated. Use custom_order_reference to find the order(s) you placed under your own reference. Each item is the same order object as GET /numbers/orders/{id}, including the kyc block.

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

custom_order_reference query · string

Only orders placed with exactly this `custom_order_reference` (max 64 characters).

per_page query · integer

Number of items per page. Defaults to `100`, maximum `5000`. A value above the maximum is rejected with `422` rather than silently truncated.

page query · integer

Page number to fetch. Defaults to `1`.

Responses

One page of orders, newest first.

Response schema

dataarray<object>

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

linksobject

firststring

The first page of the resource

example: http://localhost/api/v1/resources?page=1

laststring

The last page of the resource

example: http://localhost/api/v1/resources?page=1

prevnull | string

The previous page of the resource

nextnull | string

The next page of the resource

metaobject

current_pageinteger

The current page of the resource

≥ 1

example: 1

fromnull | integer

The first item of the resource

≥ 1

example: 1

last_pageinteger

The last page of the resource

≥ 1

example: 1

linksarray<object>

urlstring | null

The url of the resource (null for the boundary prev/next links)

example: http://localhost/api/v1/resources?page=1

labelstring

The label of the resource

example: first

activeboolean

The status of the resource

example: 1

pathstring

The path of the resource

example: http://localhost/api/v1/resources

per_pageinteger

The number of items per page of the resource

≥ 1

example: 15

tonull | integer

The last item of the resource

≥ 1

example: 1

totalinteger

The total number of items of the resource

≥ 0

example: 1

Authorization Token Missing. This error is returned when the authorization token is missing.

Response schema

errorstring

Error message

example: Authorization Token is missing

A query parameter is invalid. Same `{ message, errors }` shape as every other API validation error.

Response schema

message*string

errors*object

Free-form object

get https://cockpit.voxbi.com/api/v1/numbers/orders

Base URL

Request sample

curl -X GET '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: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

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

import requests

response = requests.get('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'  => 'GET',
        '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);

{ … }

"data": [ … ],

{ … }

"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": "success_kyc_required",

"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": [ … ],

"+4922812345678"

"phone_numbers": [ … ],

{ … }

"id": "550e8400-e29b-41d4-a716-446655440001",

"number": "+4922812345678",

"name": null,

"is_active": true,

"call_flow_id": null,

"call_flow": null

}

"error_message": null,

"kyc": { … },

"state": "pending",

"validated_at": null,

"provided": [ … ],

{ … }

"document_type": "utility_bill",

"status": "pending",

"rejection_reason": null,

"created_at": "2026-05-12T11:15:03+00:00",

"updated_at": "2026-05-12T11:15:03+00:00"

}

"missing": [ … ]

{ … }

"document_type": "id_document",

"notes": null

}

]

"webhook_url": "https://your-app.example/hooks/number-order",

"webhook_status": "delivered",

"webhook_next_retry_at": null,

"created_at": "2026-05-12T10:36:47+00:00",

"updated_at": "2026-05-12T10:41:19+00:00"

}

"links": { … },

"first": "https://cockpit.voxbi.com/api/v1/numbers/orders?page=1",

"last": "https://cockpit.voxbi.com/api/v1/numbers/orders?page=1",

"prev": null,

"next": null

"meta": { … }

"current_page": 1,

"from": 1,

"last_page": 1,

"links": [ … ],

{ … },

"url": null,

"label": "« Previous",

"active": false

{ … },

"url": "https://cockpit.voxbi.com/api/v1/numbers/orders?page=1",

"label": "1",

"active": true

{ … }

"url": null,

"label": "Next »",

"active": false

}

"path": "https://cockpit.voxbi.com/api/v1/numbers/orders",

"per_page": 100,

"to": 1,

"total": 1

}

{ … }

"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 per page field must not be greater than 5000.",

"errors": { … }

"per_page": [ … ]

"The per page field must not be greater than 5000."

]

}

No matching endpoints

List phone number orders (pbx)

Responses