Understand API v1.1 conventions

Use the common response, identifier, phone-number, timestamp, pagination and request-tracing conventions in cloudnumbering API v1.1.

The API v1.1 base URL is https://api.cloudnumbering.com/v1.1. Use the generated API reference for each endpoint's complete contract.

Read response envelopes

Most successful endpoints return success and result:

{
  "success": true,
  "result": {
    "sid": "EP12345678901234567890123456789012"
  }
}

Paginated responses add meta. Most endpoint failures return success: false and a human-readable error:

{
  "success": false,
  "error": "Invalid request"
}

When an endpoint response contains success, require both a successful HTTP status and success: true before treating the operation as successful. Some current error paths can return success: false with a 2xx status.

Token-endpoint failures and authentication failures on any endpoint are an exception: they use OAuth fields named error and error_description, with no success field at all. Check the HTTP status before looking for success, or a 401 body will read as undefined. Some operations can add endpoint-specific result or error fields, so check the reference before writing a shared response parser.

Treat identifiers as opaque

Resource identifiers are strings, often called SIDs. Current examples use prefixes such as AN for an assigned number, EP for an endpoint, NO for a number order, NB for an available number, OR for an organisation, IN for an invoice and RE for a rate-card entry.

Store the complete identifier returned by the API. Do not construct an identifier, change its case or derive business meaning from its length.

Format phone numbers for each field

When a field requires E.164 format, send +, the country code and the subscriber number without spaces or punctuation. For example:

+447700900000

Not every phone-related field has the same rules. For example, an inbound SMS sender can be alphanumeric. Follow the field description in the API or webhook guide instead of applying E.164 validation to every value.

Parse timestamps and dates deliberately

Fields documented as date-time are RFC 3339 timestamp strings. A value ending in Z, such as 2026-04-02T09:00:00.000Z, is in UTC. Preserve the offset when parsing or storing it.

Some request fields are calendar dates instead of timestamps. For example, a requested port date uses YYYY-MM-DD and has no time or UTC offset. Check the endpoint reference before converting a date to a timestamp.

Paginate list responses

List endpoints that expose standard pagination accept a 1-based page and a perPage value from 1 to 100. The usual default is 10 entries per page.

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

The response includes pagination counts and navigation links:

{
  "meta": {
    "pagination": {
      "page": 2,
      "perPage": 10,
      "pageCount": 6,
      "total": 52
    },
    "links": {
      "self": "https://api.cloudnumbering.com/v1.1/numbers?page=2",
      "next": "https://api.cloudnumbering.com/v1.1/numbers?page=3",
      "prev": "https://api.cloudnumbering.com/v1.1/numbers?page=1",
      "first": "https://api.cloudnumbering.com/v1.1/numbers?page=1",
      "last": "https://api.cloudnumbering.com/v1.1/numbers?page=6"
    }
  }
}

Follow meta.links to walk pages: self, next, prev, first and last keep the current request's origin, API version and query filters, replacing only page and perPage. Each link can be null — all five are null for an empty result (total: 0, pageCount: 1) — so check for null before following one. A generated link omits perPage when it equals the default of 10.

Not every list endpoint exposes these query parameters. Use the endpoint reference rather than adding page and perPage to every request.

Capture request IDs

Documented endpoint responses normally include an X-Request-Id header. Record it with the UTC time, HTTP method, path and status when diagnosing a request.

Do not log access tokens, client secrets, message bodies or complete phone numbers with the request ID. Some failures that happen before an endpoint handler runs do not currently include the header, so treat it as optional in client code.