FRENES
Log inRequest a quote
Request a quote

Number management

A number goes through a cycle: search, reservation, order, activation, assignment, cancellation. At each step a condition can block it. This page describes them.

Updated on

When is a number available?

A number is available when four conditions are met at the same time.

  • The country and the capability are approved (voice, SMS, or both).
  • Stock is present with the provider.
  • Your account is authorized to order this type of number.
  • The country’s obligations are met, in particular supporting documents.
If one is missing, the number is not offered or the order stays pending validation.

Number types

The available types depend on the country and the provider. The most common are below.

TypeTypical use
LocalGeographic presence, a site’s reception.
NationalA single number for a country.
MobileSMS or calls to mobiles, depending on the country.
Special-rate numberService numbers, depending on country and provider.

Supporting documents

Some countries ask for proof of identity, proof of a local address or a description of use. Requirements are shown before you order, alongside number search. An order with incomplete documents stays pending validation.

Reservation, expiry and stock conflicts

  1. You search, then reserve a number. The reservation is temporary.
  2. If you do not confirm in time, the reservation expires and the number returns to stock.
  3. If another customer gets the number before you, the order fails with a stock conflict. Run a new search.
  4. A confirmed order goes to pending validation, then the number is activated and the number.activated event is sent.
Fictional example of ordering a number. It is a simulation as long as no provider is configured.
curl -X POST https://api.example.test/v1/number-orders \
  -H "Authorization: Bearer tq_test_EXEMPLE" \
  -H "Idempotency-Key: 5b0e6f0e-2f55-4c1e-9a43-0d6a2f1c7a10" \
  -H "Content-Type: application/json" \
  -d '{"e164":"+33199001234","project_id":"prj_A"}'

Assignment to a project

A number belongs to a project. Its calls, messages and usage are attached to that project. Moving a number to another project is an operation recorded in the audit log.

Cancellation

Cancelling a number requires a confirmation that names the exact target. Depending on the country, a cancelled number may not be recoverable afterwards. If you want to keep it elsewhere, look at porting instead.

Manage numbers step by stepVirtual numbers