[PILOT] End-to-End Journey API

Introduction

The CIDP Journey API provides a consolidated view of customer interactions belonging to the same journey. These interactions may happen on one or multiple 8x8 platforms, including Contact Center (CC), Unified Communications (UC), and Engage. Using the API users can retrieve journey data and detailed transition information, enabling end-to-end tracking of customer journeys regardless of transfers between systems or agents.

This API is particularly valuable for organizations with complex flows that span multiple systems, where customers may be transferred between formal contact center agents and back-office operations.

Business Value

The CIDP Journey API solves critical business challenges:

• Unified Customer Journey Tracking: Track complete customer journeys across CC, UC, and Engage in a single view
• Transfer Pattern Analysis: Understand how calls are transferred between systems and agents
• Comprehensive Metrics: Access consolidated metrics like handling time, queue wait time, and outcomes across all platforms
• Detailed Transition History: Examine every state a customer interaction passed through

Instead of working with disconnected reporting systems, organizations can now build comprehensive reports and dashboards in third-party BI tools with a complete view of all customer interactions.

Authentication

All API requests require an x-api-key header for authentication. Obtain your x-api-key from the Admin Console application.

Required Request Header:

x-api-key: your-api-key-value

Base URLs

Region	Base URL
United States	https://api.8x8.com/cidp/journey/api
Europe	https://api-eu.8x8.com/cidp/journey/api

API Endpoints Overview

The API provides two main synchronous endpoints:

1. Journeys (/v1/journeys/search): Provides aggregated journey data across all platforms, including comprehensive metrics like handling time, queue wait time, and outcomes.

2. Transitions (/v1/transitions/search): Provides detailed information about each state transition within a journey, allowing you to track the exact journey path.

ℹ️ Synchronous API

The CIDP Journey API operates synchronously. Simply send your request and receive the data immediately in the response.

API Endpoints

Journeys Endpoint

POST /v1/journeys/search

Retrieves journey data based on the specified criteria.

Request Headers

Name	Required	Description	Example
Content-Type	✓	Set to application/json	application/json
x-api-key	✓	API key from Admin Console application	your-api-key-value

Request Body

Name	Required	Description	Example
dateRange.start	✓	Start datetime in ISO 8601 format with timezone designator	2025-03-01T00:00:00Z
dateRange.end	✓	End datetime in ISO 8601 format with timezone designator	2025-03-10T00:00:00Z
filters	☐	Set of filter objects with name and values	See filters section
displayTimezone	✓	IANA timezone display name - the desired display timezone value for the time fields	Europe/Bucharest
limit	☐	Maximum number of records to return (default: 100)	50
nextPageCursor	☐	Cursor for pagination from previous response	encoded-cursor-value
sortField	☐	Field to sort by (default: TIME)	TIME
sortDirection	☐	Sort direction, either ASC or DESC (default: ASC)	DESC

⚠️ Important: Date Range Filtering Behavior

The dateRange filter works as follows:

• For Journeys: The API returns all journeys that have a time within the specified date range (between start and end)
• For Transitions: The API returns ALL transitions belonging to journeys that started within the date range

This means:

• A journey is included if it started within the date range
• All transitions for included journeys are returned, even if some transitions occurred after the end date
• The start and end parameters define the search interval, NOT the duration of individual journeys or transitions

Example: If you search for journeys between 9:00 AM and 10:00 AM, you'll get all journeys that started in that hour, along with ALL their transitions - even if some transitions happened at 11:00 AM or later.

⚠️ Timerange Limit

Note: The maximum allowed timerange for any data retrieval request is 60 days.

For optimal performance consider using a timerange of 1 day or less. If you need to analyze data over a longer period, break your requests into multiple segments, each covering no more than 7 days.

Example Request

