Order a number
curl --request POST \ --url https://api.sipstack.com/api/v2/numbers/order \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "number": "+14165550100", "smsEnabled": true }'import requests
url = "https://api.sipstack.com/api/v2/numbers/order"
payload = { "number": "+14165550100", "smsEnabled": True}headers = { "x-api-key": "<x-api-key>", "Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = 'https://api.sipstack.com/api/v2/numbers/order';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"number":"+14165550100","smsEnabled":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}import axios from 'axios';
const options = { method: 'POST', url: 'https://api.sipstack.com/api/v2/numbers/order', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, data: {number: '+14165550100', smsEnabled: true}};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error);}Buys a number for your organization — a money-moving operation billed on your subscription exactly like a purchase from Switchboard (carrier order, monthly-rate persistence, trial-cap and card-verification gates, subscription linkage).
This endpoint is available by default and requires numbers:write.
Operators can disable programmatic ordering account-wide with the
NUMBERS_PUBLIC_ORDER_ENABLED platform kill-switch; while disabled the
endpoint returns 403 (“Number ordering is not enabled for API access.”).
Toll-free self-serve is additionally gated, and trialing organizations
must first pass the trial DID cap and card-verification checks (which
return 403 with a stable code). The carrier is resolved server-side —
never send a vendor name.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The number to buy, in E.164 or 10/11-digit form (typically one returned by search).
Example
+14165550100Request an SMS-capable number.
Responses
Section titled “ Responses ”Number ordered — the provisioned number record.
object
A number in your organization’s DID inventory, with assignment and provisioning detail. Upstream carrier/vendor fields are never exposed. Carries additional provisioning fields beyond those listed.
object
object
Example
{ "data": { "number": "+16473001234", "status": "active" }}number is missing or invalid.
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}Missing or invalid API key.
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}Ordering isn’t enabled for API access (gated), the key is missing the
numbers:write scope, the account API tier isn’t on your plan,
toll-free self-serve is gated, the trial DID cap is reached
(code: TRIAL_NUMBER_LIMIT_REACHED), or a payment card isn’t verified
(code: CARD_NOT_VERIFIED).
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}