Manage your numbers: search, order, list

Before you start

A fictional test key: tq_test_EXEMPLE.
A project to attach the number to. Here: prj_EXEMPLE_A.
The country and the type of number you are looking for (for example a local number in France).

Demo version. Design may change. No production API is open and no real number is ordered.

Search for a number

GET /numbers/search takes at least country and type. Each result lists its capabilities (voice, SMS) and the documents_required field: the documents to provide before activation. Read it before ordering.

Fictional example: a search in a demo stock. The numbers belong to a fictional range.

curl "https://api.example.test/v1/numbers/search?country=FR&type=local" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Example search response

Fictional example response. The documents_required value is illustrative.

{
  "data": [
    {
      "e164": "+33199001234",
      "country": "FR",
      "type": "local",
      "capabilities": ["voice", "sms"],
      "documents_required": ["proof_of_address"]
    }
  ]
}

Order the number

Pick a result from the search and note its e164 value.
Send POST /number-orders with e164 and project_id, along with an Idempotency-Key.
Read the status in the response: pending_validation means the order is waiting for the documents and conditions to be validated. The number cannot be used yet.
Wait for the number.activated event (webhook) or read your list of numbers again.

Fictional example: the order is a simulation until a provider is configured. No real number is reserved.

curl -X POST https://api.example.test/v1/number-orders \
  -H "Authorization: Bearer tq_test_EXEMPLE" \
  -H "Idempotency-Key: c2a97e51-6f08-4b3d-8e14-9d5a0b7c3f28" \
  -H "Content-Type: application/json" \
  -d '{"e164":"+33199001234","project_id":"prj_EXEMPLE_A"}'

List your numbers

GET /numbers returns your numbers with their project and status. Pagination is cursor-based: pass limit, then pass the next_cursor you received as the cursor parameter to get the next page. When next_cursor is null, you have read everything.

Fictional example: reading the demo inventory.

curl "https://api.example.test/v1/numbers?limit=20" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Common errors

Symptom	Likely cause	What to do
No results	No stock for that country or type, or capability not validated for that country.	Try another type, or request a quote for your country.
404 not_found	Project or number does not exist, or is outside your scope.	Check the identifier.
409 idempotency_conflict	Same key, different body.	Use a new key for a new order.
Order stuck in pending_validation	Documents missing or under review.	Provide the documents listed in documents_required.

What this guide does not do

It orders no real number and guarantees neither stock nor lead time: lead times are confirmed with the chosen provider.
It does not cover releasing a number or porting an existing one. For the latter, see “Prepare a number port”.
An available number requires an approved country and capability, stock, an authorized account and satisfied obligations. If any of the four is missing, the order does not go through.

Place a first call with one of your numbers Virtual numbers

Manage your numbers with the API