Check OTP Status

Check OTP Status Using Contact Details

Retrieve the current status of an OTP generated using the Generate OTP Using Contact Details API.

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

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

Endpoint

GET /v1/otp-using-contact-details/{otpUuid}

Authentication

Authorization: Bearer <access_token>

Path Parameters

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

Example Request

GET /v1/otp-using-contact-details/6c677c1e-e78e-4e19-a77c-1ee78efe1998

Success Response

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

Response Fields

Field	Description
`otpUuid`	Unique OTP identifier.
`otpStatus`	Current status of the OTP.
`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",
  "otpStatus": "SUCCESS",
  "createdTs": 1739963900556,
  "updatedTs": 1740025184836,
  "expiryTs": 1740050600556
}

Status: FAILED

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

Status: EXHAUSTED

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

Status: NONE

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

OTP Status Values

Status	Description
`SUCCESS`	OTP has been successfully validated.
`FAILED`	The last validation attempt failed, but retry attempts remain.
`EXHAUSTED`	The maximum number of validation attempts has been reached.
`NONE`	The 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/otp-using-contact-details/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/otp-using-contact-details/22b7dcf1-a133-442e-b7dc-f1a133342ef"
}

Best Practices

Use this API to monitor the lifecycle of an OTP generated using contact details.
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 validation.
Use expiryTs to determine when the OTP expires.

Related APIs

Generate OTP Using Contact Details
Validate OTP Using Contact Details

Updated 28 days ago

Did this page help you?