Wait for an SMS

GET

/sms/wait

const url = 'https://api.clearance.rest/numbers/sms/wait?number=%2B14155550100&sender=%2B15559998888&timestamp=1785107000000&match_regex=Kodunuz&code_regex=%5Cd%7B6%7D';
const options = {
  method: 'GET',
  headers: {'X-Service-Timeout': '45000', 'X-API-Key': '<X-API-Key>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.clearance.rest/numbers/sms/wait?number=%2B14155550100&sender=%2B15559998888&timestamp=1785107000000&match_regex=Kodunuz&code_regex=%5Cd%7B6%7D' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Service-Timeout: 45000'

Holds the request open until an SMS matching your filters arrives for number, then returns it. If a matching SMS already arrived, it returns immediately. When several match, the newest is returned. A wait lasts at most 5 minutes; send X-Service-Timeout to give up sooner.

Only messages for numbers whose status is ACTIVE (and whose SIM is present, for mobile numbers) wake a waiter. Messages for other numbers are stored but do not resolve a wait.

Parameters may also be sent as a JSON request body. Encode a leading + in number and sender as %2B in a query string.

Authorizations

ApiKey

Parameters

Header Parameters

X-Service-Timeout

integer

>= 1

Maximum time to wait, in milliseconds. Must be a positive integer. When the wait exceeds it, the response is HTTP 200 with error: "timeout". It can only lower the service’s own ceiling, never raise it.

Query Parameters

number

required

string

The recipient number to wait on, in E.164 format.

sender

string

Only match SMS from this sender. Any sender when omitted.

timestamp

string

Only consider SMS received after this moment. Accepts seconds, milliseconds, microseconds, or an ISO 8601 date string. Defaults to 0 (everything).

match_regex

string

Filter. Messages whose body does not match are skipped and the wait continues.

code_regex

string

Extraction. Regular expression applied to the body; the result goes into code (the capture group if there is one, otherwise the whole match). code is null when this is omitted.

Responses

200

The SMS, or a timeout (error: "timeout").

application/json

Any of:

object
object

object

success

required

boolean

code

required

Value extracted by code_regex, or null when it was omitted or matched nothing.

string | null

from

required

string

required

string

body

required

string

messageSid

required

string

receivedAt

required

When the SMS was received, in milliseconds since the Unix epoch.

integer

Returned with HTTP 200 when the wait exceeded X-Service-Timeout.

object

success

required

boolean

error

required

string

Allowed value: timeout

Examples

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

{
  "success": false,
  "error": "timeout"
}

400

number is missing, match_regex or code_regex did not compile, timestamp is not a number, or X-Service-Timeout is invalid.

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Examples

{
  "success": false,
  "error": "number zorunludur"
}

{
  "success": false,
  "error": "geçersiz match_regex"
}

{
  "success": false,
  "error": "geçersiz timestamp"
}

401

The X-API-Key header is missing or invalid.

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Example

{
  "success": false,
  "error": "geçersiz API anahtarı"
}

502

The upstream provider call failed (network error, auth error, or the provider’s own error).

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Example

{
  "success": false,
  "error": "invalid json body"
}