Find and manage assigned numbers

Find assigned numbers, work through paginated results, and disconnect or reconnect a number safely with API v1.1.

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.

Understand number SIDs

Number responses can contain two different identifiers:

An assigned-number SID begins with AN. Use it to assign endpoints, disconnect the number, or refer to the number as a resource on your account.
A number-pool SID begins with NB. It identifies the underlying number selected before purchase.

Do not substitute one SID type for the other.

List assigned numbers

By default, the API returns the first page of in-service numbers:

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

Read the numbers from result.entries. Pagination information is in meta.pagination, including page, perPage, pageCount, and total. Request another page by incrementing the page query parameter until you reach pageCount.

perPage can be between 1 and 100. See List your assigned numbers for the response schema.

Filter the inventory

The number list supports these filters:

Filter	Behavior
`e164`	Exact E.164 lookup. Returns at most one entry and ignores pagination.
`alias`	Partial customer-reference match.
`status`	`IN_SERVICE`, `PORT_IN`, `PORT_OUT`, or `DISCONNECTED`. Repeat it or use a comma-separated list.
`nextBillingDateFrom`	Numbers with a next billing date on or after the supplied date.
`nextBillingDateTo`	Numbers with a next billing date on or before the supplied date.

When status is omitted, only IN_SERVICE numbers are returned.

Find one number by its E.164 value:

curl --silent --show-error \
  --get \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --data-urlencode 'e164=+447700900000' \
  'https://api.cloudnumbering.com/v1.1/numbers'

Find disconnected numbers:

curl --silent --show-error \
  --get \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --data-urlencode 'status=DISCONNECTED' \
  --data-urlencode 'page=1' \
  --data-urlencode 'perPage=100' \
  'https://api.cloudnumbering.com/v1.1/numbers'

An exact lookup that finds no accessible matching number returns an empty result.entries array.

Understand rental and automatic renewal

nextBillingDate is the next rental billing date, returned as a UTC timestamp when present. It is not a scheduled disconnection date. numberRental is the number's currently stored rental amount. These fields do not include SMS or voice usage charges.

For an in-service number with auto-renew enabled, cloudnumbering attempts to collect the renewal automatically when it becomes due. You do not need to place another order each month. After a successful renewal, nextBillingDate advances.

If the balance cannot cover renewal, the number becomes overdue. cloudnumbering retries overdue in-service numbers with auto-renew enabled once a day. Overdue billing normally leads to disconnection after seven days, but some organisations are exempt. See Fixing failed number renewals for exceptions and the portal's Overdue filter. The seven-day overdue period and the seven-day self-service reconnection window are separate periods.

The API supports status as a list filter, including IN_SERVICE and DISCONNECTED, but it does not return a status or autoRenew field on each v1.1 number object. There is no OVERDUE filter value. Use an explicit status=DISCONNECTED query to find disconnected numbers; the default list only includes in-service numbers. A billing date alone does not confirm a successful charge.

API v1.1 has no operation to change auto-renew or schedule cancellation at the end of a term. It also provides no published renewal-event webhook. See Billing and usage for API integrations for reporting options and rental terms to confirm before implementing your own billing policy.

Disconnect a number

Warning: Disconnecting stops calls and messages on the number. Do not disconnect a number that you intend to port to another provider.

Disconnection takes effect immediately and stops future automatic rental renewals while the number is disconnected. It does not wait until nextBillingDate or establish a refund entitlement for the current rental period.

Treat disconnect as a destructive operation. Before sending the request:

Confirm the assigned-number SID and E.164 number against a fresh list response.
Check that no service still depends on the number.
Require explicit confirmation in your application or operational process.
Start a port-out request instead if the number is moving to another provider.

Disconnect the assigned number:

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

A successful disconnect returns HTTP 204 with no response body. A 404 means the assigned number was not found for your organisation. Any other failure — invalid input and upstream faults alike — currently returns HTTP 400 with the generic body {"success": false, "error": "Failed to disconnect number"}, so the response cannot tell you whether to correct the request or retry later. Re-check the number's status with a fresh list request before acting. See Disconnect a number.

Reconnect a disconnected number

A disconnected number can be reconnected self-service for seven days. It must have auto-renew turned on, and it must have been disconnected by you — through the portal or the API — or for overdue billing. A ported-out number cannot be reconnected.

Reconnecting is chargeable: the cost includes any overdue renewals as well as reconnection charges. Preview first, then reconnect:

POST /v1.1/numbers/reconnect/preview returns the cost breakdown without changing anything.
POST /v1.1/numbers/reconnect creates the reconnect request and charges your balance. It accepts an idempotencyKey UUID — generate the key before the first attempt and reuse exactly the same key and body to retry safely after an unknown outcome.
GET /v1.1/numbers/reconnect/{requestSid} reports the state of a request, using the requestSid returned when it was created.

A reconnect request accepts up to 100 numbers and is all-or-nothing: if any number in it is ineligible, no number in the request reconnects. Remove the ineligible numbers and submit again. See the API reference for the complete request and response schemas.