Data Extraction APIs

The Data Extraction APIs let you extract data from CXone for external reporting purposes. For example, you can extract CXone QM workflow data, CXone QM question and answer data, CXone Recording interaction metadata, or CXone WFM Payroll data. Data can only be filtered according to the specified date range.

The Data Extraction APIs are available in the DEVone Developer Community portal.

For more information about domains and URLs, see Getting Started in the DEVone Developer Community portal.

When calling the endpoint /jobs with POST method, a jobId is returned while the data is being prepared. You can verify if the data is ready by polling the service from the endpoint /jobs/{jobId}, the status of the job is returned. If the status is success, then an additional URL is also returned. The URL will be accessible for 30 seconds (not including the time it takes to download the file).

You can write scripts to call the API periodically instead of retrieving the data manually each time. At any given time, only one user per tenant can call an API. You can only call the API once in a 30 second period.

Before You Start

Before you can start using the Business Data API, you must set up user permissions, generate an access key, and follow the registration and authentication process explained on the developer portal. Required permissions:

Entity:
- If you're extracting interaction metadata, then you need the Search & Playback > APIs > Extract Interaction Metadata permission.
- If you're extracting CXone QM workflow data, then you need the QM Tools > Data Extraction APIs > QM Workflow API permission.
- If you're extracting CXone QM Q&A data, then you need the QM Tools > Data Extraction APIs > QM Workflow API permission.
- If you're extracting CXone WFM Payroll data, then you need the CXone WFM > Data Extraction APIs > CXone WFM Payroll API permission.

GET Jobs

View a list of all job statuses per tenant. Possible statuses are Running, Succeeded, Failed, Cancelled, and Expired.

POST Jobs

After a request to extract data is made, the data is gathered and prepared for extraction. The data is available in S3 as a CSV file for 24 hours. When done, a job ID is returned.

Example value and responses

Request Body*:	application/json
exportRequest { description:	Parameters that need to be provided in order to extract data.
entityName	string Name of entity to extract. For the correct entity names, see below.
version	string Version of entity to extract. For the correct versions for each entity, see below.
startDate	string($date) Date, in UTC, from which to start extracting data. The date format is <YYYY-MM-DD>. For example, to extract data from May 22nd, 2019, enter the date: 2019-05-22.
endDate	string($date) Date, in UTC, from which to stop extracting data. The date format is <YYYY-MM-DD>. For example, to extract data until May 29th, 2019, enter the date: 2019-05-29.
}

Example Value

{
  "entityName": "qm-workflows",
  "version": "3",
  "startDate": "2019-05-22",
  "endDate": "2019-05-29"
}

Responses

Status 202 - Success. Successfully exported asynchronous job.

string

Example: 12345d5h-c099-9303-j99j-w3ko9ppp1234
Status 400 - Invalid request. Incorrect date filters, etc.
Status 401 - Unauthorized. Invalid credentials.
Status 403 - Forbidden. User does not have permission to view job status.
Status 404 - Not Found. Missing entity or invalid version.
Status 500 - Internal Server Error.

GET Jobs by Job ID

View the status for a specific job per its job ID. If a job was successful, a URL to access the extracted data is returned and is accessible for 30 seconds (not including the time it takes to download the file). If the job failed, an error message is returned. The link can be used to access the extracted data. Possible job statuses are Running, Succeeded, Failed, Cancelled, and Expired.

Example value and responses

jobId*:

string

Unique identifier for the request that was made to extract customer data.

Example Value

12345d5h-r3ds-9303-0pw3-w3ko9ppp1234

Responses

Status 202 - Success. Retrieved job status.

  jobResponse{
	description: Displays the job status
	jobStatus: {
		description: Job Status, includes job ID and job status
		id:	string
			Unique identifier of the job.
		status: string 
			example: SUCCEEDED
 			Job status that can be returned.
 			Enum: [ RUNNING, SUCCEEDED, FAILED, CANCELLED, EXPIRED ]
		result: {
			description:	Job result. If successful, contains the url, if failed, an error message is displayed.
			url:		string
					example: https://s3.example.amazonaws.com/results-bucket/data-extraction/{details}
					A url to access the extracted data is returned when a job for extracting data is successful.
			errorMessage: 	string
					Error message displayed when a request for   extracting data fails. 
		}
 	}
  }

