Check OTP STatus

Check OTP Status

Retrieve the current status of a previously generated One-Time Password (OTP).

This API returns the current state of an OTP, including its validation status, remaining attempts, and expiry information.

📘
Prerequisite
Generate an OTP using the Generate OTP API and retain the returned otpUuid.

Endpoint

GET /v1/relid-otp/{otpUuid}

Authentication

Include a Bearer token in the request header.

Authorization: Bearer <access_token>

Path Parameters

Parameter	Type	Required	Description
`otpUuid`	string	✅	Unique identifier of the OTP returned by the Generate OTP API.

Example Request

GET /v1/relid-otp/6c677c1e-e78e-4e19-a77c-1ee78efe1998

Success Response

The API always returns HTTP 200 for a valid OTP UUID, regardless of the current OTP status.

Response Fields

Field	Description
`otpUuid`	Unique OTP identifier.
`userId`	User associated with the OTP.
`relidOtpStatus`	Current OTP status.
`attemptsLeft`	Remaining validation attempts.
`createdTs`	OTP creation timestamp (Epoch milliseconds).
`updatedTs`	Last updated timestamp (Epoch milliseconds).
`expiryTs`	OTP expiry timestamp (Epoch milliseconds).

Status: SUCCESS

{
  "otpUuid": "6c677c1e-e78e-4e19-a77c-1ee78efe1998",
  "userId": "u1",
  "relidOtpStatus": "SUCCESS",
  "createdTs": 1739963900556,
  "updatedTs": 1740025184836,
  "expiryTs": 1740050600556
}

Status: FAILED

{
  "otpUuid": "6c677c1e-e78e-4e19-a77c-1ee78efe1998",
  "userId": "u1",
  "relidOtpStatus": "FAILED",
  "attemptsLeft": 8,
  "createdTs": 1739963900556,
  "updatedTs": 1740025184836,
  "expiryTs": 1740050600556
}

Status: EXHAUSTED

{
  "otpUuid": "63f49aa8-5043-4f8d-b49a-a850437f8d75",
  "userId": "nilesh1",
  "relidOtpStatus": "EXHAUSTED",
  "attemptsLeft": 0,
  "createdTs": 1740395104303,
  "updatedTs": 1740395129869,
  "expiryTs": 1740395404303
}

Status: NONE

{
  "otpUuid": "d17f2871-4c0e-4cde-bf28-714c0e7cdec5",
  "relidOtpStatus": "NONE",
  "attemptsLeft": 3,
  "createdTs": 1743085429046,
  "expiryTs": 1743085444046
}

OTP Status Values

Status	Description
`SUCCESS`	OTP has been successfully validated.
`FAILED`	Most recent validation failed, but additional attempts remain.
`EXHAUSTED`	Maximum validation attempts have been reached.
`NONE`	OTP has not yet been validated.

Error Responses

HTTP Status	Description
404	OTP UUID not found.
422	Invalid OTP UUID.

Example - OTP UUID Not Found

{
  "timestamp": "2025-02-20T09:27:25IST",
  "status": 404,
  "error": "Data not present",
  "message": "otpUuid not found",
  "path": "/v1/relid-otp/22b7dcf1-a133-442e-b7dc-f1a133342ef"
}

Example - Invalid OTP UUID

{
  "timestamp": "2025-02-20T10:11:37IST",
  "status": 422,
  "error": "Invalid data",
  "message": "Invalid OTP UUID",
  "path": "/v1/relid-otp/22b7dcf1-a133-442e-b7dc-f1a133342ef"
}

Best Practices

Use this API to monitor OTP lifecycle after generation.
If the status is EXHAUSTED, generate a new OTP.
If the status is SUCCESS, no further validation is required.
Use attemptsLeft to determine whether the user can retry OTP validation.
Treat expiryTs as the authoritative expiry time for the OTP.

Updated 28 days ago

Did this page help you?