Generate OTP Codes

After setting up your WhatsApp channel and templates, you can generate OTP codes to send to users. You can use this endpoint to trigger OTP generation and send it via WhatsApp.

Endpoint and Headers

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

This API key is sensitive and should never be used on the front end or mobile SDK; it should only be implemented on the back end.

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	The channel that you will send the OTP code to.	String	Yes	oneof:whatsapp
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:pt af sq ar az bn bg ca zh_CN zh_HK zh_TW hr cs da nl en en_GB en_US et fil fi fr ka de el gu ha he hi hu id ga it ja kn kk rw_RW ko ky_KG lo lv lt mk ms ml mr nb fa pl pt_BR pt_PT pa ro ru sr sk sl es es_AR es_ES es_MX sw sv ta te th tr uk ur uz vi zu
ttl	Specifies the Time-To-Live (TTL) duration for the OTP code, which is the time window within which the OTP code is valid. It is 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/ Integer	No	The custom code must be a 4–8-digit string or an integer between 1000 and 99999999. Both integer and string custom codes must be at least 4 digits long. If the code is sent as an integer, it must be greater than 1000 and will always be interpreted as a numeric value without leading zeros. If the code is sent as a string and the desired value has fewer than 4 digits, it must be padded with leading zeros to reach 4 characters (e.g., a code of 67 must be sent as 0067).
max-attempts	Sets the maximum number of allowed OTP verification attempts. If the verification fails after reaching this limit, further attempts might be denied.	Integer	No (Default: 3)	min:1 max:10
is-unique	When set to true, ensures that a unique OTP code is generated for this request.	Boolean	No	boolean

Sample Request

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

Below is a sample request to generate and send a WhatsApp verification code with a specified locale and time-to-live (TTL).

Make sure to replace the sample values in the request header(s) and body where required before sending your request.

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

Sample Responses

202 Accepted

This response indicates that your request was successfully completed.

{
  "key": "whatsapp-12345",
  "channel": "whatsapp",
  "date-created": "2023-07-28T14:40:41Z",
  "date-updated": "2023-07-28T14:40:41Z",
  "locale": "en",
  "max-attempts": 3,
  "ttl": 180
}

400 Bad Request

Invalid request payload:

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

Missing required field:

{
  "errors": [
    {
      "message": "this field is required",
      "field": "text"
    }
  ]
}

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 service is subject to a rate limit of 750 requests per second to ensure optimal system performance. If you exceed this limit, you will receive an HTTP 429 Too Many Requests response.

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.