Export Agent Schedules API

Use the Export Agent Schedules API to easily export agent schedules from CXone Mpower Workforce Management to other applications. With this API, you can retrieve the schedule of a single agent per request. The agent’s schedule can be retrieved for a period of up to seven days.

The Export Agent Schedules APIs are available in the developer portal.

For example, you want to have automatic scheduling in your interactive voice response (IVR) system. You can use this API to tell the caller if a certain employee is available.

See Getting Started in the developer portal before using this API.

Before using the Export Agent Schedules API, you must:

  • Generate an access key. When you create the employee in CXone Mpower for the service, it needs to:

    • Have the View or Manage permission under WFM > Scheduling > Schedule Manager.

    • Be assigned to a view that gives permission to see the agent's scheduling units (or teams).

  • Follow the registration and authentication process explained on the developer portal.

You can check with your administrator if have these permissions. The administrator can find these permissions in CXone Mpower. Go to Admin > Security Settings > Roles and Permissions and select the role.

API Request

The Export Agent Schedules entity name for the POST job is export API. The endpoint is /schedules/export.

  • startDate: The format is yyyy-mm-dd.

  • endDate: The format is yyyy-mm-dd. The range can be up to seven days from the start date.

  • userID: You can use the Search Users API to find the user's ID.

  • userID: The agent’s unique ID.

  • shifts: Details about the shift.

    • shiftNotes: Comments regarding the agent’s shift.

    • activityIntervals: How many activities are in the shift.

    • baseActivityCode: Details of the shift’s base activity code.

      • title: Name of the activity code.

      • The attributes that may be included in this activity code: open, work, overTime.

    • start: Start date and time of the activity.

    • end: End date and time of the activity.

  • activityIntervals: Activities that weren’t scheduled as part of a shift.

  • start: Start date of the shift.

  • end: End date of the shift.

Example value

 {
“startDate”: “2023-10-08”,
“endDate”: “2023-10-14”,
“userID”: “11ed7199-e04e-1f80-9ebb-0262bc110012”
}

Responses

  • Status 200 - Success. The schedule was exported successfully.

     {
"agentSchedules": [
{
"userId": "11ed7199-e04e-1f80-9ebb-0262bc110012",
"shifts": [
{
"shiftNotes": null,
"activityIntervals": [],
"baseActivityCode": {
title": "Open (Default)",
"open": true,
"work": true,
"overTime": false
},
"start": "2023-06-28T03:00:00Z",
"end": "2023-06-28T12:00:00Z"
}
],
"activityIntervals": []
}
],
"start": "2023-06-28",
"end": "2023-06-28"
}

  • Status 400 - Bad Request. This can happen when:

    • Can't retrieve schedule. Wrong userID or you don't have permission to view this agent.

    • The requested date range is greater then seven days.

    • The request is missing or has wrong data.

  • Status 401 - The access token is invalid.

  • Status 403 - User account making the API call does not have the required permission.

API to Find User ID

When exporting an agent schedule, you need the agent's user ID. You can use the Search Users API to find it.

The entity name for the GET job is user search, and the endpoint is /user-management/v2/users/search.

In the request, enter the employee’s username. This will give you the user ID. You can find their username in their employee account.

 
{
“filter”; {
“userName”: [“AgentSmile@BankABC.com”]
}