Skip to content
clearance.rest

Temporary numbers

A temporary number is rented for a single verification and lasts about 20 minutes. It is the cheapest way to receive one SMS code, and a rental that gets no SMS is refunded.

Rent one

Section titled “Rent one”

Choose a country and the service you will verify against, such as tg for Telegram. Look up codes with GET /numbers/catalog/services, and the price with GET /numbers/catalog/prices.

curl -X POST https://api.clearance.rest/numbers/rent \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "type": "temporary", "country": "GB", "service": "tg", "max_price": 0.5 }'

operator narrows the rental to one operator from GET /numbers/catalog/operators. Without it, any operator may serve the number.

The response holds the item (see the overview), the price you were charged and your remaining balance.

Price and cap

Section titled “Price and cap”

The catalog price is the price of a rental that finds stock at the first attempt. A listed price does not always mean stock is available. If there is none at that price the rental steps up through a few higher prices until it reaches your cap.

max_price Cap Held from your balance
Given max_price Up to max_price
Omitted About twice the catalog price Up to that cap
  • If max_price is below the catalog price, nothing is held and the request fails with 409 max_price_too_low; error.details.price is the catalog price.
  • You are charged only the price that was reached. The rest of the hold returns to your balance.
  • Passing the catalog price as max_price means you never pay more than listed. If there is no stock at that price the request fails with 409 no_numbers_available; raise max_price to try higher prices.
  • If the balance, or a spend limit, cannot cover the cap, the request fails with 402.

Receive the SMS

Section titled “Receive the SMS”

Trigger the SMS in the target service, then wait for it:

const sms = await client.numbers.waitForSms({ number: item.phone_number, codeRegex: '(\\d{4,6})' }, { timeout: 120_000 });

If the service did not send anything, ask for another SMS with POST /numbers/items/{id}/resend. It is free.

Release and refunds

Section titled “Release and refunds”

When you are done, call POST /numbers/items/{id}/release.

  • No SMS arrived: the rental is cancelled and you are refunded. The response has refunded: true.
  • An SMS arrived: the number is completed and the rental stays charged.
  • A cancellation can be refused when the number was only just rented. The request then fails with 409 release_too_early and error.details.retry_after_seconds says how long to wait.
  • Releasing a number that is no longer active answers 409 number_not_active.

You do not have to release. A number that reaches its expiry is closed for you: its status becomes RELEASED with released_reason: "expired", and if it never received an SMS you are refunded automatically.

Events

Section titled “Events”

A temporary number emits number.rented, number.status_changed (for example when it expires) and number.metadata_updated. number.sms_received is opt-in. See Webhooks.