Waiting for an SMS

GET /numbers/sms/wait keeps the request open until an SMS matching your filters arrives on one of your numbers, then answers with it. It works the same for temporary, monthly and device numbers.

Request

Parameter
number	Required. The recipient number in E.164 format. Encode + as %2B.
sender	Only messages from this sender.
timestamp	Only messages received after this time, in seconds, milliseconds or microseconds since the epoch.
match_regex	Only messages whose body matches.
code_regex	Extracts a code from the body: the first capture group, otherwise the whole match.
X-Service-Timeout	Header. The longest wait in milliseconds; at most 5 minutes. See Waiting for results.

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=+447380312345" \
  --data-urlencode "code_regex=(\d{4,6})"

Node.js

import { WaitTimeoutError } from '@clearance-rest/sdk';

try {
  const sms = await client.numbers.waitForSms(
    { number: '+447380312345', codeRegex: '(\\d{4,6})', timestamp: new Date() },
    { timeout: 120_000 },
  );
  console.log(sms.code, sms.from);
} catch (error) {
  if (!(error instanceof WaitTimeoutError)) throw error;
  // Nothing arrived: ask for another SMS or wait again.
}

PHP

use ClearanceRest\Exceptions\WaitTimeoutException;

try {
    $sms = $client->numbers->waitForSms('+447380312345', codeRegex: '(\d{4,6})', timestamp: new DateTimeImmutable(), timeout: 120_000);
    echo $sms['code'], ' from ', $sms['from'];
} catch (WaitTimeoutException) {
    // Nothing arrived: ask for another SMS or wait again.
}

Response

{
  "success": true,
  "code": "482913",
  "from": "+15559998888",
  "to": "+447380312345",
  "body": "Your code is 482913",
  "message_id": "0190...",
  "received_at": "2026-10-25T10:00:03.120Z"
}

code is null when you sent no code_regex or it matched nothing; read the body yourself in that case.

What matches

• The newest matching message is returned. If one already arrived after timestamp, the request returns at once. Pass timestamp as the moment you triggered the SMS so an older message cannot match.
• Only messages delivered to your project match. Messages sent by us to verify a device number never do.
• Waiting does not cost anything. SMS on monthly and device numbers are charged when they arrive, not when you read them. See Billing.

When nothing arrives

After the wait time the response is 200 with success: false and error.code wait_timeout. The SDKs throw WaitTimeoutError. You can wait again, or for a temporary number request the SMS again.

Other failures: 400 invalid_regex, 400 number_required, 400 validation_error (for example a timestamp that is not a number) and 400 invalid_service_timeout.

Without waiting

To be notified instead of holding a request, subscribe to the opt-in number.sms_received event.