The journeys API Can be used to programmatically trigger journey flows and subflows individually or in bulk.

Prerequisites

To call the journeys API, first obtain your organization's OrgId and Access Token, as described in the API Authentication documentation.

You'll also need to have created and published a journey that you would like to trigger.

Trigger Journey Flow

API documentation for the trigger journey flow endpoint can be found at Trigger a journey flow or subflow.

Request

The call is a POST to https://medchatapp.com/chatbotapi/external/orgs/{orgId}/journeys/{chatBotId}/instances/bulk, where {orgId} is your organization's ID and {chatBotId} is the ID assigned to the Journey that you'd like to trigger, which can be obtained from the last part of the URL when viewing your saved Journey in Automation Studio.

The JSON request body contains a couple of top-level properties and a list of instances to trigger:

{
  "flowId": null,               // null if triggering a main flow
  "timeZone": "America/Chicago" // IANA timezone to indicate the timezone that any datetime parameters are represented as
  "instances":
  [
    {
      "parameters" : 
      {
        "patientId": "100000",
        "patientName": "John Smith",
        "appointmentId": "40-XYZ-11123",
        "appointmentDateTime": "2023-12-01 08:00:00"      
      }
    },
    {
      "parameters": 
      {
        "patientId": "100001",
        "patientName": "Jane Green",
        "appointmentId": "92-XBX-11934",
        "appointmentDateTime": "2023-12-01 08:30:00"      
      }
    }
    ...
  ]
}

• flowId- Should be null when triggering a main flow. Provide the subflow ID when triggering a journey subflow.
• timeZone - The TZ identifier of the IANA timezone that any provided datetimes are represented in. If all provided datetimes are in UTC, specify "UTC". Required if there are any datetime parameters on the journey.
• instances - An array of instances that should be triggered, each with its unique set of parameters.
  • parameters- A dictionary of strings representing the parameter values for the instance to be used when triggering the journey flow. There should be one key/value pair for each attribute configured as a parameter on the journey.

📘

Triggering journey subflows

The same endpoint for triggering a journey main flow for new instances is used to trigger a journey subflow on existing instances. The only difference is the subflow ID must be provided as flowId in the request when triggering a subflow.

Existing instances will be identified using the "Instance identifier" parameter(s) in the instances array.

Response

Expect a 204 - No Content response on a successful call.

If there is a problem with the request, the API will return a 400 - Bad Request with an array of error messages.