Jump to: navigation, search

Universal Contact Server API Reference Guide

This is the UCS 9.1 API Reference Guide.

It details, within the same topic:

  • RESTful services and methods, which can be accessed by clients directly.
  • ESP services and methods, which are accessed via Genesys PSDK.


HTTP Requests

An HTTP request needs the following elements:

  • An HTTP verb (or method).
  • A header
  • A URI (Uniform Resource Identifier) which identifies the resource upon which to apply the request
  • An optional message body

HTTP Responses

  • Responses contain a list of '<key>:<value>' entries in JSON format.
  • In the ESP protocol some UCS functions return some <key>:<value> entries in parameters and some others in user data. When used through HTTP those functions return all <key>:<value> entries in a unique JSON document.

The functions that behave this way are:

  • Callback.Create
  • Chat.Create
  • Contact.findOrCreate
  • Contact.Identify
  • OMFieldCodes.RenderMessageContent


In UCS the following methods are used: POST, PUT, GET and DELETE.

The general rule is:

  • POST when method creates a new object
  • PUT when the method updates an object
  • GET when the method reads object content
  • DELETE when the method deletes an object

URI Form

The URI is built as follows:

  • POST and PUT methods:
<http|https>://<ucs host>:<port http or https>/<optional base url>/ucs/v1/<ucs service>/<ucs method>
  • GET and DELETE methods:
<http|https>://<ucs host>:<port http or https>/<optional base url>/ucs/v1/<ucs service>/<ucs method>?<key1>=<value1>&<key2>=<value2>...

The optional base URL corresponds to the value of the option base-url in the http section.

Syntax for POST and PUT

Syntax when using the verbs POST and PUT:

<verb> http://<host>:<port>/<base url>/ucs/v1/<service>/<method>
   "Parameters": {
              "key1": value1,
              "key2": value2
   "UserData": {   
              "key3": value3, 
              "key4": value4,


  • <verb> depends on the type of operation
  • <service> is UCS's service name
  • <method> is UCS's method name
  • "Parameters" contains a JSON document with parameters
  • "UserData" contains a JSON document with user data (not used by PSDK but used by ChatServer, URS and IXNServer.)


  • Key-value pairs are separated with comma.
  • Each key is surrounded with "
  • Values of type string are surrounded with "
  • Values of type integer are not surrounded with "

A value of type binary must be base64 encoded and provided with a key named ‘binary’. Here is an example using InsertInteraction with a binary content:

POST http://<host>:<port>/<base url>/ucs/v1/OMInteractions/InsertInteraction

Syntax for GET and DELETE

Syntax when using verb GET and DELETE:

<verb> http://<host>:<port>/<base url>/ucs/v1/<service>/<method>?<key1>=<value1>&<key2>=<value2>...

In this case the request does not have a body, all parameters are provided in the URL. The parameters come after the character '?'. They are key-value pairs separated with character '&'. The syntax for each parameter is <key>=<value> except for the following:

  • ESQuery (in GetInteractions, InteractionListGet and ContactListGet) must be JSON-formatted. It should contain an Elasticsearch 5.5-compliant request (documentation is at https://www.elastic.co/guide/en/elasticsearch/reference/5.5/query-dsl.html).
  • OwnerIds in requests GetCategorizedInteraction and GetUnCategorizedInteraction must be JSON- formatted and the character ':' must be used instead of '='.
  • AttributeList (in InteractionListGet or ContactListGet) must be provided as a JSON array—for example:AttributeList={"AttrName":["Subject","Id"]}
  • SearchCriteria (in InteractionListGet or ContactListGet) must be provided as a JSON object—for example: SearchCriteria={"EQUAL":{"AttrName":"CreatorAppId","AttrValue":169}}
  • SortCriteria (in InteractionListGet or ContactListGet) must be provided as a JSON object—for example: SortCriteria={"StartDate":"ASC"}
This page was last modified on May 18, 2018, at 08:04.


Comment on this article:

blog comments powered by Disqus