Invoke Orchestration API
×
Invoke Orchestration API

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. 

POST

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. 

Http Code

Error Code

Description

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

 

Update nOTP Verification Status

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. 

PUT

https://exoverify.exotel.com/v3/accounts/<account_sid>/flashcalls/<verification_id>

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. 

Http Code

Error Code

Description

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

 

Orchestration WebHook Hits:

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.