Import Allotment API

Note: This feature is available with the Advanced license.

You can use the Import Allotment API to update agent time-off allotments in CXone WFM from an external HR or payroll system.

You provide the activity code name, user IDs, allotment values, and the unit of allotment (days or hours). The API updates the balances in WFM and returns a confirmation on success.

Prerequisites

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

Request

method	Endpoint
PUT	/timeoff-manager/allotments/import

Request Body

Content type: application/json

FIELD	TYPE	required	Description
activityCodeName	string	Yes	The name of the activity code associated with the time-off type.
allotmentType	string	Yes	The unit of allotment. Valid values: Days, Hour.
allotmentByUserName	object	No	A set of key-value pairs where each key is the user's email address and each value is the allotment amount.

Example

var(--codeSnippetCopyLabel)

{
  "activityCodeName": "string",
  "allotmentType": "Days",
  "allotmentByUserName": {
    "Test.User@nice.com": 12
  }
}

Response

200 — Successful Response

The import was successful. WFM updated the allotments for the specified agents.

var(--codeSnippetCopyLabel)

{
  "code": "OK",
  "details": "Update successful."
}

Error Response

400 — Bad Request

This error occurs when:

The input data is null or empty.
The activity code name is invalid.
The allotment type is invalid.
A user ID or its allotment value is invalid.

var(--codeSnippetCopyLabel)

{
  "code": "Bad Request",
  "details": {
    "INVALID_USER_ALLOTMENT": null,
    "INVALID_ACTIVITY_CODE": null,
    "INVALID_ALLOTMENT_TYPE": null
  }
}

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 permission.
The Import Users Allotment feature is not enabled.
Your license doesn't include HR integration APIs (Advanced license required).

var(--codeSnippetCopyLabel)

{
  "code": "Forbidden",
  "details": "The Import Users Allotment 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."
}