Send One Time Password

The Send One Time Password (OTP) API is used send a numeric 4-8 (defaults to 6) digit one time password to a contact's mobile phone via SMS or email inbox.

A OTP is valid for 15 minutes after being generated.

Send to mobile or email

Either a mobile number or email address parameter must be provided.

If both an email address and a mobile number are provider, the OTP will be sent to the mobile number. If only an email address is provided, the OTP will be sent to to the user's email inbox.

Behavior when recipient does not exist

When the API is called a contact is created if one does not exist. If the contact does exist, but the contact's status is deleted the OTP will fail.

The return value includes the contact's unique DailyStory ID. This DailyStory ID is used to validate the OTP received.

Important

The dsid of the contact is required to validate the one time password using the validation API.

Resend cooldown and lockout

To prevent abuse, a cooldown period (default 30 seconds) must elapse before another OTP can be sent to the same mobile number. Use the cooldown_seconds parameter to override this value (between 10 and 600 seconds). The successful response includes the active cooldown_seconds value so the caller knows how long to wait.

If a contact exceeds the maximum number of failed verification attempts, the API returns HTTP 429 with locked: true and a lockout_seconds value indicating how long until the contact may request a new OTP.

Query Parameters
mobilestring
A valid mobile number in e.164 format. For example, a U.S. number would be +15551234567. Either mobile or email is required.
emailstring
A valid email address. Either mobile or email is required.
minutes_validnumber
Optionally provide a value between 3 and 20 to override the default number of minutes the OTP is valid for. Defaults to 15.
otp_sizenumber
Optionally provide a value between 4 and 8 to set the length of the generated OTP. Defaults to 6.
cooldown_secondsnumber
Optionally provide a value between 10 and 600 (10 minutes) to override the minimum number of seconds that must elapse before another OTP can be sent to the same mobile number. Defaults to 30.
HTTP Response Examples
200Success
{ "Status": true, "Message": "", "Response": { "dsid": "6bbc6d5b933b4dd38ffce5b2dc30a35f", "cooldown_seconds": 30 } }
400Bad Request
{ "Status": false, "Message": "A valid email or mobile number is required", "Response": {} }
429Locked Out
{ "Status": false, "Message": "The maximum number of unsuccessful OTP attempts was exceeded. OTP requests are temporarily locked.", "Response": { "locked": true, "lockout_seconds": 7200 } }
HTTP Response Parameters
Response.dsidstring
The unique id of the contact that the one time password was generated for. Required to validate the OTP.
Response.cooldown_secondsnumber
The cooldown period in seconds before another OTP can be requested for this contact.
Response.lockedboolean
Returned with HTTP 429. Indicates the contact is temporarily locked out from requesting new OTPs after exceeding the maximum number of failed verification attempts.
Response.lockout_secondsnumber
Returned with HTTP 429. The remaining lockout duration in seconds before the contact may request a new OTP.