LUCS API

In the following we provide a description about the data models and functions used within LUCS and in automated interaction with other applications. Separate API Use Cases will explain how to apply those concepts in specific scenarios.

The Luware API allows customers to manage external system tasks in their own systems and block specific agents. The new Luware API component is divided into the following three parts to support three different usage areas:

Provisioning API: Configure and provision users and services in the system
Reporting API: Get system information and reporting data
Control API: Add and manage callback and external system tasks

Target audience

This Document is written for System Administrators and Developers of 3rd party products using LUCS functionality externally . If you are in need of additional support or want to provide feedback, don’t hesitate to contact us.

Preconditions & System Requirements

LUCS needs to be installed and fully configured respectively using the API. Please refer to the "Precondition" Documents of your respective Luware Product and Version.

API and Luware Version compatibility

The API functionality described in this documentation is only supported for LUCS Versions 3.1 or newer.

Version mismatches between LUCS base components and the installed API can lead to erratic system behavior, errors and potential loss of database content!

→ Make sure to only install the corresponding API setup matching and delivered alongside your Luware product.

API Checklist - Before you start

LUCS and API Component is installed → See chapter below and API - Advanced Programming Interface
1. AC, AM, CI and CIC Services must be running as well in order to operate the system overall → See Architecture
2. IIS is running to operate the Web FrontEnd User Interface
Check in "Home" Tab in LUCS Configurator or Web Configurator and check if the API service is running.
Generate a new API Key → See chapter below
Configure Access rights for the key → See chapter below

If malfunctions occur after setting changes (e.g. in the API Component, Network Ports or IIS) a quick restart of API Services is recommended.

Ensure that the API port used is also exempt from any Anti-Virus and Firewall tools

API Ports

Since the LUCS API uses the functionality of LUCS, ports need to be forwarded.

Source	Destination	Protocol	Destination Server Port (Default)	Comment
Agent PC (LUCS-API)	LUCS Server 01	TCP	4444	LUCS Web API
Agent PC (LUCS-API)	LUCS Server 02	TCP	4444	LUCS Web API
Server	LUCS Server 01	TCP	19413	How How Luware-API connects to other Luware components through WCF channel

Also see

Installation

When installing the API as individual setup (e.g. on a Client PC), the port and server instance can be individually configured during setup.

For an external use of the API, consider that outgoing ports need to be forwarded as well.

API Setup Port configuration

Authorization Configuration / API Key

Luware API is an active – active component and may be installed on any machine that has IIS configured. To allow access the API you need to generate unique API tokens from within WebConfigurator.

Open Settings -> Topology -> Authentication Tokens
Click "Add" and name / describe your token as needed

API Key configuration
Optionally you can set an expiry date for the token.
The API should now be ready to use. Check in "Home" Tab if the API service is running.
If malfunctions occur after setting changes (e.g. in the API Component, Ports or IIS) a quick restart of API Services is recommended.

API Rate limits

By default an API key can be used without rate limits. If your LUCS API is extensively used (maybe imposing huge load on your servers) you might configure optional burst and rate limits in a defined time period.

Examples :

Rate Limit (x per minute/hour): If a customer makes 1000 calls, they cannot complete any more calls until the hour has expired.
Burst Limit (y per second): A rate limit that is applied over a small time period (second). Once that pause is over, calls continue to be accepted, e.g. until the rate limit is reached.

Use Case: Configuring a burst limit prevents usage spikes and ensures that the rate limit is evenly spread across its overall time period. For example, you might want to permit a total of 1000 calls per hour (rate limit) and a maximum spike of 50 calls per second (burst limit).

What are the effects? Users of that API key will see a "Too many requests" return code until the rate / burst time period has passed.

Note: Rejections by rate limits are not queued by the API nor stored by LUCS for later processing. They must be handled / repeated by the system that makes the request.

API Roles

Starting with LUCS 3.3 it's now possible to limit single API key access only certain areas via role assignment.

Precondition

You need System Administrator or at least the "Topology" Permission given to your account via Role Based Access - RBAC to use this feature. Otherwise you will only be able to inspect API keys or not see the entry at all.

After generating a new API key entry you now have access to the roles tab:

API Roles tab

API Methods / Roles

POST / GET / DELETE methods are limited by API Roles (see above). An "unauthorized" error 401 is thrown when the API key is wrong or role permissions are insufficient.

Area	Description	Roles with Access	API methods V1.0	API methods V2.0
Callbacks	Allows to get or manage Outbound / Callback Task Configuration tasks. The Callback tasks get shown in: Dashboard Supervision Widgets Frontend Callback Tasks Widget	TasksManage	POST /v1.0/callbacks - Creates a new callback request GET /v1.0/callbacks/{callbacksIdentifier} - Get callback using callbackId or using ExternalTaskId that provided on creation request POST /v1.0/callbacks/{callbacksIdentifier}/cancel - Cancel the Callback using callbackId or ExternalTaskId POST /v1.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria. Post the empty object "{}" to get all of them.	POST /v2.0/callbacks - Creates a new callback request GET /v2.0/callbacks/{callbacksIdentifier} - Get callback using callbackId or using ExternalTaskId that provided on creation request POST /v2.0/callbacks/{callbacksIdentifier}/cancel - Cancel the Callback using callbackId or ExternalTaskId POST /v2.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria. Post the empty object "{}" to get all of them.
Organization Unit	Allows only Organization Units to be read via the API (GET)	OU Readonly	GET/v1.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit GET/v1.0/organizationunits - Get all OrganizationUnits in the system. Flat structure with ParentId, if defined. Services	GET /v2.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit GET /v2.0/organizationunits - Get all OrganizationUnits in the system. Flat structure with ParentId, if defined.
Services	Allows Service details to be read via the API (GET)	ServiceReadonly	GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or SIP URI GET/v1.0/organizationunits/{ouIdentifier}/services - Search services in a specific OrganizationUnit. Search from the Top Unit, defined by ouIdentifier and down through its tree (in all child units). GET/v1.0/services/count - Retrieve overall count of Services in the system. GET/v1.0/users/{userIdentifier}/services/conversationas - Get per user the available conversation as services. GET/v1.0/services/{serviceIdentifier}/context - Get list the configured context information for a service	GET /v2.0/services/{serviceIdentifier} - Get particular service by its identifier or SIP URI GET /v2.0/services/count - Retrieve overall count of Services in the system. GET /v2.0/services/{serviceIdentifier}/context - Get list the configured context information for a service GET /v2.0/services - Get all the existing Services/ContactObjects in the system. Returns data by pages. GET /v2.0/users/{userIdentifier}/services/conversationas - Get per user the available conversation as services. Returns data by pages. GET /v2.0/organizationunits/{ouIdentifier}/services - Search services in a specific OrganizationUnit. Search from the Top Unit, defined by ouIdentifier and down through its tree (in all child units). Returns data by pages. GET /v2.0/services/{serviceIdentifier}/distributionPolicy - Get service distribution policy information
Tasks	Allows to fully manage and manipulate tasks in the system. (GET, POST)	TasksReadonly TasksManage	GET/v1.0/tasks/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier. GET/v1.0/services/{serviceIdentifier}/tasks - Retrieves a list of tasks for the specified service GET/v1.0/services/{serviceIdentifier}/longestwaitingtask - Retrieves a longest-waiting task for the specified service POST /v1.0/tasks - Create new task in the system. ReservedUserObject in response is always null. POST /v1.0/tasks/{taskIdentifier}/setestablished - Notify LUCS system that external task is established. Applicable only for the external tasks. POST /v1.0/tasks/{taskIdentifier}/refresh - Reset task to pending and trigger the process to search for agent again. Applicable only for external tasks. Can not be called for tasks if: - task distributed to agent - agent is connected POST /v1.0/tasks/outboundCall/start - Start Outbound Call. GET/v1.0/users/{userIdentifier}/tasks POST /v1.0/tasks/{taskIdentifier}/transfer - Transfer the task. Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/hold - Put existing task on Hold. Returns TaskStatusData object. POST /v1.0/tasks/{taskIdentifier}/resume - Resume task from Hold state. Returns TaskStatusData object. POST /v1.0/tasks/{taskIdentifier}/terminate - Terminate the task.	GET /v2.0/tasks/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier. GET /v2.0/services/{serviceIdentifier}/longestwaitingtask - Retrieves a longest-waiting task for the specified service POST /v2.0/tasks - Create new task in the system. ReservedUserObject in response is always null. POST /v2.0/tasks/{taskIdentifier}/setestablished - Notify LUCS system that external task is established. Applicable only for the external tasks. POST /v2.0/tasks/{taskIdentifier}/refresh - Reset task to pending and trigger the process to search for agent again. Applicable only for external tasks. Can not be called for tasks if: - task distributed to agent - agent is connected POST /v2.0/tasks/outboundCall/start - Start Outbound Call. GET /v2.0/services/{serviceIdentifier}/tasks - Retrieves a list of tasks for the specified service Returns data by pages. POST /v2.0/users/{userIdentifier}/addBlockTask - Adds a "fake" task to the user to block him from other work. Use this method, if the user should be blocked for other work but be reported as "working". User will be blocked until this fake task is removed via API. GET /v2.0/users/{userIdentifier}/tasks POST /v2.0/tasks/{taskIdentifier}/transfer - Transfer the task. Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/hold - Put existing task on Hold. Returns TaskStatusData object. POST /v2.0/tasks/{taskIdentifier}/resume - Resume task from Hold state. Returns TaskStatusData object. POST /v2.0/tasks/{taskIdentifier}/terminate - Terminate the task.
Tasks: Consultative Calls	Manage consultative calls (GET, POST)	TaskReadonly TasksManage	POST /v1.0/tasks/{taskIdentifier}/consultationCall - Make a new consult call Applicable only for the incoming call tasks. GET/v1.0/tasks/{taskIdentifier}/consultationCall - Get consultation call status POST /v1.0/tasks/{taskIdentifier}/consultationCall/merge - Merge the consultation call with the customer Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/consultationCall/transfer - Transfer the consultation call with the customer Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/consultationCall/terminate - Terminate consultation call POST /v1.0/tasks/{taskIdentifier}/consultationCall/leave - Terminate consultation call POST /v1.0/tasks/{taskIdentifier}/consultationCall/audioRoutes - Set audio routes for merged consultation call Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/consultationCall/terminateCustomerCall - Terminate customer call during the consultation call Applicable only for the incoming call tasks. GET/v1.0/users/{userIdentifier}/consultativeCalls - Get user's' consultative calls	POST /v2.0/tasks/{taskIdentifier}/consultationCall - Make a new consult call Applicable only for the incoming call tasks. GET /v2.0/tasks/{taskIdentifier}/consultationCall - Get consultation call status POST /v2.0/tasks/{taskIdentifier}/consultationCall/merge - Merge the consultation call with the customer Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/consultationCall/transfer - Transfer the consultation call with the customer Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/consultationCall/terminate - Terminate consultation call POST /v2.0/tasks/{taskIdentifier}/consultationCall/leave - Terminate consultation call POST /v2.0/tasks/{taskIdentifier}/consultationCall/audioRoutes - Set audio routes for merged consultation call Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/consultationCall/terminateCustomerCall - Terminate customer call during the consultation call Applicable only for the incoming call tasks. GET /v2.0/users/{userIdentifier}/consultativeCalls - Get user's' consultative calls
User Provisioning	Allows access to user provisioning (GET, POST, DELETE)	UserReadonly UserProvision	GET/v1.0/users/{userIdentifier}/roles - Get user's roles via user identifier (case insensitive). POST /v1.0/users/{userIdentifier}/roles - Set/Remove user's roles via user identifier (case insensitive). GET/v1.0/users/{userIdentifier} - Get a particular user via identifier (case insensitive). DELETE /v1.0/users/{userIdentifier} Remove existing user by userIdentifier GET/v1.0/users - Get all users in the system. POST /v1.0/users - Create new User in the system. GET/v1.0/services/{serviceIdentifier}/users - Get existing users for the specified service. GET/v1.0/organizationunits/{ouIdentifier}/users - Get users from the particular Organization Unit. POST /v1.0/users/{userIdentifier}/update - Update User in the system. POST /v1.0/users/{userIdentifier}/copy - Create new user based on existing one.	GET /v2.0/users/{userIdentifier}/roles - Get user's roles via user identifier (case insensitive). POST /v2.0/users/{userIdentifier}/roles - Set/Remove user's roles via user identifier (case insensitive). GET /v2.0/profiles → Returns all configured responsibility profiles (ID, Name, OffDuty-Flag) GET /v2.0/users - Get all users in the system. Traits and Profiles fields are not returned by default. Use fieldsToReturn to implicitly return them. Returns data by pages. POST /v2.0/users - Create new User in the system. GET /v2.0/users/{userIdentifier} - Get a particular user via identifier (case insensitive). Traits and Profiles fields are not returned by default. Use fieldsToReturn to implicitly return them. DELETE /v2.0/users/{userIdentifier} Remove existing user by userIdentifier GET /v2.0/organizationunits/{ouIdentifier}/users - Get users from the particular Organization Unit. Traits and Profiles fields are not returned by default. Use fieldsToReturn to implicitly return them. Returns data by pages. GET /v2.0/services/{serviceIdentifier}/users - Get existing users for the specified service. Returns data by pages. POST /v2.0/users/{userIdentifier}/update - Update User in the system. POST /v2.0/users/{userIdentifier}/copy - Create new user based on existing one. POST /v2.0/users/{userIdentifier}/applytemplate/{templateUserIdentifier} - Copy fields, provided by "fieldsToUpdate" from the template user identified by "templateUserId" into User, identified by "userIdentifier".
Users: Presence / Block	Allows to manage user presence, block / unblock from task distribution (GET, POST)	UserControl	POST /v1.0/users/{userIdentifier}/block - Block the defined agent. So, agent won't be selectable for the tasks assignment until someone call Unblock or system (AM) restarted. POST /v1.0/users/{userIdentifier}/unblock - Unblock a previously blocked agent. Unblocked agent can participate in a tasks assignment process. POST /v1.0/users/{userIdentifier}/applytemplate/{templateUserIdentifier} - Copy fields, provided by "fieldsToUpdate" from the template user identified by "templateUserId" into User, identified by "userIdentifier". POST /v1.0/users/{userIdentifier}/setpresence - Sets the particular presence for the specified Agent (so, external system can maintain presence state of the LUCS agents).	GET /v2.0/usersStates - Get states of all users in the system. Returns data by pages. GET /v2.0/usersStates/{userIdentifier} - Get a particular user state via identifier (case insensitive). GET /v2.0/organizationunits/{ouIdentifier}/usersStates - Get states of users from the particular Organization Unit. Returns data by pages. GET /v2.0/services/{serviceIdentifier}/usersStates - Get states of users for the specified service. Returns data by pages. Differences between "users" and "userstates" methods The "Users" V1.0 methods returns users based on their overall configuration. This also includes offline and Off-duty profile users. The "UserStates" V2.0 method additionally takes the current system configuration into consideration, listing only users that are available and selectable according to the first, secondary, etc.. duty profiles defined in the services Distribution Policy. POST /v2.0/users/{userIdentifier}/setpresence - Sets the particular presence for the specified Agent (so, external system can maintain presence state of the LUCS agents). POST /v2.0/users/{userIdentifier}/setActiveProfile → Removes "Absent" state from user. User will once again participate normally in task assignment process. POST /v2.0/users/{userIdentifier}/setConversationAsService → Removes "Absent" state from user. User will once again participate normally in task assignment process.
Users: Absence	Allows to set or retrieve special "Absence" type Not Ready Reasons (NRR).	UserControl	Not available in API V1.0	GET /v2.0/users/{userIdentifier}/getAbsentReasons - Get all available absence reasons for agent POST /v2.0/users/{userIdentifier}/setAbsent - Blocks user from work. Reports user as "NotReady"/absent with provided NotReadyReason, which means, he's considered not "working". This state persist until either it is removed via API, the user ends the "Absent" period through Agent Assistant or AM is restarted. POST /v2.0/users/{userIdentifier}/unsetAbsent - Removes "Absent" state from user. User will once again participate normally in task assignment process. Agent Self-Block via NRR This method only works with Stratus Agent Assistant in conjunction with MS Teams.

