The Validate One Time Password (OTP) API is used to verify a 4–6 digit numeric one-time password that was sent to a contact through the Send One-Time Password API.
An OTP remains valid for 15 minutes after it is generated.
Retry attempts and lockout
By default, an incorrect OTP immediately invalidates the cached code and the contact must request a new OTP. Set allow_retry=true to permit multiple incorrect attempts before the OTP is invalidated. When retry is enabled, the response includes remaining_attempts so the caller can show the user how many attempts they have left.
If the contact exceeds the maximum number of failed attempts (default 5, configurable via retry_attempts), the API returns HTTP 429 with locked: true and a lockout_seconds value indicating how long until the contact may request or validate a new OTP.
The unique DailyStory ID (dsid) for the contact whose OTP is being validated. The dsid is returned when the Send One Time Password API is used.
The One Time Password (OTP) sent to the contact's mobile phone or email address.
Optionally provide a value between 3 and 20 to override the default validity window in minutes. Must match the value used when the OTP was sent. Defaults to 15.
When true, an incorrect OTP does not immediately invalidate the cached code; the caller may retry until retry_attempts is exhausted. Defaults to false.
The number of incorrect attempts allowed before the OTP is invalidated and the contact is locked out. Must be between 1 and 10. Only applies when allow_retry=true. Defaults to 5.
{
"Status": true,
"Message": "The OTP is valid.",
"Response": {}
}
{
"Status": false,
"Message": "The OTP is invalid.",
"Response": {
"remaining_attempts": 3
}
}
{
"Status": false,
"Message": "The maximum number of unsuccessful OTP attempts was exceeded. OTP requests are temporarily locked.",
"Response": {
"locked": true,
"remaining_attempts": 0,
"lockout_seconds": 7200
}
}
Returned on a failed validation when allow_retry=true. The number of incorrect attempts remaining before the OTP is invalidated.
Returned with HTTP 429. Indicates the contact has exceeded the maximum number of failed verification attempts and is temporarily locked out.
Returned with HTTP 429. The remaining lockout duration in seconds before the contact may request or validate a new OTP.
The API will respond with an HTTP 200 code to indicate the OTP is valid. If the OTP is invalid, the API will respond with an HTTP 400.