Send a one-time passcode (OTP) to a user. Please read API General Reference before reading this document.

Using only the user's phone number as the sole parameter in the default configuration, Unimatrix will seamlessly generate a secure numeric OTP token and automatically dispatch the verification message through the currently active channel.


  • Action: otp.send
  • HTTP Method: POST
  • Content-Type: application/json

Request Parameters

tostringYesUser's phone number for verification code. Using E.164 format.+12068800123
digitsintegerNoNumber of digits for the generated OTP code. Must be between 4-8. Default: 66
intentstringNoUser's intent for requesting the verification code, used to differentiate different authentication scenarios. Maximum 36 characters.login
channelstringNoThe verification messaging channel to use. One of: sms, call, whatsapp or auto. Default: auto (SMS takes priority over other channels)auto
codestringNoA custom code instead of a automatically generated OTP code. Must be a 4-8 digit string.
* Not recommended. Using custom codes may reduce the security of your program.
ttlintegerNoTime-to-live for custom code in seconds. Max: 1800. Default: 300 (5 minutes)300

Request Example

The following example will automatically generate a verification code and send the code to the user's phone number.

curl -X POST '' \
-H 'Content-Type: application/json' \
-d '{
  "to": "+120688001xx"

After completing the OTP sending, use the Verify OTP API to check if the user provided code is correct.

Response Parameters

codestringReturn code0
messagestringReturn messageSuccess

Results data

idstringMessage IDe7f51d2e5550131c3acc7fbc84e9901b
tostringUser's phone number (E.164)+12068800123
isostringCountry code (iso2)US
ccstringCountry code (International call prefix)1
partsintegerNumber of message parts1
pricestringConsumption amount0.008500

Response Examples

Successful response example

Status Code: 200, Response Body:

  "code": "0",
  "message": "Success",
  "data": {
    "id": "e7f51d2e5550131c3acc7fbc84e9901b",
    "to": "+12068800123",
    "iso": "US",
    "cc": "1",
    "parts": 1,
    "price": "0.008500"

Failure response example

Status Code: 400, Response Body:

  "code": "107111",
  "message": "InvalidPhoneNumbers"