NICE CXone: Building Custom Reporting Dashboards with the OData API

How-To-Articles
1

NICE CXone: Building Custom Reporting Dashboards with the OData API

What This Guide Covers

You are building a custom, near real-time BI dashboard (in PowerBI, Tableau, or Excel) that ingests ACD, Agent, and Contact data directly from NICE CXone. Rather than relying on the legacy scheduled FTP CSV exports (Data Download), you will implement a modern pipeline using the NICE CXone Open Data Protocol (OData) API. When complete, your business analysts can write standard SQL-like queries natively in their BI tools to pull fresh metrics from CXone without requiring middle-tier database replication or complex Python parsing scripts.

Prerequisites, Roles & Licensing

  • NICE CXone: Standard reporting license.
  • Permissions required:
    • Reporting > Custom Reporting > OData API (Must be explicitly granted to the user or OAuth client).
    • Security > API Applications > Create/Edit
  • BI Tool: PowerBI, Tableau, Excel (Get Data > From OData Feed), or any tool supporting the OData v4 standard.

The Implementation Deep-Dive

1. The Power of OData vs. Standard REST APIs

The standard CXone Admin/ACD REST APIs are designed for transactional actions (e.g., “Change this agent’s skill”, “Get the current state of Contact 12345”). They are highly rate-limited and not designed to return 500,000 rows of historical data.

The CXone OData API is explicitly designed for analytical queries. It exposes CXone’s internal reporting cubes as a standardized web protocol.

  • REST API: GET /v12.0/agents (Returns a fixed JSON structure).
  • OData API: GET /odata/v1/Agents?$select=AgentId,FirstName&$filter=IsActive eq true (Allows SQL-like SELECT and WHERE clauses natively in the URL).

2. Authentication: The Access Key

Unlike the standard CXone APIs which typically use OAuth 2.0 Bearer tokens, the OData API requires an Access Key.

Step 1: Generate the Access Key

  1. Log into CXone as an Administrator.
  2. Navigate to Admin > Users.
  3. Select the “Reporting Service Account” user. (Do not use a human user; if the human leaves the company and their account is deactivated, all BI dashboards will break).
  4. Go to the Access Keys tab and click Generate New Access Key.
  5. Copy the Access Key ID and Secret Access Key. You will only see the secret once.

3. Connecting PowerBI to the OData Endpoint

PowerBI has a native OData connector, making this integration completely code-less.

Step 1: Construct the Root URL
The root URL depends on your CXone cluster (e.g., na1, eu1).
Format: https://api-odata-{cluster}.niceincontact.com/odata/v1/
Example: https://api-odata-na1.niceincontact.com/odata/v1/

Step 2: Establish the Connection

  1. In PowerBI Desktop, click Get Data > OData Feed.
  2. Paste the Root URL into the dialog.
  3. PowerBI will prompt for Authentication. Select Basic.
  4. Username: Enter your Access Key ID.
  5. Password: Enter your Secret Access Key.
  6. Click Connect.

PowerBI will securely authenticate and present you with the Navigator window, displaying all the available CXone OData tables (e.g., AgentContactStates, Contacts, Skills).

4. Querying the OData Model (Best Practices)

You can select the Contacts table in PowerBI and click “Load”, but if your contact center handles 50,000 calls a day, downloading the entire table will freeze PowerBI and eventually time out the CXone API.

You must push the filtering logic back to the CXone server using OData query parameters (Query Folding).

Example: Fetching Yesterday’s Inbound Voice Contacts

Instead of loading the root URL, provide a specific query to PowerBI:

https://api-odata-na1.niceincontact.com/odata/v1/Contacts?$select=ContactId,SkillId,AgentId,StartDate,Duration&$filter=MediaType eq 1 and StartDate ge 2026-05-13T00:00:00Z and StartDate lt 2026-05-14T00:00:00Z

Understanding the OData Syntax:

  • $select: Acts like SQL SELECT. Only returns the columns you need, drastically reducing payload size.
  • $filter: Acts like SQL WHERE.
    • eq: Equals.
    • ge: Greater than or equal to.
    • lt: Less than.
  • MediaType eq 1: The integer code for Voice (Phone) interactions.

Step 3: Dynamic Date Filtering in Power Query (M)
Hardcoding dates in the URL means you have to update the BI report every day. Use Power Query (M) to make the date dynamic.

let
    // Calculate yesterday's date
    Yesterday = Date.ToText(Date.AddDays(DateTime.Date(DateTime.LocalNow()), -1), "yyyy-MM-dd"),
    Today = Date.ToText(DateTime.Date(DateTime.LocalNow()), "yyyy-MM-dd"),
    
    // Construct the OData URL
    Url = "https://api-odata-na1.niceincontact.com/odata/v1/Contacts?$filter=StartDate ge " & Yesterday & "T00:00:00Z and StartDate lt " & Today & "T00:00:00Z",
    
    // Fetch data
    Source = OData.Feed(Url, null, [Implementation="2.0"])
in
    Source

5. Building the “Agent State” Dashboard

A common requirement is calculating exactly how much time agents spent in “Available” vs. “Unavailable” states.

The Contacts table only shows interactions. For agent state, you must query the AgentContactStates table.

The Complexity of Agent States:
CXone records state changes as distinct rows. If an agent goes Available at 9:00, then InboundContact at 9:10, there are two rows. To calculate the duration of the Available state, you must calculate the delta between the StartDate of the Available row and the StartDate of the subsequent row.

The Solution:
Do not attempt to calculate this in DAX/PowerBI unless you are a DAX expert. CXone provides a pre-calculated table specifically for this: AgentStateDetails.

Query AgentStateDetails using OData:

https://api-odata-na1.niceincontact.com/odata/v1/AgentStateDetails?$select=AgentId,StateName,Duration,StartDate&$filter=StartDate ge 2026-05-13T00:00:00Z

This table explicitly provides the Duration (in seconds) the agent spent in each state, making dashboard aggregation (e.g., a pie chart of StateName by sum of Duration) trivial.

Validation, Edge Cases & Troubleshooting

Edge Case 1: The 10,000 Row Pagination Limit

The CXone OData API enforces a strict maximum page size of 10,000 rows (@odata.nextLink). If you execute a query that matches 50,000 rows, the API returns the first 10,000 and a URL to fetch the next 10,000.
Solution: If using PowerBI’s native OData connector, PowerBI handles this pagination automatically behind the scenes. However, if you are writing a custom Python script to extract the data, you MUST inspect the JSON response for the @odata.nextLink property and implement a while loop to follow the links until the property is null. Failure to do so will result in massive, silent data loss in your reports.

Edge Case 2: Data Latency (Near Real-Time vs. Real-Time)

A supervisor complains that the BI dashboard doesn’t show a call that ended 2 minutes ago.
Solution: The OData API queries the CXone reporting data mart, not the active transactional database. There is a documented ETL latency (typically 5 to 15 minutes) for data to propagate from the live ACD into the OData cubes. Do not use the OData API to build “Live Wallboards” intended to monitor queue depth by the second; use the standard REST ACD API or WebSocket streams for live monitoring. OData is for historical analytics.

Edge Case 3: Time Zone Confusion

By default, the OData API returns all DateTime fields in UTC. If your business analysts are unaware of this, they will build reports showing “Peak Call Volume” at 11:00 PM (for a US-based contact center).
Solution: Apply a time zone conversion step in your BI tool (e.g., Power Query DateTimeZone.SwitchZone) to convert the UTC timestamps to your contact center’s primary local time zone before generating any charts based on hour-of-day.

Official References