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.

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.

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.

Understand number SIDs

List assigned numbers

Filter the inventory

Disconnect a number

Reconnect a disconnected number

Related resources