GetOTP Documentation

Voice OTP

The Voice OTP allows you to perform OTP via automated phone call.

Request for Voice OTP API

To request for Voice OTP, make a POST request to our OTP endpoint.

https://api.otp.dev/v1/verifications

With the following Basic HTTP verification method:

Description	Required	Data Type	Example
Your API Key	Yes	String	mtbi2w4hlendfpxa1igthcu5p6mzxf7k

Note

Grab your API key from this page

With the following parameters:

Name	Description	Required	Data Type	Example
channel	Channel for delivering OTP	Yes	String	voice
voice_type	Voice type of verification message. 'flash' will result in a dropped call, 'tts' will result in code to speech	Yes	String	flash
phone	The user mobile phone number (with country code)	Yes	String	60123456789
code_length	The length of the code, which falls within the range of 4 to 6 characters. At least one of the following is required: 'code_length' or'code'.	No	Number	4
code	The 'code' field accepts only digits and must be between 4 to 6 characters in length. At least one of the following is required: 'code_length' or'code'.	No	String	1234
ringing_duration	The ringing duration for 'flash' call, must be between 5 to 10 seconds. Default ringing duration is 8 seconds.	No	Number	8
language	Supported languages for 'tts' verification. Default value is 'EN' English.	No	String	EN
payload	Additional info that will be sent back to the client through the Webhook URL.	No	String For JSON object, convert into JSON string.	`{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}`

Note

Notes on the phone parameter:

You must provide a phone number as digits without spaces or special characters, beginning with the country dialing code.

Notes on the language parameter:

With 'tts' voice type, you can specify the language of the verification message. Defaults to 'EN'.

Supported languages are: 'AR', 'ZH', 'EN', 'GB', 'FR', 'DE', 'HI', 'JA', 'RU', 'ES', 'MX', 'BN', 'ID', 'MS', 'FIL', 'TH', 'VI'.

Examples

Below is an example request using cURL:

curl --request POST \
     --url https://api.otp.dev/v1/verifications \
     --header 'X-OTP-Key: {YOUR_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "data": {
        "channel": "voice",
        "voice_type": "flash",
        "phone": "60123456789",
        "code_length": 4,
        "ringing_duration": 10
    }
}
'

The response would be a JSON structure, returned with HTTP 200 Codestatus code:

{
  "account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phone": "60123456789",
  "code": "1234",
  "sender": "1234567890",
  "create_date": "2025-08-18T06:28:58.962Z",
  "expire_date": "2025-08-18T06:28:58.962Z"
}

Response data details:

Name	Description	Data Type	Example
account_id	The unique identifier of the account	String	3fa85f64-5717-4562-b3fc-2c963f66afa6
message_id	The unique identifier of the message	String	3fa85f64-5717-4562-b3fc-2c963f66afa6
phone	Recipient's phone number	String	60123456789
code	Verification code (can be specified or auto-generated, depending on your setup)	String	7890
sender	The phone number the call will originate from	String	1234567890
create_date	Creation date of the verification in UTC, formatted as yyyy-mm-dd hh:mm:ss	String	2025-08-18 00:00:00
expire_date	Expiration date of the verification in UTC, formatted as yyyy-mm-dd hh:mm:ss	String	2025-08-18 02:00:00

If there is an error with the API call, you will receive a JSON response with 400+ status code, error code and message.

{
  "errors": [{
    "timestamp": "2025-08-18 00:00:00",
    "path": "/v1/verifications",
    "method": "POST",
    "status": 401,
    "message": "User Not Authorized",
    "code": "1136"
  }]
}

Please refer to this table for details:

Error Code	Description	HTTP Code
1136	User Not Authorized	401
1523	Invalid recipient number(s)	400
1621	'phone' is missing	400
1623	Invalid code length	400
1629	Provide either 'data.code' or 'data.code_length' but not both	400
1630	When 'data.channel' is voice, 'data.code' must be valid and 4 to 6 characters long	400
1632	'data.code' should be numeric if provided	400
1650	Provided 'data.language' is not supported	400
1700	Provide 'data.voice_type'	400
1701	Invalid voice type. Must be 'flash' or 'tts'	400
1702	Invalid ringing duration	400
1705	Invalid payload	400