This section is for System Administrators and Developers of 3rd party products using Stratus Agent functionality externally .

The API allows to manipulate multiple data entities simultaneously, allowing task automation and external UI interaction with Stratus Agent.

If you are in need of additional support or further applications using the API don’t hesitate to contact us.

(info) Also look at our existing solutions which already make direct use of the API

Scope

In the following we provide a description about the data models and functions used within Stratus Agent and in automated interaction with other applications.

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

Authorization Configuration / API Key

(lightbulb) To allow access the API we generate unique API tokens from within WebConfigurator for you. 

(lightbulb) It's possible to limit single API key access only certain areas via role assignment → See next chapter.

API Roles

Precondition

A Luware System Administrator will generate a key for you and make it accessible to your Organization Units.

After getting an API key you now have access to the roles tab:

API Roles tab

API Role Details

RoleDescriptionAPI commands that can be executed
TasksManageAllows to fully manage and manipulate tasks in the system.  (GET, POST)

Manage Callbacks
POST /v1.0/callbacks - Creates a new callback request
GET /v1.0/callbacks - Get callback using the ExternalTaskId that provided on creation request.
GET /v1.0/callbacks/{id} - Get callback using callbackId
POST /v1.0/callbacks/{id}/cancel - Cancel the Callback, identified by a CallbackId.
POST /v1.0/callbacks/cancel - Cancel the Callback, identified by an ExternalTaskId.
POST /v1.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria.

Manage Tasks
GET ​/v1.0​/tasks​/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier.
GET​/v1.0​/services​/{service}​/tasks - Retrieves a list of tasks for the particular service (identified by ServiceId or Service SipUri)
GET​/v1.0​/services​/{service}​/longestwaitingtask - Retrieves a longest waiting task for the particular service
POST​/v1.0​/tasks - Create new task in the system.
POST​/v1.0​/tasks​/{taskIdentifier}​/setestablished - Notify Stratus Agent system that the external task is established.
POST​/v1.0​/tasks​/{taskIdentifier}​/terminate - Remove the task. Applicable only for the external tasks.
POST​/v1.0​/tasks​/{taskIdentifier}​/refresh - Reset an external task to pending and trigger the process to search for agent again.
POST /v1.0/tasks/outboundCall/start - Starts an outbound call
GET​/v1.0​/users​/{userIdentifier}​/tasks - Retrieves a list of tasks for the particular user (identified by userIdentifier)
POST​/v1.0​/tasks​/{taskIdentifier}​/transfer - Transfer the task. Applicable only for the incoming call tasks.

Read Users
GET​/v1.0​/services​/{serviceId}​/users - Get existing users for the specified service.
GET​/v1.0​/users - Get All users in the system.
GET​/v1.0​/users​/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive).

Read Services
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 sipUri
GET​/v1.0​/services​/count - Retrieve overall count of Services in the system.

TasksReadonlyAllows only tasks details to be read via the API (GET)

Read Callbacks
GET /v1.0/callbacks - Get callback using the ExternalTaskId that provided on creation request.
GET /v1.0/callbacks/{id} - Get callback using callbackId
POST /v1.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria.

Read Tasks
GET ​/v1.0​/tasks​/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier.
GET​/v1.0​/services​/{service}​/tasks - Retrieves a list of tasks for the particular service (identified by ServiceId or Service SipUri)
GET​/v1.0​/services​/{service}​/longestwaitingtask - Retrieves a longest waiting task for the particular service
GET​/v1.0​/users​/{userIdentifier}​/tasks Retrieves a list of tasks for the particular user (identified by userIdentifier)

Read Users
GET​/v1.0​/services​/{serviceId}​/users - Get existing users for the specified service.
GET​/v1.0​/users - Get All users in the system.
GET​/v1.0​/users​/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive).

Read Services
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 sipUri.
GET​/v1.0​/services​/count - Retrieve overall count of Services in the system.

ServicesReadonlyAllows only Service details to be read via the API (GET)

Read Services
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 sipUri.
GET​/v1.0​/organizationunits​/{ouIdentifier}​/services - Search services in a specific OrganizationUnit. 
GET​/v1.0​/services​/count - Retrieve overall count of Services in the system.

Read OrganizationUnits
GET​/v1.0​/organizationunits​/{ouIdentifier} - Get details of the particular OrganizationUnit.
GET​/v1.0​/organizationunits - Get All the OrganizationUnits in the system.

OU ReadonlyAllows only Organization Units to be read via the API (GET)Read OrganizationUnits
GET​/v1.0​/organizationunits​/{ouIdentifier} - Get details of the particular OrganizationUnit.
GET​/v1.0​/organizationunits - Get All the OrganizationUnits in the system.
UsersProvisionAllows full access to user provisioning (GET, POST, DELETE)

Manage Users
GET​/v1.0​/services​/{serviceId}​/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 - Create new User in the system.
GET​/v1.0​/users - Get All users in the system.
POST​/v1.0​/users​/{userIdentifier}​/copy - Create new user based on existing one.
DELETE​/v1.0​/users​/{userIdentifier} - Remove existing user by userIdentifier
GET​/v1.0​/users​/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive).
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} - Update existing user configurations by providing updated paramaters through the API.

Read Services
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 sipUri.
GET​/v1.0​/organizationunits​/{ouIdentifier}​/services - Search services in a specific OrganizationUnit. 
GET​/v1.0​/services​/count - Retrieve overall count of Services in the system.

Read OrganizationUnits
GET​/v1.0​/organizationunits​/{ouIdentifier} - Get details of the particular OrganizationUnit.
GET​/v1.0​/organizationunits - Get All the OrganizationUnits in the system.

UsersControlAllows to manage user presence, block / unblock from task distribution (GET, POST) Control Users
GET​/v1.0​/users - Get All users in the system.
GET​/v1.0​/users​/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive).
POST​/v1.0​/users​/{userIdentifier}​/block - Block a defined agent (agent won't be selectable for tasks anymore).
POST​/v1.0​/users​/{userIdentifier}​/unblock - Unblock the agent.
POST​/v1.0​/users​/{userIdentifier}​/setpresence - Sets particular presence for an agent.
UsersReadonlyAllows only to retrieve user details (GET)

Read Users
GET​/v1.0​/services​/{serviceId}​/users - Get existing users for the specified service.
GET​/v1.0​/organizationunits​/{ouIdentifier}​/users - Get users from the particular Organization Unit.
GET​/v1.0​/users - Get All users in the system.
GET​/v1.0​/users​/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive).

Read Services
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 sipUri.
GET​/v1.0​/organizationunits​/{ouIdentifier}​/services - Search services in a specific OrganizationUnit. 
GET​/v1.0​/services​/count - Retrieve overall count of Services in the system.

Read OrganizationUnits
GET​/v1.0​/organizationunits​/{ouIdentifier} - Get details of the particular OrganizationUnit.
GET​/v1.0​/organizationunits - Get All the OrganizationUnits in the system.

  • 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 Stratus Agent 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.

API usage / API Endpoints

(tick) To get access to the Luware API URL, please get in contact with support

The following content is embedded from our Live-API documentation (Swagger UI). You can also open this window directly

(lightbulb) Note: Stratus Agent uses the same API as our LUCS product, so mentions 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."
  }