Verify OTP

Verifies the code the user entered against the reference_id returned by Send OTP. Up to 5 attempts are allowed per code; after that the code is invalidated and a new one must be sent.

POST/api/v1/otp/verify

X-API-Key

Body parameters

Field	Type	Required	Description
reference_id	string	required	The id returned by `Send OTP`
code	string	required	The code the user received via SMS

Example request

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "482153"
}

Example response

{
  "success": true,
  "data": {
    "valid": true,
    "reason": "ok"
  }
}

A wrong, expired, or exhausted code is not returned as valid: false — it is an error response (see below), so check the HTTP status. A successfully verified code is consumed and cannot be verified again.

Errors

Code	Description
400 VALIDATION_FAILED	Missing `reference_id` or `code`
400 BAD_REQUEST	Malformed JSON
401 UNAUTHORIZED	API key missing or invalid
404 NOT_FOUND	`reference_id` unknown, the code has expired, or it was already verified (codes are one-time)
422 UNPROCESSABLE_ENTITY	Code is wrong, or the maximum of 5 attempts was exceeded (the code is then invalidated) — see `message`
429 RATE_LIMITED	Too many requests — retry after `Retry-After`