Wait for an SMS

GET

/numbers/sms/wait

const url = 'https://api.clearance.rest/numbers/sms/wait?number=example';
const options = {method: 'GET', headers: {'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=example' \
  --header 'X-API-Key: <X-API-Key>'

Long-poll: returns the newest matching SMS right away when one already arrived after timestamp, otherwise waits until one arrives (at most 5 minutes; X-Service-Timeout in milliseconds lowers the limit). Only messages delivered to your project match. When nothing arrives in time the response is 200 with success: false and error.code: wait_timeout.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

number

required

string

>= 1 characters

Recipient number (E.164); encode + as %2B.

sender

string

Only messages from this sender.

timestamp

number

Only messages received after this time (seconds, milliseconds or microseconds since the epoch).

match_regex

string

Only messages whose body matches.

code_regex

string

Extract a code from the body (the first capture group, otherwise the whole match).

Header Parameters

X-Service-Timeout

integer

>= 1

Maximum time to wait in milliseconds (positive integer). Without it the request waits at most 5 minutes; a larger value is capped at 5 minutes.

Responses

200

Default Response

application/json

Any of:

object
object

object

success

required

boolean

code

required

string | null

from

required

string

required

string

body

required

string

message_id

required

string

received_at

required

UTC timestamp (ISO 8601).

string

Example

{
  "success": true
}

400

Default Response

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable error code (snake_case).

string

Allowed values: validation_error invalid_service_timeout number_required invalid_regex

message

required

Human-readable message.

string

details

Extra context for the error.

object

key

additional properties

Example

{
  "success": false,
  "error": {
    "code": "validation_error"
  }
}

401

Default Response

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable error code (snake_case).

string

Allowed values: missing_api_key invalid_api_key

message

required

Human-readable message.

string

details

Extra context for the error.

object

key

additional properties

Example

{
  "success": false,
  "error": {
    "code": "missing_api_key"
  }
}

403

Default Response

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable error code (snake_case).

string

Allowed values: team_suspended email_not_verified invalid_mcp_token

message

required

Human-readable message.

string

details

Extra context for the error.

object

key

additional properties

Example

{
  "success": false,
  "error": {
    "code": "team_suspended"
  }
}