Client Requests

Cisco Finesse Release 12.5(1) or higher supports only secure HTTP (HTTPS) requests from clients. Cisco Finesse desktop operations can be performed using the available REST HTTPS request described in this guide.

Operations on specific objects are performed using the ID of the object in the REST URL. For example, the URL to view a single object (HTTPs) would be:

The URL to view a single object (HTTPS) would be: 


https://<FQDN>:<port>/finesse/api/<object>/<objectID>

FQDN is the fully-qualified domain name of the Finesse server.

Finesse configuration APIs require the application user ID and password, which is established during installation, for authentication purposes.

Finesse APIs use the following HTTP methods to make requests:

  • GET: Retrieve a single object or list of objects (for example, a single user or list of users).

  • PUT: Replace a value in an object (for example, to change the state of a user from NOT_READY to READY).

  • POST: Create a new entry in a collection (for example, to create a new reason code or wrap-up reason).

  • DELETE: Remove an entry from a collection (for example, to delete a reason code or wrap-up reason).

Finesse uses the standard HTTP status codes (for example, 200, 400, and 500) in the response. These status codes indicate overall success or failure of the request.

If an API operation fails, a detailed error is returned in the HTTP response message body. The error, in XML format, appears as follows: 


<ApiErrors>
   <ApiError>
       <ErrorType>type</ErrorType>
       <ErrorMessage>message</ErrorMessage>
       <ErrorData>data</ErrorData>
   </ApiError>
</ApiErrors>

Finesse has a Dependency Manager that collects the state of internal dependencies for Finesse (such as the state of the Cisco Finesse Notification Service) and reports these states to external entities.

If any of these dependencies are down, Finesse is out of service. If the Cisco Finesse Tomcat is running, Finesse rejects any API requests and returns an HTTP 503 error. The error appears as follows: 


<ApiErrors>
  <ApiError>
    <ErrorType>Service Unavailable</ErrorType>
    <ErrorData></ErrorData>
    <ErrorMessage>SERVER_OUT_OF_SERVICE</ErrorMessage>
  </ApiError>
</ApiErrors>

If the Cisco Finesse Tomcat service is not running, Finesse returns a Connection Timeout error.

All Finesse APIs use HTTP BASIC authentication, which requires the credentials to be sent in the "Authorization" header. The credentials contain the username and password, separated by a single colon (:), within a BASE64-encoded string. For example, the Authorization header would contain the following string: 


"Basic YWdlbnRiYXJ0b3dza2k6Y2FybWljaGFlbA=="

where "YWdlbnRiYXJ0b3dza2k6Y2FybWljaGFlbA==" is the Base64-encoded string of "agentbartowski:carmichael" (agentbartowski being the username and carmichael being the password).

In case of Single Sign-On mode, the Authorization header would contain the following string:
Bearer <authtoken>

where the authtoken has to be fetched from IDS through the ADFS server.

If an administrator changes the password for an agent or supervisor on the secondary Administration & Data server (if configured) while the primary distributor process on Unified CCE is down, the agent or supervisor can still use the old password and access all REST APIs except the sign-in request. To ensure this does not happen, the primary distributor must be up and running when the administrator changes the password.