Status 400 - Invalid request. Incorrect date filters, etc.
Status 401 - Unauthorized. Invalid credentials.
Status 403 - Forbidden. User does not have permission to view job status.
Status 404 - Not Found. Missing entity or invalid version.
Status 500 - Internal Server Error.

CXone QM Workflow Entity and CSV File

The CXone QM Workflow API allows you to extract CXone QM workflow data, including evaluations, self-assessments, and calibrations.

For the POST job:

entityName is: qm-workflows
version is: 4

Data is filtered according to the Submission Date (in UTC).

Fields in the CXone QM workflow CSV file

Column Name	Description
Tenant Name	Name of the tenant.
Agent ID	Unique identifier of the agent. Field type: String with up to 36 characters (VARCHAR)
Type	Type of evaluation, for example: Evaluation Self-Assessment Field type: String with up to 24 characters (VARCHAR)
Evaluation Flow Trigger	Event that started the evaluation: Calibration Collaborative Manual QP Field type: String with up to 24 characters (VARCHAR)
Workflow Status	Status of workflow: Sent to Agent In Review Dispute Completed Acknowledged Complete Self Assessment Completed Reviewed Completed No Review Completed Deleted Deleted - Completed Expired Deleted - Expired Deleted - Completed Acknowledged Deleted - Completed Reviewed Deleted - Completed No Review Field type: String with up to 128 characters (VARCHAR)
Auto Acknowledged	Possible values are: TRUE: If the agent did not acknowledge the evaluation, it was automatically acknowledged. FALSE: If agent acknowledged the evaluation. Empty value: in cases of self-assessment, no acknowledgment is necessary. Field type: BOOLEAN
Workflow State	State of workflow: Open Closed Timed-Out Field type: String with up to 128 characters (VARCHAR)
Workflow ID	The unique identifier of the evaluation. Field type: String with up to 36 characters (VARCHAR) API version: 3 and higher
Plan Name	The name of the quality plan used to initiate this evaluation. Field type: String with up to 128 characters (VARCHAR)
Form Name	The name of the form used for this evaluation. Field type: String with up to 256 characters (VARCHAR)
Form Version	The version of the evaluation form used for this evaluation. Field type: Number(4,0)
Start Date	Date and time (in UTC) when this evaluation started. Field type: TIMESTAMP_LTZ(3)
Submission Date	Date and time (in UTC) when this evaluation was submitted. Field type: TIMESTAMP_LTZ(3)
Last Updated	Timestamp (in UTC) when this evaluation was last modified. Field type: TIMESTAMP_LTZ(3)
Score – Percentage	Evaluation score as a percentage. Field type: FLOAT
Score	Evaluation score. Field type: FLOAT
Maximum Possible Score	The highest score possible for each question in the evaluation form. Field type: FLOAT
Rank	Custom range of values set by the user to define the form rank. Field type: String with up to 256 characters (VARCHAR)
Failed Critical Question	If the value is true, the user failed a critical question and the evaluation form score is set to zero. If the value is false, the user answered the question correctly. Field type: BOOLEAN
User Review Comments	The comments entered by the user (agent) while disputing the evaluation. Field type: String with up to 256 characters (VARCHAR)
Dispute Resolver Comments	The comments entered by the user (manager/evaluator) while closing the dispute. Field type: String with up to 256 characters (VARCHAR)
Segment ID	The segment ID of the interaction that is being evaluated. Field type: String with up to 36 characters (VARCHAR)
ACD ID	Unique identifier of the automatic call distributor. Field type: Number(38,0)
Interaction Type	Type of interaction: PHONE_CALL EMAIL CHAT SMS WORKITEM GOOGLE_BUSINESS_MESSAGES_PRIVATE APPLE_BUSINESS_CHAT_PRIVATE TELEGRAM_PRIVATE LINE_PRIVATE WHATSAPP_PRIVATE SLACK_PRIVATE MICROSOFT_TEAMS_PRIVATE TW_PRIVATE VIBER_PRIVATE CUSTOM_PRIVATE WE_CHAT_PRIVATE FB_PRIVATE Field type: String with up to 50 characters (VARCHAR)
Interaction Start Date	Start date-time (in UTC) of the interaction. Field type: TIMESTAMP_LTZ(6)
Interaction End Date	End date-time (in UTC) of the interaction. Field type: TIMESTAMP_LTZ(6)
Interaction Direction	Direction of call: Inbound Outbound Field type: String with up to 50 characters (VARCHAR)
Team ID	The unique identifier of the agent's team. Field type: String with up to 36 characters (VARCHAR)
Team Name	Agent's team name. Field type: String with up to 50 characters (VARCHAR)
Phone Number	Customer’s phone number. Field type: String with up to 200 characters (VARCHAR)
FirstName (Eva)	First name of the evaluator. Field type: String with up to 255 characters (VARCHAR)
LastName (Eva)	Last name of the evaluator. Field type: String with up to 255 characters (VARCHAR)
FirstName (Agent)	First name of the evaluated agent. Field type: String with up to 255 characters (VARCHAR)
LastName (Agent)	Last name of the evaluated agent. Field type: String with up to 255 characters (VARCHAR)
FirstName (Disp)	First name of the dispute resolver. Field type: String with up to 255 characters (VARCHAR)
LastName (Disp)	Last name of the dispute resolver. Field type: String with up to 255 characters (VARCHAR)
FirstName (Assigner)	First name of the user who assigned the evaluation. Field type: String with up to 255 characters (VARCHAR)
LastName (Assigner)	Last name of the user who assigned the evaluation. Field type: String with up to 255 characters (VARCHAR)
Reason	Reason for the deletion of the evaluation. Field type: String with up to 128 characters (VARCHAR) API version: 4 and higher
Parent ID	Parent workflow ID of the evaluation, such as collaborative and calibration. Field type: String with up to 36 characters (VARCHAR) API version: 4 and higher
Evaluation Subject	Possible values are: Employee Segment Field type: String with up to 128 characters (VARCHAR) API version: 4 and higher

CXone QM Questions and Answers (Q&A) Entity and CSV File

The CXone QM Q&A API allows you to extract the questions and answers from CXone QM evaluations, self-assessments, and calibrations.

For the POST job:

entityName is: qm-questions
version is: 1

Data is filtered according to the Submission Date (in UTC).

Fields in the CXone QM Q&A CSV file

Column Name	Description
Question ID	Unique identifier of the question. Field type: NUMBER(38,0)
Question Title	The text of the question. Field type: String with up to 2048 characters (VARCHAR)
Question Number	The number of the question in the evaluation form. Field type: String with up to 15 characters (VARCHAR)
Answer	The evaluator's answer to the question. Field type: String with up to 10000 characters (VARCHAR)
Options	The available answer options for the question, such as yes/no, numeric options, radio button options, etc. Field type: ARRAY
Form ID	Unique identifier of the evaluation form. Field type: String with up to 36 characters (VARCHAR)
Form Name	The name of the form used for this evaluation. Field type: String with up to 256 characters (VARCHAR)
Form Version	The version of the evaluation form used for this evaluation. Field type: NUMBER(4,0)
Evaluation Start Date	Date and time (in UTC) when this evaluation started. Field type: TIMESTAMP_LTZ(3)
Evaluation Submission Date	Date and time (in UTC) when this evaluation was submitted. Field type: TIMESTAMP_LTZ(3)
Workflow Type	Type of evaluation, for example: Evaluation Self-Assessment Field type: String with up to 24 characters (VARCHAR)
Section ID	Unique identifier of the section in evaluation form. Field type: NUMBER(38,0)
Section Title	The name of the section in evaluation form. Field type: String with up to 2048 characters (VARCHAR)
Scorable	True or false flag for if the question could be scored. Field type: BOOLEAN
Actual Score	The score the agent received on the question. Field type: FLOAT
Section Score (%)	The percentage score of the section where the question was located. Field type: FLOAT
Max Score	The maximum score an agent could have received on the question. Field type: FLOAT
Agent ID	Unique identifier of the agent. Field type: String with up to 36 characters (VARCHAR)
FirstName (Agent)	First name of the evaluated agent. Field type: String with up to 255 characters (VARCHAR)
LastName (Agent)	Last name of the evaluated agent. Field type: String with up to 255 characters (VARCHAR)
Team ID	The unique identifier of the agent's team. Field type: String with up to 36 characters (VARCHAR)
Team Name	Agent's team name. Field type: String with up to 50 characters (VARCHAR)
FirstName (Eva)	First name of the evaluator. Field type: String with up to 255 characters (VARCHAR)
LastName (Eva)	Last name of the evaluator. Field type: String with up to 255 characters (VARCHAR)
Critical	True or false flag for if the question was a critical question. Field type: BOOLEAN
Failed Critical Question	If the value is true, the user failed a critical question and the evaluation form score is set to zero. If the value is false, the user answered the question correctly. Field type: BOOLEAN
Mandatory	True or false flag for if the question was mandatory. Field type: BOOLEAN
Question Type	The type of question: Radio Yes/No Checkbox Dropdown Date/Time Field type: String with up to 64 characters (VARCHAR)
Segment ID	The segment ID of the interaction that is being evaluated. Field type: String with up to 36 characters (VARCHAR)
Interaction Start Date	Start date-time (in UTC) of the interaction. Field type: TIMESTAMP_LTZ(6)
Interaction End Date	End date-time (in UTC) of the interaction. Field type: TIMESTAMP_LTZ(6)
WorkflowInstance ID	The unique identifier of the evaluation. Field type: String with up to 36 characters (VARCHAR)
Evaluation Score (%)	The percentage score of the evaluation. Field type: FLOAT
Bank ID	Unique identifier of the question bank where the question is located. Field type: String with up to 36 characters (VARCHAR)

