Buy phone numbers with API v1.1

Find available phone numbers, preview their 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 type of number you want to buy.

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

Warning: POST /v1.1/orders buys numbers and charges your account. Use the preview endpoint before creating an order.

1. Choose a rate-card entry

List the number products available to your organisation:

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

Choose the product you need and save its sid. You will pass that value as rateCardEntrySid in the preview and order requests.

Each catalogue entry also describes the recurring cost, one-off connection charge, currency, and purchase terms. The endpoint currently returns at most 10 entries and has no paging parameters, so contact support if a rate-card entry you expect is missing. See List the available catalogue for the complete response schema.

2. Choose specific numbers or request random allocation

To choose specific numbers, browse the available pool:

curl --silent --show-error \
  --get \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --data-urlencode 'pattern=*123*' \
  --data-urlencode 'limit=10' \
  'https://api.cloudnumbering.com/v1.1/numbers/available'

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

Note: Only standard numbers are sold self-service. Premium and memorable ("vanity") numbers are filtered out of the available pool with no indication in the response, so a memorable-digit search such as pattern=*123* can return few or no results. Contact sales to buy a premium number.

Results are returned in random order, and there is no paging: each request returns at most 100 numbers sampled from the pool, and repeating the same request returns different numbers. totalAvailable counts the whole matching pool, not numbers you can list, so treat it as a measure of depth rather than a set you can walk.

Skip this step if you want cloudnumbering to allocate numbers randomly. See List available numbers for all query and response fields.

3. Preview the order

For specific numbers, send their 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 a positive integer amount instead:

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

The preview is read-only: it does not reserve numbers, debit your balance, or create an order. A specific selection can include up to 100 unique number SIDs. If you provide both amount and numberSids, the amount must equal the number of SIDs.

Review the recurring rental, connection charge, total cost, and billing dates in result. Choosing specific numbers adds a flat £0.50 per-number selection fee, included in the returned connection charge and total cost; random allocation has no selection fee. See Preview an order's cost for the complete schema.

4. Create the order

After reviewing the preview, send the same body to the order endpoint:

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'

The create response includes the purchased numbers in result.numbers, so a second request is not needed to obtain them. Save the order sid and the returned number details. The API does not accept an idempotency key or client reference for number orders.

Never retry an order automatically after a timeout or another response with an unknown outcome. Inspect recent orders, assigned numbers, and your balance first. Those checks may still be unable to prove whether one particular request completed. If the outcome remains uncertain, stop and contact support with the request ID when available instead of submitting the order again.

Availability can change between preview and purchase: another buyer can take a number, or a number can be reclassified out of self-service sale, in which case the order fails even though the number still appears to exist. Treat the create response as the source of truth for whether the order succeeded. See Create an order for the complete schema.

5. Retrieve an order later

To re-fetch an order's numbers later, or to check whether an order completed after an unknown outcome, use the order SID:

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

The assigned numbers are in result.numbers. Their assigned-number SIDs begin with AN; use those SIDs when assigning routing endpoints or managing a number later. See Get an order and its numbers.