Verify API: Generate OTP Codes

The Verify API enables you to generate, send, and verify OTP codes for the SMS channel. You can utilize this API to generate OTP codes as defined in the payloads. Integrating it into your own websites or apps, you can trigger it on login pages, payment pages, and more.

After you create your channel for your brand and update the templates, you need to perform the generate action for your OTP.

Endpoint and Headers

POST https://verify.useinsider.com/v1/generate

This API key is sensitive and should only be implemented on the backend. Using it on the frontend or mobile SDK may pose security risks.

Visit our Postman collection to test this request.

Headers

Header	Sample Value	Description
X-INS-AUTH-KEY	1a2b3c4d5e6f	This key is required to authorize your request. Refer to API Authentication Tokens to generate your token.
Content-Type	application/json	This header specifies the media type of the resource.

Body Parameters

Parameter	Description	Data Type	Required	Rules
channel	Channel that you will send the OTP code.	String	Yes	oneof:sms
to	Specifies the destination phone number in E.164 format to which the OTP code will be sent.	String	Yes	e164
locale	Determines the language/locale in which the OTP code message will be sent.	String	No (Default: en)	oneof:de en es fr it ja nl pt ru tr
ttl	Specifies the Time-To-Live (TTL) duration for the OTP code, i.e., the time window within which the OTP code is valid. Measured in seconds.	Integer	No (Default: 180)	min:60 max:600
code-length	Specifies the length of the OTP code to be generated. The code length must be between 4 and 8 digits.	Integer	No (Default: 4)	min:4 max:8
custom-code	If provided, allows you to specify a custom OTP code instead of generating one.	String	No	min:1000 max:99999999
max-attempts	Sets the maximum number of allowed OTP verification attempts. Further attempts might be denied if the verification fails after reaching this limit.	Integer	No (Default: 3)	min:1 max:10

Sample Request

Every request made to the request endpoint requires a request body formatted in JSON and containing your parameters.

Before sending your request, make sure to replace the sample values in the request header(s) and body where required.

Below is a sample request to generate and send a verification code via SMS.

curl --location 'https://verify.useinsider.com/v1/generate' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: 1a2b3c4d5e6f \
--data '{
    "channel": "sms",
    "to": "+905XXXXXXXXX"
}'

Sample Responses

202 Accepted

This response indicates that your request was successfully completed.

{
    "channel": "sms",
    "dateCreated": "2023-07-28T14:40:41Z",
    "dateUpdated": "2023-07-28T14:40:41Z",
    "locale": "en",
    "maxAttempts": 3,
    "ttl": 180
}

400 Bad Request

{
    "errors": [
        {
            "message": "invalid request payload"
        }
    ]
}

400 Bad Request

{
    "errors": [
        {
            "message": "channel information must be a valid phone number for sms",
            "field": "to"
        }
    ]
}

A valid phone number needs to be in the E164 format.

401 Unauthorized

{
    "errors": [
        {
            "message": "unauthorized"
        }
    ]
}

429 Too Many Requests

{
    "errors": [
        {
            "message": "rate limit exceeded"
        }
    ]
}

500 Internal Server Error

{
    "errors": [
        {
            "message": "server error"
        }
    ]
}

Limitations

All functions must be executed with a simple HTTPS POST request.
The API Key should be provided as the authorization key in the request header. If the key is incorrect, the operation will not be executed, and an authorization error will be returned in the response.
The rate limit is 250 requests per minute.

The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team — we can adjust it to fit your needs.