Notes

For a full list on API command functionality regarding Tasks, Callbacks, OU, Services and User management, refer to our → API Swagger documentation (see below)
Existing API-Keys from previous LUCS installations will be given full access by default to avoid access conflicts. You can edit them to narrow down the permissions to the needed amount.
Task Expiry: The API - Advanced Programming Interface has a setting "MaximumPollingTimeoutInMin". If no polling happened during this timeframe the task gets disposed, because it seems "abandoned").
Overall maximum lifetime for a task is 5 days. If you want to keep it in the system you need to make a refresh request via API to let the system know you still "care" about this task.

API Usage / Endpoints / Swagger

The following content below is embedded from our Live-API documentation (Swagger UI). It is not connected to a host for command execution and only acts as reference. Alternatively you can use these links to open the Swagger viewer directly V1.0 | V2.0 .

The URL for API access depends on your server address. Refer to Essential Topology Settings to determine where your API component was installed.

Note : LUCS uses the same API as our Stratus Cloud products, so mentions of either name are to be expected.

API related errors

The API returns default → HTML Error status codes. The most common one is not passing the api_key along with a request:

During all HTTP Requests the generated API Key has to be included in the HTTP Header. Otherwise an error will be thrown:

"Error" : { "Code" : "Unauthorized" , "Message" : "Header 'api_key' not found." }

The info below is left as legacy API documentation content. Newest API definitions can be found in our Swagger UI documentation above.

In this section: