Hero SMS numbers

Hero SMS numbers are temporary. You pick a country and a service, rent a number for about 20 minutes, receive the verification SMS, and release it. They are the cheapest way to get a number for a single sign-up or verification.

Unlike Twilio, you cannot browse individual numbers first. You choose a country and a service, check price and stock, and rent.

1. Find the country and service.

   curl https://api.clearance.rest/numbers/providers/herosms/countries \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY"
   
   curl "https://api.clearance.rest/numbers/providers/herosms/services?country=6" \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY"

   A country’s id (for example 6 for Indonesia) is what the other endpoints take as country. A service’s code (for example tg) is what you pass as service.

2. Check price and stock (optional).

   curl "https://api.clearance.rest/numbers/providers/herosms/prices?country=6&service=tg" \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY"

   { "success": true, "prices": { "country": 6, "service": "tg", "cost": 0.2, "count": 1500, "physicalCount": 40 } }

   cost is indicative, not a guaranteed floor.

3. Rent a number.

   curl

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

   Node.js

   const { number } = await clearanceRest.numbers.rent({ service: 'tg', country: 6 });
   console.log(number.phoneNumber, number.expiresAt);

   PHP

   $number = $client->numbers->rent(service: 'tg', country: 6)['number'];

4. Use the number, then wait for the SMS.

   Enter number.phoneNumber wherever the verification is triggered, then wait for the SMS.

5. Release it.

   curl -X POST https://api.clearance.rest/numbers/release \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
     -H "content-type: application/json" \
     -d '{ "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6" }'

Renting several at once

Send quantity (1 to 20). The response is then always a numbers array with one result per activation. One failing does not stop the others.

{
  "success": true,
  "numbers": [
    { "success": true, "number": { "sid": "c1aaeac1-…", "phoneNumber": "+6281234567890" } },
    { "success": false, "error": "hero-sms NO_NUMBERS" }
  ]
}

Leave max_price out

max_price looks like a simple price cap, but for Hero SMS it also controls access to the marketplace stock. If you omit it, the service starts from the indicative price and retries with a growing ceiling until it finds stock, so you do not have to. Sending max_price disables that and tries exactly once, so send it only if you need a hard budget cap and can accept a NO_NUMBERS failure.

Other optional filters: operator (from GET /providers/herosms/operators) and phone_exception (comma-separated number prefixes to exclude, at most 20).

Lifetime

The rental lasts about 20 minutes (expiresAt on the number). Once it ends, the number becomes EXPIRED for a short moment and then RELEASED, and can no longer receive SMS. SMS it already received stay readable with GET /sms/wait.

Releasing and refunds

POST /numbers/release finishes the activation if an SMS arrived, or cancels it (and refunds you) if none did.

Hero SMS refuses cancellation during roughly the first two minutes after a rental. In that window release returns an error asking you to try again later. If you do nothing, the rental is cancelled and refunded automatically when it expires.

Asking for the SMS again

If the SMS did not arrive, ask Hero SMS to send it again:

curl -X POST https://api.clearance.rest/numbers/providers/herosms/resend \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6" }'

Renting the cheapest option (SDK)

The SDKs can check the price and rent in one call. It fails without renting if nothing is in stock:

const { number } = await clearanceRest.numbers.rentCheapest({ service: 'tg', country: 6 });