---
title: "Order a wholesale number"
method: POST
path: "/api/v1/wholesale/numbers"
tags: ["Wholesale"]
---

# Order a wholesale number

`POST /api/v1/wholesale/numbers`

## Request

- Base URL: `https://api.callnode.io`
- URL: `https://api.callnode.io/api/v1/wholesale/numbers`
- Auth: API key in header `X-Api-Key` and API key in header `X-Timestamp` and API key in header `X-Signature`

Allocates a number from an area and starts delivering its inbound
calls to your SIP endpoint. Prepaid: the first month at your contract
rate is charged from your wallet at allocation, then monthly; inbound
minutes are charged per call as they complete.

`deliverTo` accepts three forms:
- a bare host (`pbx.example.com` or a public IP) — we deliver as
  `sip:<allocated-number>@host`
- a sip: URI containing `{number}` — replaced with the allocated number
- a full `sip:` URI, used verbatim

Allocation can take up to ~40 seconds. On `order_failed` for a specific
area, order from a DIFFERENT area — retrying the same one will not help.

## Headers

- `X-Idempotency-Key` string, uuid

## Request body

- object
  - `areaId` string, required: From `/wholesale/areas`
  - `deliverTo` string, required: Host, `{number}` template, or full sip URI (public hosts only).
  - `friendlyName` string
  - `countryId` string: Pass when ordering outside the US.

## Response `201`

Number allocated, delivering, and charged.

- object
  - `number` object
    - `id` string
    - `phoneNumber` string: Plus sign followed by 7–15 digits.
    - `areaName` string, nullable
    - `areaCode` string, nullable
    - `deliverTo` string
  - `charged` number: First month
  - `monthlyRate` number
  - `wallet` object
    - `balance` number
  - `billing` 'wallet'

## Other responses

- `400`: Missing/invalid areaId or deliverTo (private hosts are refused).
- `402`: Insufficient wallet balance — nothing was ordered.
- `403`: Wholesale not active, verification incomplete, or rates not configured.
- `502`: The area could not be provisioned — order from a different area.

---

[API](https://skmtc.dev/callnode/apis/callnode-outbound-api.md) · [All operations](https://skmtc.dev/callnode/apis/callnode-outbound-api/llms.txt) · [OpenAPI document](https://skmtc.dev/callnode/apis/callnode-outbound-api/revisions/c7da6ad06509?raw)