Quickstart

This page takes you from nothing to a received SMS code. The whole walkthrough costs a few cents.

Create an account.

Sign up in the console with your email address and a password, then open the verification link we email you. An unverified account cannot use API keys or add balance.

Signing up creates your first team (named after you), a project called Default and an API key. Teams own the balance; projects own the API keys, numbers, mailboxes and webhooks. See How it works.
Add balance.

Open Billing and choose Add balance. The minimum is $10 and the checkout opens with $20 selected. Every paid call draws from this balance, in USD. See Billing.
Copy an API key.

Open your project, then API keys. A key starts with cr_live_ and is shown in full only when it is created, so copy it then. Export it so the examples below can use it:
```
export CLEARANCE_REST_API_KEY=cr_live_...
```
Check the key.

GET /account/balance is free and changes nothing.
curl https://api.clearance.rest/account/balance \ -H "X-API-Key: $CLEARANCE_REST_API_KEY"
import { createClient } from '@clearance-rest/sdk'; const client = createClient(); // reads CLEARANCE_REST_API_KEY console.log(await client.account.balance());
use ClearanceRest\Client; $client = new Client(); // reads CLEARANCE_REST_API_KEY print_r($client->account->balance());
The response carries your available balance, the amount held for requests in flight and your project’s spending so far. A wrong or missing key returns 401.

Rent a number and wait for its SMS.

A temporary number lives for about 20 minutes and is meant for a single verification. Look up the price first, rent the number, trigger the SMS in the service you are verifying, then hold a request open until the code arrives.

# Our price for a number that receives Telegram SMS in the UK.
curl -G https://api.clearance.rest/numbers/catalog/prices \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  --data-urlencode "type=temporary" --data-urlencode "country=GB" --data-urlencode "service=tg"

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" }'

# Replace the number with item.phone_number from the rent response.
curl -G https://api.clearance.rest/numbers/sms/wait \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "X-Service-Timeout: 120000" \
  --data-urlencode "number=+447380312345" \
  --data-urlencode "code_regex=\d{4,6}"

const rental = await client.numbers.rent({ type: 'temporary', country: 'GB', service: 'tg' });
console.log(rental.item.phone_number, 'cost', rental.price);

// ... trigger the SMS in the target service, then:
const sms = await client.numbers.waitForSms(
  { number: rental.item.phone_number, codeRegex: '\\d{4,6}' },
  { timeout: 120_000 },
);
console.log(sms.code);

await client.numbers.releaseItem(rental.item.id);

$rental = $client->numbers->rent(type: 'temporary', country: 'GB', service: 'tg');
echo $rental['item']['phone_number'], ' cost ', $rental['price'];

// ... trigger the SMS in the target service, then:
$sms = $client->numbers->waitForSms($rental['item']['phone_number'], codeRegex: '\d{4,6}', timeout: 120_000);
echo $sms['code'];

$client->numbers->releaseItem($rental['item']['id']);

If no SMS arrives, the wait ends with a wait_timeout result and costs nothing. Releasing a temporary number before any SMS arrived refunds the rental. See Temporary numbers.

Authentication and errors
Waiting for results: how long a request stays open and how to bound it
Let an AI agent do this for you: connect the MCP server
Emails and captchas

Quickstart

Next