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. |
