You can test these APIs on postman! Click here.
This ExoVerify API is used to start an SMS OTP verification. Please ensure the following pre-requisites are taken care of before using this API
Please refer to following Sequence Diagram to understand the API hits flow:
The following data points are required to start using this API:
Please use the following Headers in the API Request:
1. Authorization: Basic <credentials>
<credentials> is a Base64 encoded value of “Application_ID:Application_Secret” (ignore quotes).
2. Content-Type: application/json
https://exoverify.exotel.com/v2/accounts/{account_sid}/verifications/sms
Replace {account_sid} with your Account SID (Find it on the top left side of this page)
The following are the Body Parameters of the API Request
| Parameter Name | Mandatory/Optional | Value / Description |
| application_id | Mandatory | Indicates the Exoverify SMS App to be used for the verification request. |
| phone_number | Mandatory | Indicates the phone number that needs to be verified. It must be in the E164 format. |
| replace_vars | Optional | A list of variables that are to be used for replacing {#var#} placeholders in a DLT approved SMS Template that has variables apart from the OTP itself. For instance, if you have two occurrences of {#var#} in your template, and specify a list of two strings for the “replace_vars“ array parameter - the replacement of each {#var#} will be done with each item in the list using the order of the items in the list, from left to right. |
{
"application_id": "f5b1c365648e6f50fd1b29634a5e166e",
"phone_number": "+916666666666"
}
{
"application_id": "f5b1c365648e6f50fd1b29634a5e166e",
"phone_number": "+916666666666",
"replace_vars": ["John", "Doe"]
}
{
"request_id":"881cf11407d54595a6902267d05eff4a",
"method":"POST",
"http_code":200,
"response":{
"code":200,
"error_data":null,
"status":"success",
"data":{
"verification_id":"463fac2fa3ece58c6551e296c1b9167c",
"phone_number":"+918637XX2391",
"application_id":"f5b1c365648e6f50fd1b29633a5e166e",
"account_sid":"google",
"max_attempts":10,
"expiration_in_seconds":60,
"url":"/v2/accounts/google/sms/verifications/463fac2fa3ece58c6551e296c1b9167c",
"created_at":"2022-07-12T12:13:16Z",
"updated_at":"2022-07-12T12:13:16Z"
}
}
}
{
"request_id":"6d9de1b5576b446692ffd9d1c1620c8e",
"method":"POST",
"http_code":400,
"response":{
"code":400,
"error_data":{
"code":1002,
"description":"ApplicationId in Body and Authorization Header should be same",
"message":"Invalid parameter"
},
"status":"failure",
"data":null
}
}
The following are a sample list of the HTTP codes and corresponding error codes that can encountered in the event of a failure.
|
400 |
1001 |
Mandatory Parameter missing |
|
400 |
1002 |
Invalid parameter |
|
400 |
1005 |
Mandatory Body Parameters missing |
|
401 |
1010 |
Authentication failed |
|
403 |
1012 |
Forbidden Operation |
|
403 |
1015 |
Verification has been denied |
|
404 |
1000 |
Not Found |
|
429 |
1030 |
Throttle limit Breached for Sending Sms |
|
500 |
1110 |
Internal Server Error |
|
500 |
1123 |
Internal Server Error |
|
500 |
1120 |
Internal Server Error |
This ExoVerify API is used to verify if the OTP entered by the user is correct or not
Note: Please ensure you use this API only after successfully creating an SMS OTP app on ExoVerify. The following data points are a pre-requisite to using this API:
This API can be used only after the Start Verification API has been hit successfully.
Please use the following Headers in the API Request:
1. Authorization: Basic <credentials>
<credentials> is a Base64 encoded value of “Application_ID:Application_Secret” (ignore quotes).
2. Content-Type: application/json
https://exoverify.exotel.com/v2/accounts/{account_sid}/verifications/sms/{verification_id}
Replace {account_sid} with your Account SID (Find it on the top left side of this page)
Replace {verification_id} with the Verification ID as received in the response of the Start Verification API request
The following are the Body Parameters of the API Request
| Parameter Name | Mandatory/Optional | Value / Description |
| OTP | Mandatory | The user entered OTP that is to be verified |
{
"OTP": "576389"
}
{
"request_id":"48f97c0f1cca46b09fb0e4255ef8a4eb",
"method":"POST",
"http_code":200,
"response":{
"code":200,
"error_data":null,
"status":"success",
"data":{
"verification_id":"12c705bc55de82cc96f9d543cf77167c",
"application_id":"f5b1c365648e6f50fd1b29633a5e166e",
"account_sid":"Zomato5",
"status":"success",
"created_at":"2022-07-12T12:15:55+05:30",
"updated_at":"2022-07-12T12:15:55+05:30"
}
}
}
{
"request_id":"34f1bed8b4f246049e894d44d588d911",
"method":"POST",
"http_code":403,
"response":{
"code":403,
"error_data":{
"code":1003,
"description":"VerificationId already verified.",
"message":"Authentication failed"
},
"status":"failure",
"data":null
}
}
The following are a sample list of the HTTP codes and corresponding error codes that can encountered in the event of a failure.
|
400 |
1210 |
OTP has expired |
|
400 |
1211 |
Invalid OTP Entered |
|
400 |
1210 |
Mandatory Body Parameters missing |
|
401 |
1010 |
Authentication failed |
|
403 |
1017 |
VerificationId already verified |
|
403 |
1012 |
Forbidden Operation |
|
403 |
1016 |
Maximum allowed verification attempts has been made |
|
404 |
1000 |
Not Found |
|
500 |
1110 |
Internal Server Error |
|
500 |
1120 |
Internal server error |
nOTP is a No-OTP verification mechanism under ExoVerify from Exotel that helps secure your business by verifying customer identity based upon their mobile number.
Available as an SDK for Android phones only, nOTP allows users to verify with absolutely no actions from their end. All they have to do is enter their phone number, and click on the ‘verify’ button. Everything else happens automatically, and the number gets securely verified. nOTP works without an SMS. It is simple and makes number authentication foolproof by ensuring that the mobile number and the user's device are tightly coupled at the time of verification.
nOTP works with the SDK automatically intercepts a phone call triggered by Exotel to the mobile number seeking verification, allowing you to verify your users seamlessly with zero user interaction.
Using the SDK, you can have nOTP verification into your existing android apps with just a few lines of code.
Please visit the GitHub link to access all the technical details on how to integrate your Android app with nOTP and visit ExoVerify to start verifying in no time!
Please refer to this Sequence Diagram to understand the back-end magic of nOTP
Support article on nOTP: https://support.exotel.com/support/solutions/articles/3000109094-what-is-notp-and-how-it-works-
Support article on ExoVerify: https://support.exotel.com/support/solutions/articles/3000113627-exoverify-help-document
Please note that Orchestration as a feature is available via the ExoVerify SDK as well. This API is to be used only if a client has a specific requirement to use Orchestration without the SDK. However it is highly recommended to use the SDK approach.
This ExoVerify API is used to trigger a particular verification Journey. Based on the flow created in the journey, this API will start the verification process of a number with Mechanism 1 (For eg: nOTP) and if it fails for misc reasons, Mechanism 2 (For eg: SMS OTP) will automatically get triggered. Please note that an existing nOTP app and SMS OTP app should be present to create a Journey and consequently to use this API.
Note: Please ensure that a Journey has been created on the ExoVerify portal before using this API. The Master Key and Master Token available on the Orchestration page will be used to authenticate all the Orchestration API Requests. Please ensure that these credentials are safely stored and accessible ONLY to the relevant people in your organisation.
Please use the following Headers in the API Request:
1. Authorization: Basic <credentials>
<credentials> is a Base64 encoded value of “Master_Key:Master_Token” (ignore quotes).
2. Content-Type: application/json
https://exoverify.exotel.com/v2/accounts/<account_sid>/orchestration
Replace <account_sid> with your Account SID (Find it on the top left side of this page)
The following are the Body Parameters of the API Request
| Parameter Name | Mandatory/Optional | Value / Description |
| journey_app_id | Mandatory | The ID of the Journey created on ExoVerify |
| phone_number | Mandatory | The number of the end user that needs to be verified. Please ensure the number is sent as string in E164 format |
| replace_vars | Optional* | A list of variables that are to be used for replacing {#var#} placeholders in a DLT SMS Template that has variables apart from the OTP itself. For instance, if you have two occurrences of {#var#} in your template, and specify a list of two strings for the “replace_vars“ array parameter - the replacement of each {#var#} will be done with each item in the list using the order of the items in the list, from left to right. |
{
"journey_app_id": "0de44779fd9f9a4371f33b4fd44416c1",
"phone_number": "+916666666666",
"replace_vars": [
"John",
"Doe"
]
}
{
"request_id": "080de4b2141f4a04a638abbb325a2976",
"method": "POST",
"http_code": 200,
"response": {
"status": "in-progress",
"orchestration_id": "3674a784e6f8626109c94dd6373616c4",
"journey_app_id": "0de44779fd9f9a4371f33b4fd44416c1",
"message": "Verification mechanism [1] of type notp trigerred",
"verification_mechanism_details": [
{
"sequence": 1,
"type": "notp",
"is_triggered": true,
"data": {
"verification_id": "352dc8c46d8a982d520381c770ea16c4",
"physical_numbers": [
"dc8c6d422c1e6a8b305856439f26dd9c344cc62732079de60ed79858f00f004d"
],
"phone_number": "+916666666666",
"timeout_seconds": 30,
"created_at": "2022-12-04T21:33:00Z"
}
},
{
"sequence": 2,
"type": "smsotp",
"is_triggered": false,
"data": {
"verification_id": "e803a4d54c4d739a8f66623923ac16c4",
"phone_number": "+916666666666",
"timeout_seconds": 60,
"replace_vars": [
"John",
"Doe"
],
"created_at": "2022-12-04T21:33:00Z"
}
}
]
}
}
The following are a sample list of the HTTP codes and corresponding error codes that can encountered in the event of a failure.
|
400 |
1001 |
Mandatory Parameter missing |
|
400 |
1002 |
Invalid parameter |
|
400 |
1005 |
Mandatory Body Parameters missing |
|
400 |
1007 |
Invalid request body,failed parsing |
|
401 |
1010 |
Authentication failed |
|
403 |
1012 |
Forbidden |
|
404 |
1000 |
Not Found |
|
415 |
1011 |
Unsupported content type |
|
500 |
1110 |
Internal Server Error |
|
500 |
208 |
Internal Server Error |
|
500 |
209 |
Internal Server Error |
When Orchestration is used via APIs, the outgoing call from Exotel (for nOTP) is to be intercepted and rejected by the client’s app. And, for the Orchestration to progress in the journey, the client has to update Exotel servers with the status of the verification by hitting the PUT API as detailed below. This ensure that the verification journey continues while also ensuring that the stats and reports as seen on ExoVerify reflect the accurate status of every nOTP request.
https://exoverify.exotel.com/v3/accounts/<account_sid>/flashcalls/<verification_id>
Please note that the <verification_id> is obtained from the Response of the Invoke API in the nested “data” JSON where verification “type” is nOTP.
Replace <account_sid> with your Account SID (Find it on the top left side of this page)
Please use the following Headers in the API Request:
1. Authorization: Basic <credentials>
<credentials> is a Base64 encoded value of “Master_Key:Master_Token” (ignore quotes).
2. Content-Type: application/json
The following are the Body Parameters of the API Request:
| Parameter Name | Mandatory/Optional | Description |
| status | Mandatory | This is status of the nOTP verification. It can only be “success” or “fail” |
| caller_id | Optional* | This is the phone number of the nOTP that was rejected by the client app. This should be passed in the E164 format. |
* The caller_id parameter is mandatory when the nOTP verification was a success.
{
"status": "success",
"caller_id": "+6531588492"
}
{
"status": "fail"
}
{
"request_id": "a1ca6e5778ac4bf982ef53a015e819dd",
"method": "PUT",
"http_code": 200,
"response": {
"code": 200,
"error_data": null,
"status": "success",
"data": {
"id": "5ab74d86d5a5d8a5674582bs8472171n",
"application_id": "869378073a1f405a92fb759d037086f4",
"account_sid": "exotel39us3",
"status": "success",
"number": "+919999999999",
"verification_attempts": 1,
"verification_tat": 10.96,
"created_at": "2023-01-23T17:31:24Z",
"updated_at": "2023-01-23T17:31:34Z"
}
}
}
The following are a sample list of the HTTP codes and corresponding error codes that can encountered in the event of a failure.
|
400 |
1001 |
Mandatory Parameter missing |
|
400 |
1002 |
Invalid parameter |
|
400 |
1005 |
Mandatory Body Parameters missing |
|
400 |
1007 |
Invalid request body,failed parsing |
|
400 |
207 |
Could not find the CallerId |
|
401 |
1010 |
Authentication failed |
|
403 |
1012 |
Forbidden |
|
404 |
1000 |
Not Found |
|
409 |
127 |
The verification is already in terminal state. The status cannot be changed. |
|
409 |
125 |
Wrong caller id for flashcall status update |
|
429 |
126 |
Exceeded flashcall update limit |
|
500 |
1110 |
Internal Server Error |
In the Mandatory field where the client has configured the an endpoint for WebHook hits, Exotel will hit this endpoint with the status of the mechanisms in the Journeys. Please find below Sample Payloads of the same.
{
"mechanism_type": "smsotp",
"verification_id": "ec5d31df6d3ff7176f0873ddf97e16c4",
"app_mechanism_id": "2f21b17965a2e9fd088941bc4351168c",
"phone": "+916666666666",
"status": "success",
"webhook_timestamp": "2022-12-04T22:21:16Z"
}
The following are the Parameters in this WebHook hit:
| Parameter Name | Description |
| verification_id | A unique request id for the Orchestration call. |
| app_mechanism_id | ID of the SMS OTP/nOTP application chosen for the verification process. |
| mechanism_type | nOTP/SMS OTP. |
| phone | Phone number which is being verified. |
| status | Status of the verification. |
| webhook_timestamp | The timestamp at which this webhook was created and sent to the configured endpoint. |
{
"mechanism_type": "smsotp",
"verification_id": "04ca66bf0f14042680d4c6f5a990171c",
"app_mechanism_id": "501b48d0bc2239b17d20104a2f36167r",
"phone": "+916666666666",
"status": "fail",
"reason": "Timeout",
"next_mechanism": {
"mechanism_type": "notp",
"app_mechanism_id": "6791cd7e71c747a7a29db94ec7854995",
"verification_id": "4a044b0e1c6ea581fd9a6437e768171c",
"timeout_in_second": 20
},
"webhook_timestamp": "2023-01-12T05:16:09Z"
}
{
"mechanism_type": "notp",
"verification_id": "04ca66bf0f14042680d4c6f5a990171c",
"app_mechanism_id": "6791cd7e71c747a7a29db94ec7854995",
"phone": "+916666666666",
"status": "fail",
"reason": "Timeout",
"next_mechanism": null,
"webhook_timestamp": "2023-01-12T05:16:31Z"
}
The following are the Parameters in this WebHook hit:
| Parameter Name | Description |
| verification_id | A unique request id for the Orchestration call. |
| app_mechanism_id | ID of the SMS OTP/nOTP application chosen for the verification process. |
| mechanism_type | nOTP/SMS OTP. |
| phone | Phone number which is being verified. |
| status | Status of the verification. |
| reason | Stating the reason in case of failure. |
| next_mechanism | If there is next verification mechanism it will have its details or else this will be set to null. |
| webhook_timestamp | The timestamp at which this webhook was created and sent to the configured endpoint. |