Send OTP API

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.

Definitions

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

Request Parameters

Name	Type	Required	Description	Example
to	string	Yes	User's phone number for verification code. Using E.164 format.	+12068800123
digits	integer	No	Number of digits for the generated OTP code. Must be between 4-8. Default: `6`	6
intent	string	No	User's intent for requesting the verification code, used to differentiate different authentication scenarios. Maximum 36 characters.	login
channel	string	No	The verification messaging channel to use. One of: `sms`, `call`, `whatsapp` or `auto`. Default: `auto` (SMS takes priority over other channels)	auto
code	string	No	A 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.	123456
ttl	integer	No	Time-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 'https://api.unimtx.com/?action=otp.send&accessKeyId=YOUR_ACCESS_KEY_ID' \
-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

Name	Type	Description	Example
code	string	Return code	0
message	string	Return message	Success
data	JSON	Results

Results `data`

Name	Type	Description	Example
id	string	Message ID	e7f51d2e5550131c3acc7fbc84e9901b
to	string	User's phone number (E.164)	+12068800123
iso	string	Country code (iso2)	US
cc	string	Country code (International call prefix)	1
parts	integer	Number of message parts	1
price	string	Consumption amount	0.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"
}