Numbers

Rent phone numbers for your workspace: caller IDs for your tests, destinations a system under test can call, and the numbers survey tests answer on.

7 endpoints

Renting a number

Search for a number, buy it, then follow its order until it is live. A new UK number takes about a day to activate while the carrier checks the regulatory paperwork, which TotalPath files for you. A number has a monthly charge and a one-off setup fee, so buying is not safe to retry: a repeated request buys a second number. Free plans cannot rent numbers. Only UK (GB) numbers are sold today.

List numbers

GET/numbers

The phone numbers this workspace rents, newest first, with `allowance`: how many it may hold. An empty list is the state every workspace starts in, not an error. A number that is ordered but not usable yet is listed with `state: ordering` and a `requirementsStatus`; a UK number takes about a day to activate. Released numbers drop off the list. `allowance` is absent if it could not be read. Needs the `numbers:read` scope.

Request

bash

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/numbers

Response

json

{
  "allowance": {
    "used": 2,
    "max": 5,
    "remaining": 3,
    "unlimited": false,
    "source": "tier",
    "tier": "team",
    "includedInDeal": false
  },
  "numbers": [
    {
      "numberId": "3045775838822799120",
      "orderId": "b3c8e1f2-5d4a-4b6c-9e7f-1a2b3c4d5e6f",
      "e164": "+447457416512",
      "countryIso2": "GB",
      "phoneNumberType": "mobile",
      "capabilities": [
        "voice",
        "local_calling",
        "fax",
        "sms"
      ],
      "type": "survey",
      "uses": [
        "survey"
      ],
      "isDefault": false,
      "state": "ordering",
      "monthlyRateUsd": 4,
      "createdAt": "2026-11-12T09: 00: 00Z",
      "requirementsStatus": "requirement-info-under-review"
    },
    {
      "numberId": "3045775838822794747",
      "orderId": "97a7d59a-1889-4391-bb3b-3d44fd7e3b26",
      "e164": "+447457416494",
      "countryIso2": "GB",
      "phoneNumberType": "mobile",
      "capabilities": [
        "voice",
        "local_calling",
        "fax",
        "sms"
      ],
      "type": "survey",
      "uses": [
        "survey"
      ],
      "isDefault": false,
      "state": "live",
      "monthlyRateUsd": 4,
      "acquiredAt": "2026-11-03T09: 12: 00Z",
      "createdAt": "2026-11-02T08: 40: 00Z"
    }
  ]
}

Search available numbers

GET/numbers/available

Numbers that could be bought now, with what you would pay. The search is filtered to what `numberType` needs: a `survey` number must carry SMS, which in the UK means a mobile. Leave out `phoneNumberType` to search every type that can do the job, cheapest first (in the UK a voice-only `national` or `local` number costs half a `mobile`). Numbers TotalPath already holds are listed first with `fromPool: true`: no setup fee, and they work immediately. `immediateActivation` is false for every new UK mobile so far; expect about a day. An empty list means nothing matches. Only `GB` is sold today.

Query Parameters

Name	Type	Required	Description
country	string	required	ISO 3166-1 alpha-2 country code, e.g. GB
numberType	string	optional	What the number is for: outbound, inbound, callback or survey. Default survey
phoneNumberType	string	optional	Search one type only, e.g. mobile or national
limit	number	optional	Results to return, 1-50. Default 10

Request

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.nopaque.co.uk/numbers/available?country=GB&numberType=survey&limit=5"

Response

json

{
  "country": "GB",
  "phoneNumberType": "mobile",
  "phoneNumberTypes": [
    "mobile"
  ],
  "numberType": "survey",
  "numbers": [
    {
      "e164": "+447457416494",
      "fromPool": false,
      "phoneNumberType": "mobile",
      "capabilities": [
        "voice",
        "local_calling",
        "fax",
        "sms"
      ],
      "monthlyRateUsd": 4,
      "upfrontRateUsd": 4,
      "selfServe": true,
      "currency": "USD",
      "immediateActivation": false
    }
  ]
}

Get a country's number requirements

GET/numbers/requirements

The regulatory items a country asks for before it activates a number, with the carrier's own guidance kept as written. This is information, not a form: every item is `satisfiedBy: nopaque`, because we file all of it on your behalf and you supply nothing. It explains why a number takes about a day to activate, and it is what an order's progress is counted against. An unsupported country or type is a 400 naming what is sold.

Query Parameters

Name	Type	Required	Description
country	string	required	ISO 3166-1 alpha-2 country code, e.g. GB. Case-insensitive
phoneNumberType	string	optional	e.g. mobile. Defaults to the country's only type when it sells exactly one

Request

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.nopaque.co.uk/numbers/requirements?country=GB&phoneNumberType=mobile"

Response

json

{
  "country": "GB",
  "phoneNumberType": "mobile",
  "requirements": [
    {
      "id": "req_proof_of_address",
      "name": "Proof of Address (National), Recent Utility Bill or Invoice",
      "fieldType": "document",
      "description": "A utility bill or invoice dated within the last three months showing the registered address.",
      "satisfiedBy": "nopaque"
    }
  ]
}

Buy a number

POST/numbers/orders

Order one number for this workspace. This spends money: the number has a monthly charge, plus a one-off setup fee billed once it is live, not when it is ordered (`upfrontChargedUsd` in a 202 is that fee, still to come). Retrying is not safe - a repeat request buys a second number and a second charge. The number is re-checked with the carrier first, so the price and capabilities used are the carrier's current ones. If TotalPath already holds a suitable number it is assigned instead: it works immediately and the answer is 201 with `fromPool: true` and no setup fee. Otherwise the answer is 202: the number is listed straight away with `state: ordering`, and Get a number order reports what it is waiting on (about a day in the UK). The regulatory paperwork is ours; nothing is asked of you. 402 `number_limit_reached` when the workspace may not hold another number (Free plans cannot rent numbers). 409 when the order was refused before anything was spent; the `error` says why. On a 500 or 502 contact support rather than retrying. Needs the `numbers:write` scope.

Body Parameters

Name	Type	Required	Description
e164	string	required	The number to buy, exactly as Search available numbers returned it
numberType	string	required	What it is for: outbound, inbound, callback or survey. A survey number must carry SMS
country	string	required	ISO 3166-1 alpha-2. Only GB is sold today
phoneNumberType	string	optional	national, local or mobile. Defaults to the cheapest type that can do the job

Request

bash

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"e164":"+447457416512","numberType":"survey","country":"GB"}' \
  https://api.nopaque.co.uk/numbers/orders

Response

json

{
  "number": {
    "numberId": "3045775838822799120",
    "orderId": "b3c8e1f2-5d4a-4b6c-9e7f-1a2b3c4d5e6f",
    "e164": "+447457416512",
    "countryIso2": "GB",
    "phoneNumberType": "mobile",
    "capabilities": [
      "voice",
      "local_calling",
      "fax",
      "sms"
    ],
    "type": "survey",
    "uses": [
      "survey"
    ],
    "isDefault": false,
    "state": "ordering",
    "monthlyRateUsd": 4,
    "createdAt": "2026-11-12T09: 00: 00Z",
    "requirementsStatus": "requirement-info-under-review"
  },
  "orderId": "b3c8e1f2-5d4a-4b6c-9e7f-1a2b3c4d5e6f",
  "activation": {
    "immediate": false,
    "message": "UK numbers are checked by the carrier before they work. This normally takes about a day."
  },
  "requirementsSubmitted": true,
  "upfrontChargedUsd": 4,
  "monthlyRateUsd": 4
}

Get a number order

GET/numbers/orders/{orderId}

What an order is still waiting on, counted per regulatory requirement. Read this rather than the number's state, which stays `ordering` for the whole wait. `waitingOn` is `telnyx` (the carrier is reviewing; nothing to do but wait), `nopaque` (the next step is ours) or `nobody` (the requirements are met). `customerMustAct` is always false. An order from another workspace is a 404. Needs the `numbers:read` scope.

