Waiting for results

Three calls keep the request open until their result exists:

Request	Waits for
`GET /numbers/sms/wait`	An SMS on one of your numbers
`GET /emails/wait`	An email to one of your mailboxes
`POST /captchas/resolve`	A solved captcha

GET /numbers/sms/wait

number=+14155550100

code_regex=\d{6}

X-Service-Timeout: 120000

200 OK

The request is open. Nothing to return yet.

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

There is no polling loop and no webhook to host. Send the request, then read the response when it comes back.

What is already there counts

If a matching SMS or email arrived before you asked, the request returns immediately with the newest match. Use timestamp to ignore anything older than a moment you choose, for example the moment you triggered the message. It accepts seconds, milliseconds or microseconds since the Unix epoch.

Bounding the wait

Send X-Service-Timeout with the longest time you will wait, in milliseconds.

GET /numbers/sms/wait?number=%2B14155550100 HTTP/1.1
X-API-Key: cr_live_...
X-Service-Timeout: 60000

SMS and email waits last at most 5 minutes, whatever you send. Without the header they wait 5 minutes.
A captcha request lasts at most 10 minutes. Without the header it waits up to that.
A value that is not a positive integer returns 400 invalid_service_timeout.
If your client disconnects, we stop waiting for you. A wait that delivers nothing costs nothing.

Set your own HTTP client’s timeout a little above X-Service-Timeout, or intermediate proxies may cut the connection first. The SDKs do this for you: they send the header and give up 15 seconds after the server would.

When nothing arrives

The SMS and email waits end with HTTP 200 and a failure envelope:

{ "success": false, "error": { "code": "wait_timeout", "message": "..." } }

This is not an error in the usual sense: it costs nothing and you can wait again. The SDKs raise it as WaitTimeoutError. A captcha request instead returns a status of timeout; see Solving captchas.

Filtering with regular expressions

The SMS and email waits take two regular expressions, compiled with JavaScript semantics:

match_regex keeps only messages that match. An SMS is tested on its body; for an email a match in the text, the HTML or the subject counts.
code_regex extracts a value into code. The first capture group is used when the expression has one, otherwise the whole match. If it matches nothing, or you send no code_regex, code is null.

An expression that does not compile returns 400 invalid_regex.

Agents

An MCP client cannot hold a request open for minutes, so the MCP tools return status: "pending" when the time is up and the agent simply calls them again. See Waiting and limits.