Waiting for an SMS

GET /numbers/sms/wait works the same for every kind of number (Hero SMS, Twilio or mobile). It returns the SMS that matches your filters, waiting for it if it has not arrived yet.

curl

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=+14155550100" \
  --data-urlencode "sender=+15559998888" \
  --data-urlencode "match_regex=Kodunuz" \
  --data-urlencode "code_regex=\d{6}"

Node.js

const sms = await clearanceRest.numbers.wait({
  number: '+14155550100',
  sender: '+15559998888',
  matchRegex: 'Kodunuz',
  codeRegex: '\\d{6}',
  timeout: 120000,
});
console.log(sms.code, sms.body);

PHP

$sms = $client->numbers->wait(
    number: '+14155550100',
    sender: '+15559998888',
    matchRegex: 'Kodunuz',
    codeRegex: '\d{6}',
    timeout: 120_000,
);
echo $sms['code'];

{
  "success": true,
  "code": "123456",
  "from": "+15559998888",
  "to": "+14155550100",
  "body": "Kodunuz 123456",
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "receivedAt": 1785107161430
}

Filters

Parameter	Effect
number (required)	The recipient number, in E.164 format.
sender	Only SMS from this sender. Any sender when omitted.
timestamp	Only SMS received after this moment. Seconds, milliseconds, microseconds or an ISO 8601 string.
match_regex	Filter. Messages whose body does not match are skipped and the wait continues.
code_regex	Extraction. Applied to the chosen message; the result goes into code.

match_regex selects which SMS qualifies and code_regex pulls a value out of it; they are independent. If code_regex has a capture group, the group is returned, otherwise the whole match. When you omit code_regex, code is null. An invalid regex returns 400.

In a query string, encode a leading + as %2B. A raw + is turned into a space. curl --data-urlencode and the SDKs do this for you.

Set timestamp before you trigger the SMS

If several SMS match, the newest is returned, and an SMS that arrived before your request counts. If you reuse a number, an old code can match a new wait. Capture the time before you trigger the SMS and pass it as timestamp:

const startedAt = Date.now();
await triggerVerificationSms(number);          // your side of the flow
const sms = await clearanceRest.numbers.wait({ number, timestamp: startedAt, codeRegex: '\\d{6}' });

Which numbers receive

Only numbers whose status is ACTIVE wake a waiter. An SMS for a number in any other state is stored but does not resolve a wait. Mobile numbers also need their SIM to be present. See Managing numbers.

Timeout

The wait lasts at most 5 minutes; lower it with X-Service-Timeout. When it runs out the response is HTTP 200 with { "success": false, "error": "timeout" }. See Timeouts.