Buy phone numbers with API v1.1

Browse Standard, Silver, and Gold numbers, preview their exact cost, and buy them with API v1.1.

Before you start

You need:

API client credentials and an access token;
enough account balance to cover the order;
the rate-card entry for the number product you want to buy.

The API v1.1 base URL is https://api.cloudnumbering.com/v1.1. These examples assume your access token is stored in CLOUDNUMBERING_ACCESS_TOKEN.

Warning: POST /v1.1/orders buys numbers and charges your balance. Preview the exact selection before creating an order.

Choose a rate-card entry

curl --silent --show-error \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  'https://api.cloudnumbering.com/v1.1/catalogue'

Choose the required entry and save its sid. Pass it as rateCardEntrySid when browsing prices, previewing, and creating the order. See List the available catalogue.

Catalogue and available-number prices cover number purchase and rental, not per-SMS or per-minute voice usage. rateCardSid and rateCardEntrySid on an order identify its purchase rate card and selected number product. Download separate SMS and voice usage rate cards from portal Rate Sheets. These order identifiers do not promise that future rental prices are fixed; confirm renewal price-change terms against your agreement.

Choose random or specific numbers

For random Standard allocation, skip browsing and use amount in the preview and order requests.

To choose specific numbers, request one or more public tiers:

curl --silent --show-error \
  --get \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --data-urlencode 'valueTiers=STANDARD,SILVER,GOLD' \
  --data-urlencode 'rateCardEntrySid=RE12345678901234567890123456789012' \
  --data-urlencode 'pattern=*777*' \
  --data-urlencode 'limit=20' \
  'https://api.cloudnumbering.com/v1.1/numbers/available'

pattern is an optional E.164 wildcard where * matches any digits. The response returns number-pool SIDs beginning with NB. Save the sid values you want to buy.

Each entry identifies its valueTier and, when rateCardEntrySid is supplied, its exact pricing. Silver has a £250 acquisition price at launch. Gold prices are per number and range from £400 to £700. Use the returned price rather than hard-coding these values.

Premium salePrice replaces the Standard selection fee. Normal connectionCharge and recurringRental still apply. The *Minor fields use cloudnumbering accounting units: GBP has 10,000 units per £1, so £250 is 2500000.

Browsing does not reserve numbers. Results and prices are checked again during preview and purchase. See List available numbers.

Preview the order

Send up to 100 unique number-pool SIDs in numberSids:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "numbers",
    "rateCardEntrySid": "RE12345678901234567890123456789012",
    "numberSids": [
      "NB12345678901234567890123456789012",
      "NB12345678901234567890123456789013"
    ]
  }' \
  'https://api.cloudnumbering.com/v1.1/orders/preview'

For random allocation, omit numberSids and provide amount from 1 to 1,000:

{
  "type": "numbers",
  "rateCardEntrySid": "RE12345678901234567890123456789012",
  "amount": 2
}

The preview is read-only. It returns exact aggregate and per-number pricing plus an opaque quoteToken. Store totalCostMinor and quoteToken for the create request. A selected order can mix Standard, Silver, and Gold numbers and completes in full or not at all.

See Preview an order's cost.

Create the order

Send the same selection with the accepted exact total and quote token:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 018f47a2-2f7c-7f59-9863-46d49f63e1b4' \
  --data '{
    "type": "numbers",
    "rateCardEntrySid": "RE12345678901234567890123456789012",
    "numberSids": [
      "NB12345678901234567890123456789012",
      "NB12345678901234567890123456789013"
    ],
    "expectedTotalCostMinor": 6510000,
    "quoteToken": "opaque-price-quote"
  }' \
  'https://api.cloudnumbering.com/v1.1/orders'

Idempotency-Key is optional. When supplied, it must be a UUID. Repeating the same canonical request with the same key returns the original result for at least 24 hours; changing the request with the same key returns idempotency_conflict.

The response contains the order SID, assigned numbers, and stored pricing. Premium acquisition prices are not refundable. See Create an order.

Retrieve the order

curl --silent --show-error \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  'https://api.cloudnumbering.com/v1.1/orders/NO12345678901234567890123456789012?page=1&perPage=100'

The stored order keeps the accepted aggregate and per-number price snapshot. Assigned-number SIDs begin with AN; use them for routing and later number management. See Get an order and its numbers.

Handle changes and failures

number_unavailable: refresh the available list and preview a new selection.
price_changed: preview again and ask the customer to accept the new total.
pricing_unavailable or tier_unavailable: do not fall back to Standard inventory; retry later or choose another tier.
insufficient_funds: add enough balance and preview again.
idempotency_in_progress: retry the same request and idempotency key after a short delay.
An unknown outcome with an idempotency key: retry the unchanged request with the same key or retrieve the order before creating a new logical order.