GetOTP Logo

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. Take note that our OTP endpoint ends with a trailing slash: 

https://otp.dev/api/verify/

With the following Basic HTTP verification method:

Description Required Data Type Example
Your API Key Yes String mtbi2w4hlendfpxa1igthcu5p6mzxf7k

Note

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://otp.dev/api/verify/ \
     --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 Code status 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": "/api/verify/",
    "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