Path Parameters

Name	Type	Required	Description
orderId	string	required	The `orderId` from Buy a number or List numbers

Request

bash

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/numbers/orders/b3c8e1f2-5d4a-4b6c-9e7f-1a2b3c4d5e6f

Response

json

{
  "orderId": "b3c8e1f2-5d4a-4b6c-9e7f-1a2b3c4d5e6f",
  "number": {
    "numberId": "3045775838822799120",
    "orderId": "b3c8e1f2-5d4a-4b6c-9e7f-1a2b3c4d5e6f",
    "e164": "+447457416512",
    "countryIso2": "GB",
    "phoneNumberType": "mobile",
    "capabilities": [
      "voice",
      "local_calling",
      "fax",
      "sms"
    ],
    "type": "survey",
    "uses": [
      "survey"
    ],
    "isDefault": false,
    "state": "ordering",
    "monthlyRateUsd": 4,
    "createdAt": "2026-11-12T09: 00: 00Z",
    "requirementsStatus": "requirement-info-under-review"
  },
  "progress": {
    "complete": false,
    "requirementsStatus": "requirement-info-under-review",
    "total": 6,
    "approved": 5,
    "awaitingOn": 1,
    "outstanding": [
      {
        "requirementId": "req_company_registration",
        "name": "Local Government-Issued ID/Passport Copy or Local Company Registration Certificate",
        "fieldType": "document",
        "status": "pending-approval"
      }
    ],
    "waitingOn": "telnyx",
    "customerMustAct": false
  }
}

Update a number

PATCH/numbers/{numberId}

Change what a number is used for, make it the workspace's default caller ID, or both. A number has one use: `outbound` (caller ID for standard tests), `load` (caller ID for load-test calls), or `callback`, `survey` or `inbound` (destinations). The use needs the matching capability (`survey` needs SMS). `isDefault: true` clears the flag from any other number; the default must have the `outbound` or `load` use. Only a `live` number can be changed. Needs the `numbers:write` scope.

Path Parameters

Name	Type	Required	Description
numberId	string	required	Number ID (`numberId`), from List numbers

Body Parameters

Name	Type	Required	Description
uses	string[]	optional	Exactly one of outbound, load, callback, survey or inbound
isDefault	boolean	optional	true makes this the workspace's fallback caller ID

Request

bash

curl -X PATCH -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uses":["load"],"isDefault":true}' \
  https://api.nopaque.co.uk/numbers/3045775838822794747

Response

json

{
  "number": {
    "numberId": "3045775838822794747",
    "orderId": "97a7d59a-1889-4391-bb3b-3d44fd7e3b26",
    "e164": "+447457416494",
    "countryIso2": "GB",
    "phoneNumberType": "mobile",
    "capabilities": [
      "voice",
      "local_calling",
      "fax",
      "sms"
    ],
    "type": "survey",
    "uses": [
      "load"
    ],
    "isDefault": true,
    "state": "live",
    "monthlyRateUsd": 4,
    "acquiredAt": "2026-11-03T09: 12: 00Z",
    "createdAt": "2026-11-02T08: 40: 00Z"
  }
}

Release a number

POST/numbers/{numberId}/release

Give a number back. Billing for it stops and it leaves List numbers. It returns to TotalPath's pool rather than the open market, so it is not reserved for you if you want it back later. Only a `live` number can be released; one still activating is a 409 `number_not_releasable`. A 202 means the carrier has not confirmed yet; it finishes on its own and the number may stay listed for a few minutes. Needs the `numbers:write` scope.

Path Parameters

Name	Type	Required	Description
numberId	string	required	Number ID (`numberId`), from List numbers

Request

bash

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/numbers/3045775838822794747/release

Response

json

{
  "released": true,
  "message": "Number released."
}