Export Summary APIs

Note: This feature is available with the Advanced license.

You can use the Export Summary API to retrieve agent time-off summary information from CXone WFM by activity code name.

This API returns user-level time-off balances, including earned days, days taken, scheduled, remaining, carried over, and accrual details — in both days and hours.

Prerequisites

You need the Rules & Summary manage/view permission.
You need a valid access token. For details on authentication, see the WFM API documentation on the DEVone portal.

Request

method	Endpoint
GET	/timeoff-manager/summary/{activityCodeName}

Request Parameters

PARAMETERS	TYPE	location	required	Description
activityCodeName	String	Path	Yes	The name of the activity code.
top	integer (int32)	Query	No	The number of records to return.
skip	integer (int32)	Query	No	The number of records to skip.

Response

200 — Successful Response

Returns the time-off summary for all users associated with the specified activity code.

Example

var(--codeSnippetCopyLabel)

{
  "totalRecords": 0,
  "top": 0,
  "skip": 0,
  "timeOffUserSummaryList": [
    {
      "userName": "string",
      "activityCodeName": "string",
      "timeZone": "string",
      "hireDateInUtc": "2026-07-21",
      "daysPerYear": 0,
      "daysTaken": 0,
      "scheduled": 0,
      "remaining": 0,
      "earned": 0,
      "carriedOver": "string",
      "accrualValueInDays": 0,
      "accrualType": "string",
      "hoursPerDay": 0,
      "totalHours": "string",
      "hoursTaken": "string",
      "hoursScheduled": "string",
      "hoursRemaining": "string",
      "hoursEarned": "string",
      "hoursCarriedOver": "string",
      "accrualValueInHours": "string"
    }
  ]
}

Response Fields

FIELD	TYPE	DESCRIPTION
totalRecords	integer	The total number of records available.
top	integer	The number of records returned.
skip	integer	The number of records skipped.
userName	string	The name of the agent.
activityCodeName	string	The name of the time-off activity code.
timeZone	string	The agent's time zone.
hireDateInUtc	string (date)	The agent's hire date in UTC.
daysPerYear	number	The total allotted days per year.
daysTaken	number	The number of days already taken.
scheduled	number	The number of days currently scheduled.
remaining	number	The number of days remaining.
earned	number	The number of days earned to date.
carriedOver	string	The number of days carried over from the previous period.
accrualValueInDays	number	The accrual value in days.
accrualType	string	The type of accrual (for example, monthly percentage).
hoursPerDay	number	The number of hours per day used for conversion.
totalHours	string	The total allotted hours.
hoursTaken	string	The hours already taken.
hoursScheduled	string	The hours currently scheduled.
hoursRemaining	string	The hours remaining.
hoursEarned	string	The hours earned to date.
hoursCarriedOver	string	The hours carried over from the previous period.
accrualValueInHours	string	The accrual value in hours.

Error Responses

400 — Bad Request

This error occurs when:

The activity code name is invalid.
There is no active time-off rule for the requested activity code name.

var(--codeSnippetCopyLabel)

{
  "code": "Bad Request",
  "details": "Invalid activity code name."
}

401 — Unauthorized

This error occurs when:

User authentication failed.
The authentication token is invalid or missing.

var(--codeSnippetCopyLabel)

{
  "message": "Unauthorized"
}

403 — Forbidden

This error occurs when:

You don't have the Rules & Summary manage/view permission.
The Export User Summary feature is not enabled.
Your license doesn't include HR integration APIs (Advanced license required).

var(--codeSnippetCopyLabel)

{
  "code": "Forbidden",
  "details": "The Export User Summary feature is not enabled."
}

500 — Internal Server Error

An unexpected error occurred. Contact support.

var(--codeSnippetCopyLabel)

{
  "code": "Internal Server Error",
  "details": "Something went wrong. Contact support."
}

Response Parameters

PARAMETERS	TYPE	DESCRIPTION
agentIdentifier	String	The unique identifier of the agent.
activityCode	String	The time-off activity code.
earnedBalance	Number	The total earned time-off balance.
usedBalance	Number	The total used time-off balance.
remainingBalance	Number	The remaining time-off balance (earned minus used).
carryoverBalance	Number	The balance carried over from the previous period (if applicable).