CXone QM Evaluator Notes and CSV File

The CXone QM Evaluator Notes API allows you to extract CXone QM evaluator notes.

For the POST job:

entityName is: qm-evaluation-comment-entity
version is: 1

Data is filtered according to the Submission Date (in UTC).

Fields in the CXone QM evaluator notes CSV file

Column Name	Description
Comment ID	The unique identifier of the comment. Field type: String with up to 36 characters (VARCHAR)
Comments	The text for the comment. Field type: String with up to 300 characters (VARCHAR)
Commented Time	Date and time when the comment was added. Field type: TIMESTAMP_LTZ(3)
Activity	The evaluation action name when the comment was added. Field type: String with up to 50 characters (VARCHAR)
Commented By ID	The unique identifier of the user who added the comment. Field type: String with up to 36 characters (VARCHAR)
Commented By FirstName	First name of the user who added the comment. Field type: String with up to 255 characters (VARCHAR)
Commented By LastName	Last name of the user who added the comment. Field type: String with up to 255 characters (VARCHAR)
Question ID	The unique identifier of the question. Field type: String with up to 36 characters (VARCHAR)
Question Title	The text of the question. Field type: String with up to 2048 characters (VARCHAR)
Form ID	The unique identifier of the evaluation form. Field type: String with up to 36 characters (VARCHAR)
Form Name	The name of the form used for the evaluation. Field type: String with up to 256 characters (VARCHAR)
Form Version	The version of the evaluation form used for the evaluation. Field type: NUMBER(4,0)
Workflow ID	The unique identifier of the evaluation. Field type: String with up to 36 characters (VARCHAR)
Workflow Status	The status of the workflow. Field type: String with up to 128 characters (VARCHAR)
Agent ID	The unique identifier of the agent. Field type: String with up to 36 characters (VARCHAR)
FirstName (Agent)	First name of the agent. Field type: String with up to 255 characters (VARCHAR)
LastName (Agent)	Last name of the agent. Field type: String with up to 255 characters (VARCHAR)
Team ID	The unique identifier of the agent's team. Field type: String with up to 36 characters (VARCHAR)
Team Name	Agent's team name. Field type: String with up to 50 characters (VARCHAR)

Interaction Metadata Entity and CSV File

The Interaction Metadata API allows you to extract CXone Recording interaction metadata.

For the POST job:

entityName is: recording-interaction-metadata
version is: 7
To filter data by date and time use startDate and endDate in UTC with the format: yyyy-mm-dd hh:mm:ss

Fields in the interaction metadata CSV file

Column Name	Description
ACD Call ID (e.g., Master Contact ID)	The ACD Call ID depends on the ACD solution, for example, this is the same as the CXone Master Contact ID The master or parent ID for one or more related contacts. A new master contact ID will be assigned if a contact has been transferred 3 or more times.. Field type: Number containing up to 38 digits
Segment ID	Unique identifier of the segment. A segment is an interaction with two parties, such as a customer and an agent. Field type: String with up to 36 characters (VARCHAR UUID)
Segment Start Reason	Reason the segment started: Conference IVR Segment: First segment in the contact Transfer Field type: String with up to 100 characters (VARCHAR)
Segment End Reason	Reason the segment ended: Conference IVR Segment: Last segment in the contact Transfer Field type: String with up to 100 characters (VARCHAR)
Direction	Direction of the segment: Inbound Outbound Internal Unknown Field type: String with up to 150 characters (VARCHAR)
Start Date	Start date and time (in UTC) of the segment. Field type: TIMESTAMP
End Date	End date and time (in UTC) of the segment. Field type: TIMESTAMP
Channel Type	Type of interaction: Voice Chat Email IVR Work Item SMS Messaging channels: Facebook Messenger, Twitter Direct Messages, WhatsApp, Apple Messages for Business, LINE Messaging, Telegram Messenger, Viber Messenger, Custom, Google Business Messenger, Microsoft Teams, Slack. Public social channels: Facebook, Google Places, Google Play, LinkedIn, Twitter, YouTube, Apple Apps Reviews, Custom (public). Field type: String with up to 150 characters (VARCHAR)
Screen Recording	If the segment includes screen recording: Yes No
Voice Recording Status	Status of the recording: Success Partially recorded: Parts of this segment were not recorded, but the interaction can still be played back Does not match any policy: No recording—none of the recording policies were triggered by this interaction Not recorded due to recording %: No recording—a recording policy was triggered by this interaction, but wasn't recorded due to the recording percent defined in the policy Do not record policy: No recording—a do not record policy was triggered for this interaction Declined consent in IVR: No recording Failed: No recording Not applicable: No recording—for example, a digital interaction, or historical interaction that were not set to record Masked: No recording—the recording was masked Record transfers to external numbers not selected: No recording No recording because mediaSourceType is NONE: No recording—no recording media was specified Can be recorded (voice) not selected: No recording—the Agent attribute Can be recorded (voice) was not selected Field type: String with up to 250 characters (VARCHAR)
Screen Recording Status	Status of the recording: Success Partially recorded: Parts of this segment were not recorded, but the interaction can still be played back Does not match any policy: No recording—none of the recording policies were triggered by this interaction Not recorded due to recording %: No recording—a recording policy was triggered by this interaction, but wasn't recorded due to the recording percent defined in the policy Do not record policy: No recording—a do not record policy was triggered for this interaction Declined consent in IVR: No recording Failed: No recording Not applicable: No recording—for example, a digital interaction, or historical interaction that were not set to record Masked: No recording—the recording was masked Record transfers to external numbers not selected: No recording No recording because mediaSourceType is NONE: No recording—no recording media was specified Can be recorded (screen) not selected: No recording—the Agent attribute Can be recorded (screen) was not selected Field type: String with up to 250 characters (VARCHAR)
Recording Alerts	Recording alerts include: ScreenAgent error: There are multiple reasons, such as the agent doesn't have ScreenAgent NICE ScreenAgent is a service that runs on agent desktops that require screen recording. installed, or there's an error with ScreenAgent. See Resolve ScreenAgent Issues . No connection to media server: No recording. There was a problem with the media server. There can be multiple reasons. The error description for the recording alert provides more detailed information. Voice recorder could not record call: No recording. There was a problem with the voice recorder. There can be multiple reasons. The error description for the recording alert provides more detailed information. Audio not available: incomplete audio data: Audio isn't available for this interaction (incomplete audio data). Contact NICE CXone support. Audio not available: missing audio packets: Audio isn't available for this interaction (missing audio packets). Contact NICE CXone support. System error: Recording did not start or another general error. Contact NICE CXone support. Call too short: Call is less than 4 seconds so cannot be recorded. Masking failed: Failed to mask recording. You can play back the recording to check if there is any sensitive data. To delete the recording, click Action and select Delete Recordings. Recording stopped on demand: Recording stopped by the user.
Policy Name	Name of the recording policy or do not record policy that was applied to this interaction. Field type: String with up to 100 characters (VARCHAR)
ANI	For incoming calls, ANI is the phone number of the caller (caller ID). Field type: String with up to 200 characters (VARCHAR)
DNIS	For incoming calls, DNIS is the phone number that was called (dialed in number). Field type: String with up to 200 characters (VARCHAR)
ACW (in seconds)	How many seconds screen recording continued after the call ended to capture the agent's after call work.
Disposition	Tag the agent assigns with additional information about the call.
Agent User ID	Unique identifier assigned to the agent. The CSV file can contain agent-related information for up to 5 agents. Field type: String with up to 36 characters (VARCHAR)
Agent ACD ID	Unique identifier assigned to the agent by the ACD. Field type: String with up to 50 characters (VARCHAR)
Agent Contact Number	Unique identifier assigned to the agent for the contact. Field type: Number containing up to 38 digits API version: 5 and higher
Agent Name	Name of the agent as specified in the CXone employee account. Field type: String with up to 100 characters (VARCHAR)
Agent Team ID	Unique identifier assigned to the agent's team. Field type: String with up to 36 characters (VARCHAR UUID)
Agent Team	Agent's team name. Field type: String with up to 40 characters (VARCHAR)
Agent Skills	Classification assigned to the agent in the ACD, based on abilities, specialties, and knowledge. Field type: String with up to 50 characters (VARCHAR)
Associated Contact No List	List of contact numbers of agents associated with the segment. The elements of this list are of number type only. Field type: Variant API version: 7 and higher
Interaction ID	A unique ID (UUID) for an interaction. When there are multiple segments associated with a single interaction, the segments can have the same Interaction ID. The Interaction ID is not the same as the Segment ID or Contact ID. Field type: String with up to 36 characters (VARCHAR) API version: 7 and higher
Business Data Name	Name of the business data field as specified. Field type: String with up to 128 characters (VARCHAR) API version: 7 and higher
Business Data Value	Business data value can be a text, numeric, or true/false. Field type: String with up to 4000 characters (VARCHAR) API version: 7 and higher
Source	The source of the recording—CXone or an external source. Values are only available for users with CXone AppLink. Field type: String with up to 30 characters (VARCHAR) API version: 6 and higher
External Contact ID	The ID of a contact as defined in the external source of the recording. Values are only available for users with CXone AppLink Field type: String with up to 100 characters (VARCHAR) API version: 6 and higher
External Segment ID	The ID of a segment as defined in the external source of the recording. Values are only available for users with CXone AppLink Field type: String with up to 100 characters (VARCHAR) API version: 6 and higher

CXone WFM Payroll Entity and CSV File

The CXone WFM Payroll API (version 1) allows you to extract CXone WFM activity data for external payroll reporting purposes.

The CXone WFM Payroll entity name for the POST job is: wfm-payroll.

Data is filtered according to the payroll code's date. Keep in mind, the time zone for the date and time are according to the scheduling unit's time zone.

Fields in the CXone WFM Payroll CSV file

Column Name	Description
First Name	Agent's first name. Field type: String with up to 255 characters (VARCHAR)
Last Name	Agent's last name. Field type: String with up to 255 characters (VARCHAR)
Username	Agent's username. Field type: String with up 255 characters (VARCHAR)
Scheduling Unit	Agent's scheduling unit. Field type: String with up 256 characters (VARCHAR)
Scheduling Unit's Time Zone	Time zone of the agent's scheduling unit. Field type: String with up 128 characters (VARCHAR)
Payroll Code	The payroll code that contains the scheduled activity data. Field type: String with up 50 characters (VARCHAR)
Date	Date (in the scheduling unit's time zone) of the activity. Field type: DATE
Start Time	Start time (in the scheduling unit's time zone) of the activity. Field type: TIME (9)
Duration In Seconds	The duration of the activity in seconds. Field type: NUMBER (8,0)