Searching Journeys

Searching is a fundamental part of Customer Journey as it allows a user to track their engagement with the contact center. This helps an Agent to better serve the user and allows the contact center to build a good user experience.

A Simple Example

The minimum amount of information required by a user to perform a search is a single identifier, this is the simplest search that can be performed and will search everything in the user's account for a match.

The below is an example of a simple search that can be performed via the Search Journeys API. Journey's that match the email address [email protected] will be returned within the response, which would contain the engagements and identifiers that belong to that user's journey.

{
  "identifiers": {
    "emailAddresses": [
      "[email protected]"
    ]
  }
}

An example of the response can be seen below, note we have omitted some fields for clarity:

{
  "pagination":{
    "pageNumber":1,
    "pageSize":50,
    "total":2
  },
  "engagements":[
    {
      "id":"8e557fd6-580a-43b3-8cf9-db8169f4af5a",
      "status":"COMPLETED",
      "startDate":"2021-04-23T17:45:21.000Z",
      "updateDate":"2021-04-23T17:47:21.000Z",
      "endDate":"2021-04-23T17:50:21.000Z",
      "identifiers":{
        "emailAddresses":[
          "[email protected]"
        ],
        "phoneNumbers":[
          "188-115-7717"
        ]
      }
    },
    {
      "id":"94594028-5559-4efb-8263-9698e3ffe61d",
      "status":"COMPLETED",
      "startDate":"2021-04-26T11:59:21.000Z",
      "updateDate":"2021-04-26T12:07:21.000Z",
      "endDate":"2021-04-26T12:07:21.000Z",
      "identifiers":{
        "phoneNumbers":[
          "188-115-7717"
        ],
        "accountIds":[
          "account-528"
        ]
      }
    },
    {
      "id":"cb7e2e17-53ae-4341-91e6-c5059879cfce",
      "status":"ACTIVE",
      "startDate":"2021-04-30T14:38:45.000Z",
      "identifiers":{
        "accountIds":[
          "account-528"
        ]
      }
    }
  ],
  "identifiers":{
    "phoneNumbers":[
      "188-115-7717"
    ],
    "accountIds":[
      "account-528"
    ]
  }
}

Breaking it down

When performing this search, Customer Journey goes through the following steps:

Lookup the identifier [email protected] and all connected identifiers.

These identifiers form the complete customer identity.

Using the customer identity collect all the connected engagements.
Return a journey including the customer identity and engagements.

The action taken in (1) makes it possible for a user to find enhanced journey information without needing to know the full customer identity.

For example, given the following:

Email address [email protected] is internally connected with phone number "188-115-7717".
- This connection is made on the first engagement.
Phone number "188-115-7717" is internally connected with account ID "account-528".
- This connection is made on the second engagement.

In this case Customer Journey would have the intelligence to retrieve everything in the user's journey connected to all 3 identifiers even though the user of the API is only aware of [email protected]. This greatly improves the user experience by increasing the level of detail returned while searching.

Using a Date-Time Range

In some scenarios a user may only be interested in the parts of a journey that occurred within a specific period of time. For example a user may only be interested in everything that occurred between 2021-04-01 and 2021-04-30, everything after 2021-04-01, or everything before 2021-04-30.

A user can narrow a search down to a specific period of time using ISO 8601 format date-time ranges with the fields startDate & endDate, we have provided examples of each combination. All date-time ranges are inclusive.

Everything within a Date-Time Range

{
  "startDate": "2021-04-01T17:45:21.001Z",
  "endDate": "2021-04-30T17:08:34.653Z",
  "identifiers": {
    "emailAddresses": [
      "[email protected]",
    ]
  }
}

Everything after a Date-Time

{
  "startDate": "2021-04-01T17:45:21.001Z",
  "identifiers": {
    "emailAddresses": [
      "[email protected]",
    ]
  }
}

Everything before a Date-Time

{
  "endDate": "2021-04-30T17:08:34.653Z",
  "identifiers": {
    "emailAddresses": [
      "[email protected]",
    ]
  }
}

Filtering by Conversation

In certain scenarios a user may only want to retrieve the parts of a journey that relate to a particular conversation, where a conversation is a free-form piece of text describing an engagement, e.g. "Car Insurance". Each engagement can have one or more conversations associated with it during its lifecycle in the contact center, so it can be useful to filter parts of a journey by conversation.

Filtering by conversation is performed using the conversation field, which takes a free-form piece of text as part of the search request (this can be combined with a date-time range):

{
  "conversation": "Mortgage Protection",
  "identifiers": {
    "emailAddresses": [
      "[email protected]",
    ]
  }
}

In the example journey below we have 2 engagements and 2 unique conversations:

{
  "engagements": [
    {
      "id": "8e557fd6-580a-43b3-8cf9-db8169f4af5a",
      "status": "COMPLETED",
      "conversations": [
        "Car Insurance"
      ]
    },
    {
      "id": "1a6ed0e2-1670-493f-b097-0ca4406937d4",
      "status": "COMPLETED",
      "conversations": [
        "Car Insurance",
        "Mortgage Protection"
      ]
    }
  ]
}

To retrieve the parts of the journey related to "Mortgage Protection", the second engagement, then the request would be:

{
  "conversation": "Mortgage Protection",
  "identifiers": {
    "emailAddresses": [
      "[email protected]",
    ]
  }
}

To retrieve the parts of the journey related to "Car Insurance", the first & second engagement, then the request would be:

{
  "conversation": "Car Insurance",
  "identifiers": {
    "emailAddresses": [
      "[email protected]",
    ]
  }
}