Port numbers with API v1.1

Create port-in or port-out requests and track their status with API v1.1.

Warning: Do not disconnect a number that you want to port out. Create a port-out request while the number remains assigned to your organisation.

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.

Before you start

For port-in requests, you need:

a number in E.164 format;
the PAC supplied by the losing provider;
the requested port date as a London local date in YYYY-MM-DD format;
an eligible rate-card entry SID beginning with RE;
an organisation for which API port-in is enabled.

The API returns HTTP 403 when port-in is not enabled for the organisation. Contact cloudnumbering support if you need eligibility, number-type, country, lead-time, or contract guidance.

For port-out requests, you need the assigned-number SID beginning with AN. Use GET /v1.1/numbers to find it.

Create port-in requests

POST /v1.1/porting/in accepts between 1 and 100 entries. Give every entry a stable idempotency UUID so that retrying the same request can reuse the existing port order instead of creating another one. Generate and store a new UUID for each logical entry:

PORT_IN_IDEMPOTENCY_KEY="$(uuidgen)"

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data @- \
  'https://api.cloudnumbering.com/v1.1/porting/in' <<JSON
{
    "entries": [
      {
        "e164": "+447700900000",
        "pac": "ABC123",
        "requestedPortDate": "2026-08-17",
        "rateCardEntrySid": "RE12345678901234567890123456789012",
        "idempotencyKey": "$PORT_IN_IDEMPOTENCY_KEY",
        "clientReference": "migration-batch-7-row-1"
      }
    ]
}
JSON

This operation creates real port-in requests; it is not a preview. A successful HTTP response can contain a mixture of created or reused orders in result.orders and rejected entries in result.errors. Inspect both arrays before marking the batch as accepted. clientReference is included with per-entry errors; match successful or reused orders by their E.164 number and returned order SID.

Reuse the same idempotencyKey when retrying the same entry. Do not reuse it for a different port request. See Port numbers in for the complete request and response schemas.

Create port-out requests

Request PACs for one or more assigned numbers:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "assignedNumberSids": [
      "AN12345678901234567890123456789012"
    ],
    "codeType": "PAC"
  }' \
  'https://api.cloudnumbering.com/v1.1/porting/out'

This operation creates real port-out requests. It accepts between 1 and 100 assigned-number SIDs and currently supports PAC only.

As with port-in, HTTP 200 can contain both orders and per-number validation errors. Inspect result.orders and result.errors. The request does not accept an idempotency key, so do not automatically retry an ambiguous port-out response without first checking existing port orders.

See Request PACs for assigned numbers.

Track porting status

Save every port order SID beginning with PO. Retrieve a single order:

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

See Get a port order.

Customer-visible statuses are:

IN_PROGRESS
CODE_READY
CODE_EXPIRED
FAILED
COMPLETED
CANCELLED

For a port-out order, the PAC is returned in code only while the status is CODE_READY. codeExpiresAt reports its expiry when available. CODE_EXPIRED is partly time-derived: a CODE_READY order whose code has passed its expiry reports CODE_EXPIRED, so two polls can return different statuses without anything changing server-side.

If your integration polls, add backoff and stop when the order reaches a terminal status. A 409 means the order exists but is not ready for the requested data; retry it later rather than creating another order.

You can also list orders with GET /v1.1/porting/orders. It supports pagination and filters for port order SID, assigned-number SID, E.164 number, and active orders. See List porting orders.

Operational guidance

ReadMe documents the API contract. Use the help centre for supported porting scenarios, account administration, and operational steps: