REST API

UCS provides a backend REST API through the ucs-api service, with routing handled by NGINX. OAuth login through an existing user account is required for access (the user must belong to a role with superuser permissions and must not be public). For testing, OAuth can be disabled in the /etc/ucs.api.conf file, in the [oauth] section, by setting enabled = 0.

Communication Protocol

Calls made to the UCS REST API use the following parameters:

Transfer Protocol: HTTPS
Security: OAuth 2.0 (client_credentials, access token)
Interface Architecture: REST
Data Format: JSON
Encoding: UTF-8
URL: https://ucs.example.com/api/v1.0

Successful calls and expected errors are confirmed with an HTTP status 2XX. Exceptions:

OAuth returns HTTP status 400 for a bad request or 401 for incorrect credentials
Unexpected exceptions (UCS-side exceptions) return HTTP status 500

POST /login/oauth2/token

A B2B OAuth token is required for calling API methods. The method for obtaining a token requires client_id, client_secret, and grant_type as payload. The response will return an access token, valid for 1 hour (or as set in /etc/ucs.api.conf, in the [oauth] section, with the parameter expires = 3600).

Example of obtaining an OAuth token

Request

POST https://ucs.example.com/login/oauth2/token

Content-Type: application/json

{
  "client_id": "service_account_username_in_ucs",
  "client_secret": "service_account_password_in_ucs",
  "grant_type": "client_credentials"
}

Response

200 OK

Content-Type: application/json

{
  "access_token": "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz",
  "token_type": "Bearer",
  "expires_in": "3610"
}

Following REST API endpoints require an Authorization header with a valid access token.

Example of calling a method with the obtained access token

Request

GET https://ucs.example.com/api/v1.0/status

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

If the attempt to obtain an OAuth token fails, an HTTP status of 400 or 401 is returned.

Example of an unsuccessful attempt to obtain an access token

Response to a bad request

400 Bad Request

Content-Type: application/json

{
  "error": "invalid_request",
  "error_description": "We support only \"client_credentials\" grant type",
  "error_uri": "https://www.oauth.com/oauth2-servers/access-tokens"
}

Response to an invalid credentials

401 Unauthorized

Content-Type: application/json

{
  "error": "invalid_client",
  "error_description": "Invalid username or password",
  "error_uri": "https://www.oauth.com/oauth2-servers/access-tokens"
}

Status and Enumerations

The following methods provide the current status of UCS and enumerations for obtaining internal object IDs in UCS, which are required as attributes for other methods.

Status

GET /api/v1.0/status

Status of the UCS system, SIP trunks, and phones.

Example of obtaining the UCS system status

Request

GET https://ucs.example.com/api/v1.0/status

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "trunks": {
    "1": {
      "name": "SIPY",
      "status": 1,
      "rtt": 1
    },
    "2": {
      "name": "external",
      "status": 0,
      "rtt": 0
    }
  },
  "phones": {
    "1": {
      "name": "System",
      "configured": 279,
      "configured_ipphones": 16,
      "configured_softphones": 263,
      "available": 0,
      "available_ipphones": 0,
      "available_softphones": 0,
      "dead": 11,
      "dead_ipphones": 2,
      "dead_softphones": 9,
      "paired": 11,
      "paired_ipphones": 2,
      "paired_softphones": 9
    },
    "3": {
      "name": "Testik",
      "configured": 2,
      "configured_ipphones": 1,
      "configured_softphones": 1,
      "available": 0,
      "available_ipphones": 0,
      "available_softphones": 0,
      "dead": 0,
      "dead_ipphones": 0,
      "dead_softphones": 0,
      "paired": 0,
      "paired_ipphones": 0,
      "paired_softphones": 0
    }
  },
  "ucs": 0,
  "api": 0,
  "postgres": 14,
  "asterisk": 1,
  "light-log": 0,
  "tftp": 1,
  "stunserver": 1,
  "webserver": 3,
  "nats-server": 1
}

Queues

GET /api/v1.0/queues

A list of configured queues (both inbound and outbound campaigns) and their current status. The method does not accept any parameters. The response is an array of associative arrays.

Example of obtaining a queue overview

Request

GET https://ucs.example.com/api/v1.0/queues

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 74,
      "active": true,
      "group_id": 11,
      "type": 1,
      "number": "10099",
      "name": "NONLIFE CZ",
      "callers_waiting": 0,
      "callers_ringing": 0,
      "callers_talking": 0,
      "agents_idle": 0,
      "agents_ringing": 0,
      "agents_talking": 0,
      "agents_acw": 0,
      "agents_aux": 0,
      "answered": 1567,
      "overflowed": 1,
      "abandoned": 336,
      "talktime": 314549,
      "waittime": 270986,
      "answered_wait_time": 227409.22137379646,
      "answered_in_service": 740,
      "answered_in_work_hours": 0,
      "answered_in_work_and_sl": 0,
      "abandoned_in_threshold": 140,
      "abandoned_in_work_hours": 0,
      "abandoned_in_work_and_sl": 0,
      "abandoned_full": 0,
      "sl": {
        "day": [
          740,
          1763
        ],
        "week": [
          4184,
          9405
        ],
        "month": [
          17929,
          28297
        ],
        "quarter": [
          44922,
          69392
        ]
      },
      "sl_work": {
        "day": [
          0,
          0
        ],
        "week": [
          0,
          0
        ],
        "month": [
          0,
          0
        ],
        "quarter": [
          0,
          0
        ]
      },
      "last_call_enter": 1724428798.475978,
      "last_call_answer": 1724428717.4761183,
      "callers": []
    },
    ...
  ]
}

Groups

GET /api/v1.0/groups

Skupiny v UCS slouží pro organizaci nastavení (odráží organizační strukturu společnosti) a řízení přístupu (na základě rolí). Většina objektů (uživatelé, telefony, fronty, atd.) má atribut group_id, který určuje do jaké skupiny daný objek patří. Pokud objekt nemá tento atribut, pak je pro jeho editaci vyžadováno superuser oprávnění. UCS garantuje, že vždy existuje skupina ID 1. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.

Příklad získání číselníku organizačních skupin UCS

Request

GET https://ucs.example.com/api/v1.0/groups

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "System",
      "external_id": null
    },
    {
      "id": 3,
      "name": "  Testik",
      "external_id": "1234"
    },
    {
      "id": 7,
      "name": "  Test2",
      "external_id": "2222"
    },
    {
      "id": 9,
      "name": "  NN - Brokerska",
      "external_id": "broker1"
    },
    {
      "id": 10,
      "name": "  Markuv Servicedesk",
      "external_id": "service1"
    }
  ]
}

Roles

GET /api/v1.0/roles

A role is a set of permissions that allows users to use UCS services (and possibly edit settings). A typical example of a role is e.g. Administrator, Regular User, Supervisor, Agent, etc. The method accepts no parameters. The answer is an array of associative arrays.

An example of obtaining a list of UCS user roles

Request

GET https://ucs.example.com/api/v1.0/roles

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "group_id": 1,
      "name": "Administrator"
    },
    {
      "id": 6,
      "group_id": 1,
      "name": "Alice"
    },
    {
      "id": 7,
      "group_id": 1,
      "name": "Bob"
    },
    {
      "id": 9,
      "group_id": 10,
      "name": "Bot"
    },
    {
      "id": 8,
      "group_id": 1,
      "name": "Charlie"
    }
  ]
}

Teams

GET /api/v1.0/teams

The team is a set of settings for the call center's properties, the colors of individual statuses and the reasons for non-distance are set here agents, default values for queue membership, etc. The method accepts no parameters. The answer is an array of associative arrays.

An example of obtaining a directory of UCS call center teams

Request

GET https://ucs.example.com/api/v1.0/teams

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 8,
      "group_id": 1,
      "name": "Markuv Team",
      "note": "Team TEAM TEAM!!!!",
      "aux_reasons": [
        {
          "reason": "Nemám rád šmouly",
          "break": false,
          "color": "ff0000",
          "limit": null,
          "hidden": false
        }
      ],
      "contacts": [],
      "tasks": {
        "person": 0,
        "person_url": null,
        "call": 0,
        "call_url": null,
        "email": 0,
        "email_url": null
      },
      "maximum_assigned_emails": null,
      "default_inbound_priority": 100,
      "default_inbound_acw": false,
      "default_inbound_acw_timeout": null,
      "default_inbound_busy": null,
      "default_inbound_busy_timeout": null,
      "default_outbound_acw": false,
      "default_outbound_acw_timeout": null,
      "default_email_priority": 100,
      "default_email_languages": {
        "cs_CZ": 100,
        "en_US": 100,
        "de_DE": 100,
        "ru_RU": 100
      },
      "default_email_assigned": null,
      "default_task_priority": 100,
      "color_agent_offline": null,
      "color_agent_ready": "188b35",
      "color_agent_acw": "ffda1f",
      "color_agent_aux": "ff9500",
      "color_agent_ringing": "a1ff2e",
      "color_agent_talking": "a1ff29",
      "color_phone_offline": null,
      "color_phone_idle": "00bfff",
      "color_phone_ringing": "ff00ea",
      "color_phone_talking": "ff00ea",
      "breaks_limit": null,
      "transfer_to_agent": false,
      "transfer_to_queue": false,
      "channels": {
        "inbound": false,
        "task": false,
        "email": false,
        "chat": false,
        "dialer": false
      }
    },
    ...
  ]
}

Calls

UCS provides CDR (Call Detail Records) of calls made. Each call has a string unique ID, which consists of the UNIX timestamp of the start of the call and the dot-separated number of the call from restarting the Asterisk component.

Call Information

GET /api/v1.0/call/{uniqueid}

The method makes it possible to retrieve all saved data about the call. The direction of the call is determined by a combination of attributes src_internal and dst_internal. Detailed information about how the call passed through the switchboard is recorded in the path attribute. If the call was transferred, then the dst_ attributes correspond to the destination number. Attention, if the caller transfers, then another CDR record is created for that call.

Example of obtaining information about a call (Call Detail Record)

Request

GET https://ucs.example.com/api/v1.0/call/1723018607.115

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "price": 0,
    "duration": 524,
    "src_number": "+420776000001",
    "src_name": "",
    "dst_number": "1800",
    "dst_name": " Bob",
    "src_internal": false,
    "dst_internal": true,
    "calldate": "2024-08-07 10:17:04",
    "connected": "2024-08-07 10:17:07",
    "disconnected": "2024-08-07 10:25:51",
    "src_extension_id": null,
    "dst_extension_id": 75,
    "src_user_id": null,
    "dst_user_id": 11,
    "src_type": "trunk",
    "dst_type": "phone",
    "xfer_users": null,
    "trunk_id": null,
    "uniqueid": "1723018607.115",
    "metadata": {
      "ucrm_interaction_id": 30391,
      "outbound_id": 0
    },
    "src_group_id": 1,
    "dst_group_id": 1,
    "pilot_number": "0776000001",
    "ring_time": 4,
    "talk_time": 524,
    "hold_time": 0,
    "cause": 3,
    "recording": true,
    "recording_duration": 523,
    "path": [
      {
        "date": "2024-08-07 10:16:47",
        "type": 1,
        "number": "0776000001",
        "name": "SIPY"
      },
      {
        "date": "2024-08-07 10:17:04",
        "type": 10000,
        "number": "1800",
        "name": "Bob SP"
      },
      {
        "date": "2024-08-07 10:17:04",
        "type": 10711,
        "number": "1800",
        "name": " Bob"
      },
      {
        "date": "2024-08-07 10:17:04",
        "type": 10001,
        "number": "1800",
        "name": "Bob SP"
      },
      {
        "date": "2024-08-07 10:17:07",
        "type": 10002,
        "number": "1800",
        "name": "Bob SP"
      },
      {
        "date": "2024-08-07 10:25:51",
        "type": 10720,
        "number": "0776000001",
        "name": ""
      },
      {
        "date": "2024-08-07 10:25:51",
        "type": 10,
        "number": "0776000001",
        "name": ""
      }
    ]
  }
}

Call Metadata Detail

The metadata attached to a call is an associative array of arbitrary keys and values. Metadata can be obtained for an active call even after it has ended.

GET /api/v1.0/metadata/{uniqueid}

An example of getting metadata for an active or completed call

Request

GET https://ucs.example.com/api/v1.0/metadata/1723018607.115

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "ucrm_interaction_id": 30391,
    "outbound_id": 0
  }
}

Call Metadata Update

The method allows differential update of call metadata. The passed keys are in the metadata of the call creates or overwrites. If the existing metadata key does not exist in the payload, then this key is left unchanged. To delete a key, its value is set to null. The method returns the result call metadata.

POST /api/v1.0/metadata/{uniqueid}

An example of updating the metadata of an active or completed call

Request

POST https://ucs.example.com/api/v1.0/metadata/1723018607.115

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "outbound_id": null,
  "pokus": "hokus"
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "ucrm_interaction_id": 30391,
    "pokus": "hokus"
  }
}

Shared Data

Data transmitted from other systems that are displayed on wallboards, or with which call routing, message playback, etc. are controlled.

Fetch Values

GET /api/v1.0/shared/{identificator}

Get the current shared data value of the given identifier.

Example of getting the current value of shared data

Request

GET https://ucs.example.com/api/v1.0/shared/osl_chats

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "type": "osl",
    "data": {
      "SWS": {
        "OneSolution": {
          "Waiting": 5,
          "Processed": 0
        }
      },
      "KPK": {
        "OneSolution": {
          "Waiting": 2,
          "Doing": 4
        }
      }
    }
  }
}

Update Values

POST /api/v1.0/shared/{identificator}

Override the shared data value of the given identifier.

Example of updating shared data

Request

POST https://ucs.example.com/api/v1.0/shared/osl_chats

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "type": "osl",
  "data": {
    "SWS": {
      "OneSolution": {
        "Waiting": 4,
        "Processed": 1
      }
    },
    "KPK": {
      "OneSolution": {
        "Waiting": 2,
        "Doing": 4
      }
    }
  }
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Users

Synchronization of user accounts.

Users List

GET /api/v1.0/users

Returns a list of users in UCS as an array of objects. The method has no parameters.

Example of getting all existing users in UCS

Request

GET https://ucs.example.com/api/v1.0/users

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {"id": 1, "name": "admin", "external_id": "asdf"},
    {"id": 10, "name": "Alice", "external_id": null},
    {"id": 11, "name": "Bob", "external_id": "2468"}
  ]
}

User Detail

GET /api/v1.0/user/{user_id}

nebo

GET /api/v1.0/user/external/{external_id}

The method returns the complete attribute structure of the user object User.

Example of getting all user account attributes

Request

GET https://ucs.example.com/api/v1.0/user/external/asdf

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "id": 1,
    "active": true,
    "external_id": "asdf",
    "group_id": 1,
    "role_id": 1,
    "team_id": null,
    "locale": "en_US",
    "username": "admin",
    "firstname": "null",
    "lastname": null,
    "displayname": "admin",
    ...
  }
}

User

Struktura objektu uživatele:

Key	Type	Note
id	int	unique user ID (primary key)
username	str	login name (case-insensitive)
password	str	password in plain text (it is hashed to the DB with the PBKDF2 algorithm)
locale	enum[str]	user interface language cs_CZ: Czech en_US: English sk_SK: Slovak
email	str	user's email address (can be used for login)
primary_extension	int	the ID of the user's primary line
pin	str	voicemail access code
firstname	str	user's first name
lastname	str	user's last name
public	bool	service accounts have this attribute set to false
group_id	int	ID of the UCS organizational group to which the user belongs
identificator	str	user identifier for the User Mobility feature
external_id	str	user identifier in the external IS (be careful, it is case-sensitive)
filter_id	int	Outgoing call filter ID for calls to an external number
number	str	external number to which the user is called in case of line unpairing
data	json	any user-bound metadata in associative array format
team_id	int	ID of the call center team to which the user belongs
active	bool	flag whether the user account is active
wssip_device_id	int	Softphone ID
certificate	bool	flag whether to create a client SSL certificate for the user
role_id	int	ID of the permission role to which the user belongs
channels	json	active channels for the Omnichannel feature
clid_number	str	the caller's phone number for external outgoing calls

User Create

POST /api/v1.0/user

Creates a user in UCS. Mandatory attributes are username and group_id (group ID 1 always exists in UCS). A user object User is passed as palyload in the request. The return value is the ID of the newly created user.

Example of creating a new user account

Request

POST https://ucs.example.com/api/v1.0/user

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "username": "test",
  "group_id": 1
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": 123
}

The internal UCS ID of the newly created account is 123.

User Update

PATCH /api/v1.0/user/{user_id}

PATCH /api/v1.0/user/external/{external_id}

Updates the attributes of the user object User. If the attribute is not in the payload specified, then its current value is retained.

Example of updating the attributes of an existing user account

Request

PATCH https://ucs.example.com/api/v1.0/user/123`

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "external_id": "T1000",
  "password": "1pokus+Hokus2",
  "team_id": 1,
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

In case of an incorrect value of any of the attributes, an associative field with the given attributes is returned.

PATCH https://ucs.example.com/api/v1.0/user/external/T1000`

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "external_id": "t123456",
  "number": "cislo",
  "filter_id": "PSTN",
}

Bad value in number and filter_id attribute. Incorrectly entered attributes will block the update, i.e. even if the external_id value is valid, it will not be overwritten.

200 OK

Content-Type: application/json

{
  "success": false,
  "data": {
    "number": "contain invalid character (invalid character \"c\")",
    "filter_id": "value must be integer number"
  }
}

User Delete

DELETE /api/v1.0/user/{user_id}

nebo

DELETE /api/v1.0/user/external/{external_id}

Deletes the user. The reference will be canceled in the call history, but the records incl. recordings will remain unaffected. Alternatively, to deactivate the user, the active attribute can be set to the value false, then the user remains in DB but can't login.

Příklad smazání uživatelského účtu

Request

DELETE https://ucs.example.com/api/v1.0/user/external/T1000

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Agent Queue Membership Detail

GET /api/v1.0/queues/agents

Overview of assignment of all agents to service contact center queues. The answer is an array of AgentQueues objects of individual users. Each user contains a queues attribute, which is an array of QueueMembership objects of individual queue membership.

Typy front UCS

Hodnota	Note
0	Outbound - outgoing call campaign
1	Inbound - incoming calls queue
2	Task - µCRM task queue
3	E-mail - incoming e-mail processing queue

Example of getting an overview of agent assignments

Request

GET https://ucs.example.com/api/v1.0/queues/agents

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Admin Ucska",
      "external_id": "asdf",
      "queues": [
        {
          "id": 146,
          "type": 3,
          "priority": 100,
          "suspended": false
        },
        {
          "id": 123,
          "type": 2,
          "priority": 80,
          "suspended": false
        },
        {
          "id": 82,
          "type": 1,
          "priority": 1,
          "suspended": true
        },
        {
          "id": 103,
          "type": 0,
          "priority": 100,
          "suspended": false
        }
      ]
    },
    {
      "id": 11,
      "name": "Bob",
      "external_id": "2468",
      "queues": [
        {
          "id": 234,
          "type": 0,
          "priority": 50,
          "suspended": false
        }
      ]
    },
    {
      "id": 43,
      "name": "Pokus Bezfrontovej",
      "external_id": "nonono",
      "queues": [ ]
    }
  ]
}

Agent Queue Membership Update

POST /api/v1.0/queues/agents

Bulk update the assignment of specified agents to service the contact center queues. The payload of the request contains an array of AgentQueues objects of the agents for which the queue membership is to be updated. If the user is not in the list, then its membership is not modified (it is not deleted from all queues). The user can be identified internally UCS ID (id attribute) or an external ID from another information system (external_id attribute). If they are given both attributes, then the id attribute is used and the external_id attribute is ignored.

Membership is set by the queues attribute, which is an array of QueueMembership objects of all queues, which the agent serves. If no parameters of the agent's membership in the queue are to be modified, then the field is sufficient in the queues attribute, pass an associative field containing only the id of the given queue. To update, just fill out the form attributes to be changed or the existing values can be left and the update is skipped (no UCS is loaded). To delete membership from a queue, the queue is dropped from the field in the queues attribute of the given user.

If the payload is valid, then the success attribute of the return value is set to true and the data attribute is the results of updating individual users (including the success attribute) and in each user object in the queues attribute the results of updating its membership in individual queues (again including the success attribute).

AgentQueues

Agent object structure:

Key	Type	Note
id	int	unique user ID (primary key)
external_id	str	user identifier in the external IS
queues	array	agent queue membership field (QueueMembership object)

QueueMembership

The structure of the queue agent membership object:

Key	Type	Note
id	int	UCS queue ID
priority	int	priority of handling interactions in the queue (1 lowest, 100 highest)
suspended	bool	when set to false, processing of interactions in the queue is suspended

Example of updating agent membership in queues

Request

For the user admin (ID 1) it will be:
mail queue (ID 146) left unchanged
the bag queue (ID 123) is also left unchanged
service of the incoming call queue (ID 82) has been restored
removed from outbound call campaign handling (103)
User Bob will not be updated (will remain a member of outgoing campaign ID 234)
User Pokus Bezquetova (external identifier 2468) will:
added to incoming call queue handling (ID 82)
accidentally added to a non-existent queue
Attempt to update non-existent user (ID 0)
Attempt to update non-existent user (external identifier does not exist)

POST https://ucs.example.com/api/v1.0/queues/agents

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

[
  {
    "id": 1,
    "queues": [
      {"id": 146},
      {"id": 123, "priority": 80, "suspended": false},
      {"id": 82, "suspended": false}
    ]
  },
  {
    "external_id": "2468",
    "queues": [
      {"id": 82},
      {"id": 0}
    ]
  },
  {
    "id": 0,
    "queues": [ ]
  },
  {
    "external_id": "neexistuje",
    "queues": [ ]
  }
]

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "success": true,
      "queues": [
        {"id": 146, "success": true, "Nothing to change"},
        {"id": 123, "success": true, "Nothing to change"},
        {"id": 82, "success": true, "Agent membership updated"},
        {"id": 103, "success": true, "Agent removed from queue"}
      ]
    },
    {
      "external_id": "2468",
      "success": true,
      "queues": [
        {"id": 82, "success": true, "Agent added into queue"},
        {"id": 0, "success": false, "Unknown queue id"}
      ]
    },
    {
      "id": 0,
      "success": false,
      "error": "Unknown agent id",
      "queues": [ ]
    },
    {
      "external_id": "neexistuje",
      "success": false,
      "error": "Unknown agent external_id",
      "queues": [ ]
    }
  ]
}

µCRM

Synchronization of customers to UCS micro CRM.

Persons List

GET /api/v1.0/crm/persons

The method accepts optional limit and offset parameters in the URL.

The return value is an array of Person objects.

Example of getting 50 contacts with an offset of 100

Request

GET https://ucs.example.com/api/v1.0/crm/persons?limit=50&offset=100

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 26920,
      "group_id": 1,
      "displayname": "Abrhám Václav",
      "firstname": "Václav",
      "lastname": "Abrhám",
      "external_id": "16943"
    },
    {
      "id": 13270,
      "group_id": 1,
      "displayname": "Adamec Lukáš",
      "firstname": "Lukáš",
      "lastname": "Adamec",
      "external_id": "20451"
    },
    {
      "id": 25677,
      "group_id": 1,
      "displayname": "Albert Antonín",
      "firstname": "Antonín",
      "lastname": "Albert",
      "external_id": "23393"
    },
    ...
  ],
  "total": 26907
}

There are a total of 26907 people in µCRM.

Person Detail

GET /api/v1.0/crm/person/{person_id}

GET /api/v1.0/crm/person/external/{external_id}

Example of getting contact person detail from µCRM

Request

GET https://ucs.example.com/api/v1.0/crm/person/59233

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

nebo

GET https://ucs.example.com/api/v1.0/crm/person/external/abc123

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "id": 59233,
    "group_id": 1,
    "displayname": "Ing. Petr Novák VIP",
    "firstname": "Petr",
    "lastname": "Novák",
    "note": "Pozor, je to převelice důležitý zákoš…",
    "external_id": "abc123",
    "data": {
      "expires": "2025-01-01 00:00:00"
    },
    "contacts": [
      {
        "id": 71615,
        "type": 2,
        "contact": "a@b.cd",
        "label": "e-mail"
      },
      {
        "id": 71616,
        "type": 1,
        "contact": "+420654321987",
        "label": "mobil"
      },
    ],
    "interactions": [ ],
    "companies": [ ],
    "tasks": [ ]
  }
}

Person

User object structure:

Key	Type	Note
id	int	unique person ID (primary key)
group_id	int	ID of the group the person is a member of
displayname	str	the person's display name
firstname	str	name
lastname	str	surname
note	str	any note to the contact person
external_id	str	user identifier in the external IS
data	object	key/value associative array for arbitrary data
contacts	array	contact data field (Contact object)
interactions	array	history of communication with the client (read-only)
companies	array	companies in which the person is included (read-only)
tasks	array	tickets associated with the given person (read-only)

Contact

Contact object structure:

Key	Type	Note
id	int	unique association ID (primary key)
type	enum[int]	contact type 0: general contact 1: phone number 2: email address 3: web URL
contact	str	contact (address, phone number, email, URL)
label	str	description for the given contact information

Person Create

POST /api/v1.0/crm/person

A Person object structure is passed as the request body. Only the group_id attribute is required.

The return value is the ID of the newly created record.

Example of inserting a new person into µCRM

Request

POST https://ucs.example.com/api/v1.0/crm/person

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "group_id": 1,
  "displayname": "Martin Dvořák",
  "external_id": "321654987",
  "contacts": [
    {
      "type": 1,
      "contact": "+420222333444",
      "label": "kancelář"
    }
  ]
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": 123456
}

The internal UCS ID of the newly established person µCRM is 123456.

Person Update

PATCH /api/v1.0/crm/person/{person_id}

A Person object structure with the attributes to be updated is passed as the request body. The contacts attribute is optional if the person's contacts are not to be updated. If the contacts attribute is passed, then the contacts are overwritten according to the passed content.

The return value of the method is empty.

Example of updating the data of an existing person in µCRM

Request

PATCH https://ucs.example.com/api/v1.0/crm/person/123456

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "firstname": "Martin",
  "lastname": "Dvořák"
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Person Delete

DELETE /api/v1.0/crm/person/{person_id}

Deletes a person from UCS.

The return value of the method is empty.

Example of deleting an existing person from µCRM

Request

DELETE https://ucs.example.com/api/v1.0/crm/person/123456

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Companies List

GET /api/v1.0/crm/companies

Contact persons in µCRM can be covered by a company. The method accepts optional limit and offset parameters in the URL. The return value is an array of Company objects.

Example of getting 50 coverage organizations at offset 100

Request

GET https://ucs.example.com/api/v1.0/crm/companies?limit=50&offset=100

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

{
  "success": true,
  "data": [
    {
      "id": 5313,
      "group_id": 1,
      "name": "Acme inc.",
      "external_id": "74"
    },
    {
      "id": 2919,
      "group_id": 1,
      "name": "All happy, ltd.",
      "external_id": "13873"
    },
    {
      "id": 1677,
      "group_id": 1,
      "name": "AZ s.r.o.",
      "external_id": "6694"
    },
    ...
  ],
  "total": 10611
}

There are a total of 10611 companies in µCRM.

Company Detail

GET /api/v1.0/crm/company/{company_id}

GET /api/v1.0/crm/company/external/{external_id}

Example of getting company detail in µCRM

Request

GET https://ucs.example.com/api/v1.0/crm/company/10764

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

nebo

GET https://ucs.example.com/api/v1.0/crm/company/external/ins

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  success: true,
  data: {
    "id: 10764,
    "group_id: 1,
    "name: "INSOFT s.r.o.",
    "external_id": "ins",
    "data": {
      "ico": "04110889"
    },
    "persons": [
      {
        "person_id": 123456,
        "role": "majitel"
      }
    ],
    "tasks": [ ]
  }
}

Company

Structure of the company object:

Key	Type	Note
id	int	unique company ID (primary key)
group_id	int	ID of the group of which the company is a member
name	str	company name
external_id	str	user identifier in the external IS
data	object	key/value associative array for arbitrary data
persons	array	array of persons belonging to the company (object CompanyPerson)
tasks	array	tickets associated with the given company (read-only)

CompanyPerson

The structure of the person-to-company association object:

Key	Type	Note
person_id	int	unique ID of a person (object Person)
role	str	description of a person's role in society

Company Create

POST /api/v1.0/crm/company

The Company object structure is passed as the request body. Only the group_id attribute is required.

The return value is the ID of the newly created record.

Example of creating a new company in µCRM

Request

POST https://ucs.example.com/api/v1.0/crm/company

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "group_id": 1,
  "name": "Společnost a.s."
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": 10765
}

Company Update

PATCH /api/v1.0/crm/company/{company_id}

A Company object structure with the attributes to be updated is passed as the request body. The persons attribute is optional if associated persons are not to be updated. If the persons attribute is passed, then persons are overwritten according to the passed content.

The return value of the method is empty.

Example of editing company attributes in µCRM

Request

PATCH https://ucs.example.com/api/v1.0/crm/company/123456

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json

{
  "persons": [
    {
      "person_id": 123456,
      "role": "dodavatel"
    },
    {
      "person_id": 123457,
      "role": "jednatel"
    }
  ]
}

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

Company Delete

DELETE /api/v1.0/crm/company/{company_id}

Deletes the company from UCS.

The return value of the method is empty.

Example of deleting a company from µCRM

Request

DELETE https://ucs.example.com/api/v1.0/crm/company/10764

Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Response

200 OK

Content-Type: application/json

{
  "success": true,
  "data": null
}

REST API

Communication Protocol​

OAuth Login​

Status and Enumerations​

Status​

Queues​

Groups​

Roles​

Teams​

Calls​

Call Information​

Call Metadata Detail​

Call Metadata Update​

Shared Data​

Fetch Values​

Update Values​

Users​

Users List​

User Detail​

User​

User Create​

User Update​

User Delete​

Agent Queue Membership Detail​

Typy front UCS​

Agent Queue Membership Update​

AgentQueues​

QueueMembership​

µCRM​

Persons List​

Person Detail​

Person​

Contact​

Person Create​

Person Update​

Person Delete​

Companies List​

Company Detail​

Company​

CompanyPerson​

Company Create​

Company Update​

Company Delete​

Communication Protocol

OAuth Login

Status and Enumerations

Status

Queues

Groups

Roles

Teams

Calls

Call Information

Call Metadata Detail

Call Metadata Update

Shared Data

Fetch Values

Update Values

Users

Users List

User Detail

User

User Create

User Update

User Delete

Agent Queue Membership Detail

Typy front UCS

Agent Queue Membership Update

AgentQueues

QueueMembership

µCRM

Persons List

Person Detail

Person

Contact

Person Create

Person Update

Person Delete

Companies List

Company Detail

Company

CompanyPerson

Company Create

Company Update

Company Delete