API Docs
Voxbi Cockpit APIs
All endpoints

Check whether a phone number can be ordered at a given address

Pre-flight check that validates an address with the upstream registry and returns (a) the dial prefix for the resolved location, (b) the geocoder's resolvedAddress, and (c) the kycRequirements that must accompany the future order. Call this before POST /numbers/orders.

Comparing the address

The address is geocoded, so resolvedAddress may differ from what you sent (address echoes your input). Compare the two and, if they differ, confirm the corrected values with the end user before placing the order - the order endpoint persists the geocoder-resolved values. Structured fields in resolvedAddress are nullable (the geocoder may fail to pin a component such as the street number); formattedAddress is always present.

Working with kycRequirements

kycRequirements lists the KYC documents that must be supplied on POST /numbers/orders. Each top-level entry is either:

  • an object - that exact document is required, or
  • an array of objects - you must provide any one of the documents listed inside (an "OR group").

So the example below requires two documents in total:

  • either a business_registration_certificate or a utility_bill (the OR group), and
  • an id_document (the standalone entry).

Each documentType is the code you reference when uploading on POST /numbers/orders: send file documents as a file part kyc[<documentType>] (e.g. kyc[utility_bill] carrying bill.pdf; accepted MIME types application/pdf, image/jpeg, image/png), and identifier-only documents as a form field kyc[<documentType>]=<value> (e.g. kyc[business_registration_number]=BE-12345).

The optional notes field carries country-specific context (the local name of the document, or a freshness constraint such as "dated within 3 months") and can be surfaced verbatim to the end user.

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
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 must be omitted for others - it is `null` for the `DE` example here. Send the same value you will send to `POST /numbers/orders`.
length: 0–16
country*string
ISO 3166-1 alpha-2 country code.
length: 2–2
example: DE

Responses

Address resolved successfully; KYC requirements returned.
Response schema
addressobject
Echo of the address components you submitted.
streetstring
example: Adenauerallee
street_numberstring
example: 1
postal_codestring
example: 53113
citystring
example: Bonn
countrystring
example: DE
resolvedAddressobject
Address as resolved by the geocoder. Compare against `address` to detect corrections. Structured fields are nullable; `formattedAddress` is always present.
streetstring | null
example: Adenauerallee
streetNumberstring | null
example: 1
postalCodestring | null
example: 53113
citystring | null
example: Bonn
countrystring | null
example: DE
formattedAddressstring
Human-readable resolved address. Always present.
example: Adenauerallee 1, 53113 Bonn, Germany
prefixstring
Dial prefix for the resolved location in E.164 form with a leading `+` (country prefix plus area code where applicable).
example: +49228
kycRequirementsarray<object>
KYC documents required on the future order. Each entry is either a single requirement object, or an array of objects meaning "provide any one of these". See the endpoint description for how to upload each `documentType`.
[]object
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
The address failed validation - locally or upstream (e.g. it could not be resolved, or your account may not order numbers for that country). Same `{ message, errors }` shape as every other API validation 422, with `errors` mapping each rejected field to its messages. No order is created at this stage, so there is no `data`. When an upstream error has no field to attach to, `errors` is an empty object `{}` and `message` carries the reason.
Response schema
message*string
errors*object
Free-form object
post https://cockpit.voxbi.com/api/v1/numbers/orders/check
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/numbers/orders/check' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/numbers/orders/check', {
  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/check',
    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/check', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
No request example provided.
{ … }
"address": { … },
"street": "Adenauerallee",
"street_number": "1",
"postal_code": "53113",
"city": "Bonn",
"country": "DE"
},
"resolvedAddress": { … },
"street": "Adenauerallee",
"streetNumber": "1",
"postalCode": "53113",
"city": "Bonn",
"country": "DE",
"formattedAddress": "Adenauerallee 1, 53113 Bonn, Germany"
},
"prefix": "+49228",
"kycRequirements": [ … ]
[ … ],
{ … },
"documentType": "business_registration_certificate",
"notes": "Handelsregister"
},
{ … }
"documentType": "utility_bill",
"notes": "Dated within 3 months"
}
],
{ … }
"documentType": "id_document"
}
]
}
{ … }
"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 street field is required. (and 1 more error)",
"errors": { … }
"street": [ … ],
"The street field is required."
],
"street_number": [ … ]
"The street number field is required."
]
}
}