API docs

Check a verification

Submit the code the user entered. A correct code approves the verification; a wrong one leaves it pending until it's approved, expires, or hits the attempt limit.

POST/v1/verifications/check

Identify the verification by the same to number, or by its verification_id. OTPRelay tracks attempts and expiry for you - you just send the code and read verified.

Request body

codestringrequired: The one-time passcode the user entered.
tostringoptional: The phone number the code was sent to, in E.164 format. Required unless you pass verification_id.
verification_idstringoptional: The verification's id (ver_…), as an alternative to to.

Request

bash

curl https://api.otprelay.io/v1/verifications/check \  -H "Authorization: Bearer sk_live_••••" \  -H "Content-Type: application/json" \  -d '{    "to": "+966512345678",    "code": "418207"  }'

Approved response

A correct code returns 200 OK with status: "approved" and verified: true. Treat status as the source of truth.

200 OK - approved

{  "id": "ver_01HZX9Q2K3M7B8N4P5R6S7T8U9",  "object": "verification",  "status": "approved",  "verified": true,  "to": "+966512345678",  "checked_at": "2026-06-16T10:01:12Z"}

Incorrect code

A wrong code also returns 200 OK, but the verification stays pending with verified: false. Let the user try again until the verification is approved or reaches its attempt limit.

200 OK - still pending

{  "id": "ver_01HZX9Q2K3M7B8N4P5R6S7T8U9",  "object": "verification",  "status": "pending",  "verified": false,  "to": "+966512345678",  "checked_at": "2026-06-16T10:01:30Z"}

Check limits

A verification allows up to 5 checks. After that it's closed with max_attempts_reached, and further checks return 404. The same happens once a verification is approved or expired - start a new verification to retry.

See the full set of states on The verification object, and error bodies on Errors.