{
  "dateRange": {
    "start": "2025-05-19T08:00:00+03:00",
    "end": "2025-05-19T16:00:00+03:00"
  },
  "filters": [
    {
      "name": "pbxNames",
      "values": [
        "yourPbxName"
      ]
    },
    {
      "name": "tenantIds",
      "values": [
        "yourTenantId"
      ]
    }
  ],
  "displayTimezone": "Europe/Bucharest",
  "limit": 50,
  "sortDirection": "DESC"
}

Example Response

{
  "data": [
    {
      "time": "2025-03-10T13:33:42+02:00",
      "journeyId": "7b2429440d15183af1044dd47f1d447d",
      "interactions": [
        {
          "id": "int-196e53e066e-QNePASHISrp0D65MVgaNJYS13-phone-01-emeriaeurope01",
          "direction": "Inbound",
          "type": null
        }
      ],
      "agents": [
        {
          "id": "ag-123",
          "subscriptionId": "sub-456",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "loginId": "jdoe",
          "department": "Customer Support",
          "group": {
            "id": "101",
            "name": "ungroup"
          }
        }
      ],
      "contact": {
        "name": "+443335565567",
        "phoneNumber": "+449988776655",
        "email": "john.doe@8x8.com"
      },
      "entryPoint": {
        "type": "user",
        "id": "user-789",
        "name": "Jane Smith",
        "phoneNumber": "+1234567890",
        "extension": "1001",
        "email": "jane.smith@example.com",
        "loginId": "jsmith",
        "department": "Sales",
        "pbx": "mainPbx",
        "tenantId": "8x8"
      },
      "direction": "Outbound",
      "transfersCompleted": 0,
      "forwardedToQueue": 0,
      "forwardedToRingGroup": 0,
      "forwardedToScript": 2,
      "holdDuration": 0,
      "mediaTypes": [
        "Phone"
      ],
      "outcome": "EndedInScript",
      "origin": {
        "type": "user",
        "id": "user-789",
        "name": "Jane Smith",
        "phoneNumber": null,
        "extension": "1036",
        "email": "jane.smith@example.com",
        "loginId": "jsmith",
        "department": "Sales",
        "pbx": "mainPbx"
      },
      "pbxNames": [],
      "queues": [],
      "ringGroups": [],
      "scheduleHours": ["Open", "Closed"],
      "tenantIds": [
        "8x8"
      ],
      "wrapUpCodes": [],
      "outboundPhoneCodes": []
    }
  ],
  "nextPageCursor": "ZW5jbLW5leHQtRlZC1jdXJzb3ItZm9ycGFnZQ==",
  "totalElements": 150
}

Transitions Endpoint

POST /v1/transitions/search

Retrieves transition data based on the specified criteria.

Request Headers

Name	Required	Description	Example
Content-Type	✓	Set to application/json	application/json
x-api-key	✓	API key from Admin Console application	your-api-key-value

Request Body

Same structure as Journeys endpoint, but with transition-specific filters.

Example Request

{
  "dateRange": {
    "start": "2025-05-21T00:00:00+03:00",
    "end": "2025-05-21T23:59:59+03:00"
  },
  "filters": [
    {
      "name": "transitions.name",
      "values": [
        "TRANSFER"
      ]
    }
  ],
  "displayTimezone": "Europe/Bucharest",
  "limit": 100
}

Example Response

{
  "data": [
    {
      "journeyId": "3015ccfd5ebf8b2dcde38045ed30bc7",
      "transitions": [
        {
          "time": "2025-05-21T12:09:23.312+03:00",
          "name":"STARTED",
          "interactionId": "int-196f21ac6ef-d5eed30bc738045-phone-02-8x8",
          "agents": [],
          "previousAgents": [],
          "previousQueue": null,
          "previousRingGroup": null,
          "queue": null,
          "ringGroup": null,
          "duration": 0,
          "externalNumber": null,
          "mediaType": "Phone"
        },
        {
          "time": "2025-05-21T12:09:23.312+03:00",
          "name":"IN_SCRIPT",
          "interactionId": "int-196f21ac6ef-d5eed30bc738045-phone-02-8x8",
          "agents": [],
          "previousAgents": [],
          "previousQueue": null,
          "previousRingGroup": null,
          "queue": null,
          "ringGroup": null,
          "duration": 9206,
          "externalNumber": null,
          "mediaType": "Phone"
        },
        {
          "time": "2025-05-21T12:10:12.143+03:00",
          "name":"TRANSFER",
          "interactionId": "int-196f21ac6ef-d5eed30bc738045-phone-02-8x8",
          "agents": [
            {
              "id": "ag-456",
              "subscriptionId": "sub-789",
              "name": "Jack Pott",
              "email": "jack.pott@example.com",
              "loginId": "jpott",
              "department": "Technical Support",
              "group": null
            }
          ],
          "previousAgents": [
            {
              "id": "ag-123",
              "subscriptionId": "sub-456",
              "name": "Marsha Mellow",
              "email": "marsha.mellow@example.com",
              "loginId": "mmellow",
              "department": "Customer Support",
              "group": null
            }
          ],
          "previousQueue": {
            "id": "queue-101",
            "name": "Service Client",
            "extension": "2001"
          },
          "previousRingGroup": null,
          "queue": null,
          "ringGroup": null,
          "duration": 0,
          "externalNumber": "+441138413014",
          "mediaType": "Phone"
        }
      ]
    }
  ],
  "nextPageCursor": null,
  "totalElements": 1
}

Filters

Filters allow you to narrow down the data returned by the API based on specific criteria. Different filter types are available for journeys and Transitions endpoints.

By default, the API returns all journeys/transitions belonging to your customer account across all PBXes and tenants. To return only journeys for a specific PBX, add a pbxNames filter. To return only journeys for a specific tenant, add a tenantIds filter. All filters use AND logic — when multiple filters are provided, only results matching all of them are returned.

Journey Filters

Filter Name	Description	Example Values
agents.group.id	Filter by agent group IDs	["group1", "group2"]
agents.group.name	Filter by agent group names	["Team A", "Team B"]
agents.name	Filter by agent names	["John Doe", "Jane Smith"]
entryPoint.extension	Filter by entry point extension	["1001"]
entryPoint.id	Filter by entry point ID	["ep-789"]
entryPoint.name	Filter by entry point name	["Main Support Line"]
entryPoint.phoneNumber	Filter by entry point phone number	["053244122"]
entryPoint.type	Filter by entry point type	["cc-channel", "ring-group", "call-queue", "auto-attendant", "user"]
interactions.id	Filter by interaction ID	["interaction-123"]
journeyId	Filter by journey ID	["journey-123"]
mediaTypes	Filter by media types	["phone", "chat", "email"]
origin.extension	Filter by origin extension	["1001"]
origin.id	Filter by origin ID	["user-789"]
origin.name	Filter by origin name	["Jane Smith"]
origin.phoneNumber	Filter by origin phone number	["+1234567890"]
origin.type	Filter by origin type	["user"]
outboundPhoneCodes.listName	Filter by outbound phone code list name	["JohnDoeInbound"]
outboundPhoneCodes.name	Filter by outbound phone code name	["No queue"]
outboundPhoneCodes.shortCode	Filter by outbound phone code short code	["Unt1"]
pbxNames	Filter by PBX names	["pbx1", "pbx2"]
queues.extension	Filter by queue extension	["2001"]
queues.id	Filter by queue ID	["queue-123"]
queues.name	Filter by queue names	["Customer Support Queue"]
ringGroups.extension	Filter by ring group extension	["3001"]
ringGroups.id	Filter by ring group ID	["rg-456"]
ringGroups.name	Filter by ring group names	["Sales Ring Group"]
tenantIds	Filter by tenant IDs	["tenant1", "tenant2"]
wrapUpCodes	Filter by wrap-up codes	["Service Call", "Support Call"]

Transition Filters

Filter Name	Description	Example Values
journeyId	Filter by journey ID	["journey-123"]
pbxNames	Filter by PBX names	["pbx1"]
tenantIds	Filter by tenant IDs	["tenant1"]
transitions.agents.name	Filter by agent names	["John Doe"]
transitions.interactionId	Filter by interaction ID	["interaction-123"]
transitions.name	Filter by transition name	["TALKING", "TRANSFER"]
transitions.previousAgents.name	Filter by previous agents	["Marsha Mellow"]
transitions.previousQueue.extension	Filter by previous queue extension	["2001"]
transitions.previousQueue.id	Filter by previous queue ID	["queue-123"]
transitions.previousQueue.name	Filter by previous queue name	["Support S2"]
transitions.previousRingGroup.extension	Filter by previous ring group extension	["3001"]
transitions.previousRingGroup.id	Filter by previous ring group ID	["rg-456"]
transitions.previousRingGroup.name	Filter by previous ring group name	["Sales Ring Group"]
transitions.queue.extension	Filter by queue extension	["2001"]
transitions.queue.id	Filter by queue ID	["queue-123"]
transitions.queue.name	Filter by queue name	["Support S1"]
transitions.ringGroup.extension	Filter by ring group extension	["3001"]
transitions.ringGroup.id	Filter by ring group ID	["rg-456"]
transitions.ringGroup.name	Filter by ring group name	["Sales Ring Group"]

Filter Format

Filters are provided as an array of objects in the request body:

{
  "filters": [
    {
      "name": "agents.name",
      "values": [
        "John Doe",
        "Marsha Mellow"
      ]
    },
    {
      "name": "mediaTypes",
      "values": [
        "phone"
      ]
    }
  ]
}

Pagination

The API uses cursor-based pagination to efficiently navigate through large result sets. Here's how it works:

1. Make an initial request with a desired limit value in the request body (default is 100)
2. The response includes a nextPageCursor if there are more records available
3. To retrieve the next page, include the nextPageCursor in your next request body
4. Continue this process until nextPageCursor is null, indicating no more pages

Pagination Example

Initial request:

{
  "dateRange": {
    "start": "2025-05-19T00:00:00Z",
    "end": "2025-05-19T23:59:59Z"
  },
  "displayTimezone": "UTC",
  "limit": 100
}

Response with next page cursor:

{
  "data": [
    /* 100 records */
  ],
  "nextPageCursor": "encoded-cursor-value",
  "totalElements": 250
}

Next page request:

{
  "dateRange": {
    "start": "2025-05-19T00:00:00Z",
    "end": "2025-05-19T23:59:59Z"
  },
  "displayTimezone": "UTC",
  "limit": 100,
  "nextPageCursor": "encoded-cursor-value"
}

Last page response:

{
  "data": [
    /* remaining records */
  ],
  "nextPageCursor": null,
  "totalElements": 250
}

Sorting

The API supports sorting of results through two parameters in the request body:

• sortField: Specifies which field to sort by (default: TIME)

  ℹ️ Note: Currently, TIME is the only available sortField.

• sortDirection: Specifies the sort order, either ASC (ascending) or DESC (descending) (default: ASC)

Example:

{
  "dateRange": {
    "start": "2025-05-19T00:00:00Z",
    "end": "2025-05-19T23:59:59Z"
  },
  "displayTimezone": "UTC",
  "sortField": "TIME",
  "sortDirection": "DESC"
}

Data Models

Journey Data Model

The Journeys Endpoint provides a consolidated view of all customer interactions belonging to the same journey across all 8x8 platforms. Each journey record includes the following structure:

Field	Type	Description
time	ISO8601 date	When the journey occurred
journeyId	string	The journeyId field returned by the Journeys Endpoint uniquely identifies and aggregates all interactions associated with a particular customer journey across all platforms. Use this journeyId to correlate and analyze comprehensive interaction data for a specific journey.
interactions	Interaction[]	Array of interaction objects representing the interactions belonging to the journey. These interactions can originate from CC, UC or Engage platforms.
agents	Agent[]	Array of agent objects involved in handling the journey
contact	Contact	Contact object containing name, phone number, and email who interacts with the organization. As an example for inbound phone interactions this is the caller, and for outbound ones this is the callee.
entryPoint	entryPoint	entryPoint object is populated only for inbound journeys and identifies where the interaction first enters the organization (e.g. a contact center channel, or a unified communication ring group). For outbound journeys this object is null.
transfersCompleted	int	Number of warm & cold transfers during the journey
forwardedToQueue	int	Number of automated forwards to a CC or UC queue during the journey
forwardedToRingGroup	int	Number of automated forwards to a Ring Group during the journey
forwardedToScript	int	Number of automated forwards to a UC AA + CC script/IVR
holdDuration	long	Total hold time in milliseconds
mediaTypes	string[]	Types of media in the journey (phone, chat, email, etc.)
origin	origin	Origin object is populated only for UC outbound calls and identifies what agent made the call
outcome	string	Outcome of the journey (e.g. abandoned, handled, forwarded to VM).
direction	string	Direction of the journey (e.g. Inbound, Outbound, Internal).
pbxNames	string[]	PBX names
queues	Queue[]	Array of queue objects used in the journey
ringGroups	RingGroup[]	Array of ring group objects used in the journey
scheduleHours	string[]	Distinct array of values for all the IVR scheduleHours nodes of the journey.
tenantIds	string[]	Tenant IDs
wrapUpCodes	string[]	Wrap-up codes applied to the journey
outboundPhoneCodes	OutboundPhoneCode[]	Outbound phone codes - populated only for CC agent-initiated outbound interactions.

Nested Object Structures

Interaction Object:

{
  "id": "string",
  "direction": "string",
  "type": "string"
}

Agent Object:

{
  "id": "string",
  "subscriptionId": "string",
  "name": "string",
  "email": "string",
  "loginId": "string",
  "department": "string",
  "group": {
    "id": "string",
    "name": "string"
  }
}

ℹ️ Note on User Details

The email, loginId, and department fields reflect the current user configuration in the Admin Console at the time of the API request, not the historical configuration from when the journey or transition occurred. These fields may be null if not configured for the user.

Contact Object:

{
  "name": "string",
  "phoneNumber": "string",
  "email": "string"
}

Queue Object:

{
  "id": "string",
  "name": "string",
  "extension": "string"
}

Field	Type	Description
id	string	Unique identifier of the queue
name	string	Display name of the queue
extension	string	Queue extension number. Note: Contact Center queues do not have extensions — this field will be null for Contact Center queues. Only Unified Communications queues have extension values.

RingGroup Object:

{
  "id": "string",
  "name": "string",
  "extension": "string"
}

Field	Type	Description
id	string	Unique identifier of the ring group
name	string	Display name of the ring group
extension	string	Ring group extension number

OutboundPhoneCode Object:

The outboundPhoneCodes field is populated only for CC agent-initiated outbound interactions.

{
  "listName": "string",
  "name": "string",
  "shortCode": "string"
}

Field	Description
name	Menu text of the outbound phone code in Contact Manager
shortCode	Short code identifier of the outbound phone code
listName	Name of the outbound phone code list

entryPoint Object:

The entryPoint object is populated only for inbound journeys and identifies where the interaction first enters the organization (e.g. a contact center channel, or a unified communication ring group).

{
  "type": "string",
  "id": "string",
  "name": "string",
  "phoneNumber": "string",
  "extension": "string",
  "email": "string",
  "loginId": "string",
  "department": "string",
  "pbx": "string",
  "tenantId": "string"
}

ℹ️ Note on User Details for USER-type Entry Points

When the entry point type is user, the email, loginId, and department fields reflect the current user configuration in the Admin Console at the time of the API request, not the historical configuration from when the journey occurred. These fields may be null if not configured for the user or if the entry point type is not user.

entryPoint Type Values:

The type field in the entryPoint object is an enum that identifies the type of entry point. It can have one of the following values:

• cc-channel: The inbound interaction enters through a contact center channel (e.g. Customer Support, Sales Queue, Email Support, etc.)
• call-queue: The inbound interaction enters through a unified communication call queue
• ring-group: The inbound interaction enters through a ring group
• auto-attendant: The inbound interaction enters through a unified communication auto-attendant
• user: The inbound interaction targets a unified communication user directly, bypassing contact center channels. Entry points of this type include additional user details (email, loginId, department) reflecting current Admin Console configuration

origin Object:

The origin object is populated only for UC outbound journeys and identifies what agent initiated the call.

{
  "type": "user",
  "id": "string",
  "name": "string",
  "phoneNumber": "string",
  "extension": "string",
  "email": "string",
  "loginId": "string",
  "department": "string",
  "pbx": "string"
}

Transition Data Model

The Transitions Endpoint provides detailed information about each state change within a journey, allowing users to track the exact journey path. Journeys are identified with the journeyId. Each transition record includes:

Field	Type	Description
time	ISO8601 date	When the transition occurred
journeyId	string	ID of the parent journey
name	string	Name of the transition (e.g., WAITING, TALKING, TRANSFER)
interactionId	string	ID of the interaction
agents	Agent[]	Array of agent objects (if applicable)
previousAgents	Agent[]	Array of previous agent objects (if applicable)
previousQueue	Queue	Previous queue object (if applicable)
previousRingGroup	RingGroup	Previous ring group object (if applicable)
queue	Queue	Queue object (if applicable)
ringGroup	RingGroup	Ring group object (if applicable)
duration	long	Duration of this specific transition state in milliseconds
externalNumber	string	External number (if applicable)
mediaType	string	Media type (phone, chat, email, etc.)

Transition States

A journey can progress through multiple transition states:

• STARTED: An interaction with a customer has started. Information about the customer is included in the contact object of the journey.
• OUTBOUND_STARTED: An outbound interaction initiated by a UC user or CC agent has started. The duration captures the time from initiation until the customer answers (transition to TALKING) or the call is abandoned/disconnected (transition to FINISHED).
• IN_SCRIPT: The customer is interacting with a script like an IVR script or an auto-attendant.
• WAITING: The customer is waiting to be handled by an agent (e.g. waiting in a queue or while the phones in a ring group are ringing etc.).
• TALKING: An agent is interacting with the customer.
• HOLD: An agent has put the call on hold (e.g. while the agent is preparing a transfer).
• FORWARD: The customer interaction is routed by the system to another destination. Destinations can be an agent, a queue/ring group or a phone number. The properties agents, queue, ringGroup and externalNumber contain the destination of the forward. The properties previousAgents, previousQueue and previousRingGroup contain the origin of the forward.
• TRANSFER: The customer interaction is transferred by an agent handling the customer to another destination. Destinations can be another agent, a queue/ring group or another phone number. The properties agents, queue, ringGroup and externalNumber contain the destination of the transfer. The properties previousAgents, previousQueue and previousRingGroup contain the origin of the transfer.
• FINISHED: The customer journey has ended.

Journey Outcomes

The outcome field in the Journeys API response summarizes the result of a customer journey.

Possible Outcome Values

Value	Description
Handled	The journey was successfully handled by an agent or user.
Abandoned	The journey was abandoned by the customer before being handled by an agent or user.
EndedInScript	The journey ended in an IVR script or auto-attendant without reaching an agent or user.
Other	The journey ended with an outcome not covered by the above categories.
UnknownOutcome	The outcome could not be determined from the available data.

Error Handling

The API returns standard HTTP status codes and an error response body:

{
  "errors": [
    {
      "message": "Error message description",
      "suggestion": "Suggested action to resolve the error",
      "url": "https://developer.8x8.com/analytics/docs/end-to-end-journey-api#invalid-pbx-invalidpbx"
    }
  ]
}

Common Errors

HTTP Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error

Error Codes

This section provides detailed explanations for each error code that the API might return. Each error header is linkable via its anchor for easy navigation within the documentation.

Invalid PBX

This error occurs when one or more PBX names provided in the filter do not belong to the authenticated customer's account. It ensures that users cannot request data for PBXes that are not associated with their account.

Invalid Tenant

This error is returned when the tenant IDs specified in the filter are not recognized as belonging to the current customer's account. It helps maintain data integrity by restricting access only to authorized tenant information.

Malformed Request

This error indicates that the request payload is not properly structured. It may be due to invalid JSON syntax or an incorrect structure that does not conform to the API specification.

Bad Request

A generic error indicating that the request is invalid. This can be caused by missing required fields, incorrect data types, or any other violation of the API’s requirements.

Date Range Not Null

This error is raised when the date range parameter is missing from the request. A valid date range is required to determine the period for which the data should be retrieved.

Start Date Not Null

This error occurs when the start date of the date range is not provided. The API requires a valid start date to define the beginning of the data retrieval period.

End Date Not Null

This error is returned if the end date of the date range is missing. A valid end date is needed to mark the conclusion of the period for which data is requested.

End Date Before Start Date

This error occurs when the provided start date is later than the end date. The API expects the start date to precede the end date to form a valid interval.

Filters Not Empty

This error is triggered when the filters array is empty. At least one filter must be supplied to narrow down the data and make the query meaningful.

ISO 8061 With Timezone Format

This error is raised when a date does not conform to the ISO 8601 format with a timezone designator (for example, 2025-03-01T00:00:00Z). Correct date formatting is required for proper parsing.

Max Interval

This error indicates that the interval between the start and end dates exceeds the maximum allowed period. The user should specify a smaller date range to process the request successfully.

Filter Values Not Empty

This error is returned when a filter is provided without any associated values. Each filter must include at least one value to effectively narrow down the data.

Invalid Filter Type

This error occurs when the filter type specified in the request is not among the supported types. Users must ensure that only valid filter types are used.

Timezone Not Null

This error is raised when the displayTimezone parameter is missing. A valid IANA timezone identifier must be provided to ensure accurate time-based data processing.

Invalid Timezone

This error is thrown if the provided timezone does not match any recognized IANA timezone. Users should verify and provide a valid timezone identifier.

Invalid Sort Direction

This error occurs when the sort direction is neither asc nor desc. The API only accepts these two values for sorting order.

Invalid Sort Field

This error is returned when the sort field specified is not supported. At the moment, only the TIME field is available for sorting results.

Invalid Limit

This error indicates that the limit parameter is out of the acceptable range (typically between 1 and 1000). Users should adjust the limit to a valid number within the allowed range.

Invalid Cursor

This error is raised when the pagination cursor provided in the request is invalid. The cursor must be the one returned from a previous valid request.

Cursor And Sort Mismatch

This error indicates that the sort field or direction associated with the provided cursor does not match the current request parameters. Ensure that the cursor is used with the same sort settings as those in the original response.

Missing PBX For Customer

This error is thrown when the authenticated customer’s account does not have an associated PBX. The user should contact their account administrator to have a PBX linked to their account.

Invalid Endpoint

This error occurs when the requested API endpoint does not exist or is not recognized by the API.

Please verify the endpoint against the valid paths listed in the API Endpoints section above.

Invalid Request Method

This error is returned when the HTTP method used in the request does not match the expected method for the endpoint.

Please ensure you are using the correct HTTP method (e.g., POST) as specified in the API Endpoints section above.

Rate Limiting

The API implements rate limiting to protect system resources. By default up to 10 hits are allowed within a 60 seconds sliding window. When rate limits are exceeded, the API returns a 429 status code with a Retry-After header indicating when you can try again.

Use Cases

1. End-to-End Customer Journey Analysis

For organizations with complex call flows that span multiple platforms (such as transferred calls between contact center agents and back-office teams), this API provides a complete view of the customer journey.

Implementation Steps

1. Retrieve journey data:

POST /v1/journeys/search

{
  "dateRange": {
    "start": "2025-05-19T08:00:00+03:00",
    "end": "2025-05-19T23:00:00+03:00"
  },
  "filters": [
    {
      "name": "pbxNames",
      "values": [
        "mainPbx"
      ]
    }
  ],
  "displayTimezone": "Europe/Paris",
  "limit": 50
}

2. For detailed journey analysis, retrieve transition data using the journeyId from the journeys response:

POST /v1/transitions/search

{
  "dateRange": {
    "start": "2025-05-19T08:00:00+03:00",
    "end": "2025-05-19T23:00:00+03:00"
  },
  "filters": [
    {
      "name": "journeyId",
      "values": [
        "journey-123"
      ]
    }
  ],
  "displayTimezone": "Europe/Paris",
  "sortDirection": "ASC"
}

2. Transfer Pattern Analysis

For organizations that want to understand how calls are being transferred between systems and analyze transfer patterns.

Implementation Steps

1. Retrieve all transfer transitions:

POST /v1/transitions/search

{
  "dateRange": {
    "start": "2025-05-19T00:00:00+03:00",
    "end": "2025-05-19T23:59:59+03:00"
  },
  "filters": [
    {
      "name": "transitions.name",
      "values": [
        "TRANSFER"
      ]
    }
  ],
  "displayTimezone": "Europe/Paris",
  "limit": 100
}

3. Queue Performance Analysis

For analyzing queue performance across different platforms.

Implementation Steps

1. Retrieve journey data filtered by queues:

POST /v1/journeys/search

{
  "dateRange": {
    "start": "2025-05-19T00:00:00+03:00",
    "end": "2025-05-19T23:59:59+03:00"
  },
  "filters": [
    {
      "name": "queues.name",
      "values": [
        "support",
        "sales",
        "technical"
      ]
    }
  ],
  "displayTimezone": "Europe/Paris",
  "limit": 100
}

Best Practices

1. Use appropriate date ranges: Keep date ranges reasonably small (ideally less than 1 day) to improve performance. For longer historical analysis, consider breaking your requests into multiple segments.

2. Apply relevant filters: Use filters to narrow down results and improve response times.

3. Handle pagination properly: Always check for the nextPageCursor and fetch all pages when needed.

4. Respect rate limits: Implement appropriate retry mechanisms with backoff when encountering rate limiting.

5. Cache results when appropriate: For frequently accessed data that doesn't change often, consider caching on your side.

6. Handle errors gracefully: Check for error responses and retry with backoff for transient errors.

API Glossary

Time Representations

All times in the API are represented in ISO 8601 format with timezone designator (e.g., 2025-03-01T00:00:00Z). The displayTimezone specified in your request is only used for displaying purposes.

Duration Metrics

All duration metrics (handling time, wait time, etc.) are provided in milliseconds.

Media Types

• phone: Phone interactions
• chat: Chat interactions
• email: Email interactions

Interaction Direction

• inbound: Customer-initiated interactions
• outbound: Agent-initiated interactions
• internal: Internal interactions (e.g., between agents)

PBX and Tenant IDs

PBX names and tenant IDs are used for filtering and represent the 8x8 platform instances your organization uses.

Further Assistance

For additional support or questions about the CIDP Journey API, please contact your 8x8 representative or submit a support ticket through the 8x8 support portal.