Introduction

This document describes EnreachAPI (formerly known as BeneAPI), a RESTful API that allows 3rd parties access Enreach systems to perform various functions. EnreachAPI serves data mapped as resources corresponding to URI paths. Client applications make HTTP requests to the API and handle the response. Request and response data can be serialized to either JSON or XML formats. The API is not dependent on any specific language or technology, so it can be used by any application capable of making HTTP requests and parsing the responses.

Note that Benemen was renamed to Enreach in 2022, and corresponding naming changes were applied to technical products and documentation as well. Some documentation and technical details (XML namespaces, domain names) may still contain Benemen references.

HTTPS requirements

HTTPS is required for all endpoints. Security configuration follows SSLabs SSL and TLS Deployment Best Practices.

All API integrations must meet following requirements for HTTPS.

TLS Protocol support

Supported TLS protocols are TLS v1.2 and TLS v1.3. As of January 20, 2022, older TLS 1.0 and 1.1 protocols are deprecated for all HTTPS services.

Secure Cipher Suites

Following cipher suites are supported. As of June 16, 2022, all older and insecure cipher suites are deprecated for all HTTPS services.

• ECDHE-ECDSA-AES256-GCM-SHA384
• ECDHE-ECDSA-AES128-GCM-SHA256
• ECDHE-RSA-AES256-GCM-SHA384
• ECDHE-RSA-AES128-GCM-SHA256
• ECDHE-ECDSA-CHACHA20-POLY1305
• ECDHE-RSA-CHACHA20-POLY1305

Service discovery

Example discovery using POST

POST https://discover.enreachvoice.com/api/user
Content-Type: application/json

{
    "user": "user.name@example.com",
}


HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Jun 2018 13:25:14 GMT
[
  {
    "siloName": "Silo02",
    "username": "user.name@example.com",
    "apiEndpoint": "https://api-sedna.enreachvoice.com/",
    "uiEndpoint": "https://sedna.enreachvoice.com/Account/LogOn/?un=user.name@example.com",
    "authority": null,
    "authorityIdPHint": null,
    "basicAuthEndpoint": "https://sedna.enreachvoice.com/Account/BasicLogOn/?un=user.name@example.com",
    "recoveryEndpoint": "https://sedna.enreachvoice.com/Account/RequestPassword/?un=user.name@example.com"
  }
]

Example discovery using GET

curl -v https://discover.enreachvoice.com/api/user?user=user.name@example.com

> GET /api/user?user=test.user@domain.com HTTP/1.1
> Host: discover.enreachvoice.com
> User-Agent: curl/7.55.1

< HTTP/1.1 200 OK
< Transfer-Encoding: chunked
< Content-Type: application/json; charset=utf-8
< Date: Thu, 14 Jun 2018 13:25:14 GMT
<
[
  {
    "siloName": "Silo02",
    "username": "user.name@example.com",
    "apiEndpoint": "https://api-sedna.enreachvoice.com/",
    "uiEndpoint": "https://sedna.enreachvoice.com/Account/LogOn/?un=user.name@example.com",
    "authority": null,
    "authorityIdPHint": null,
    "basicAuthEndpoint": "https://sedna.enreachvoice.com/Account/BasicLogOn/?un=user.name@example.com",
    "recoveryEndpoint": "https://sedna.enreachvoice.com/Account/RequestPassword/?un=user.name@example.com"
  }
]

Enreach provides two-layer infrastructure, where different users may be served by different backends accessed via different API addresses.

For dynamic clients providing service to any user logging in, service discovery is an important part of the overall functionality. For static integrations, targeting a single, known endpoint is acceptable. However, implementing service discovery always makes the service more robust, as manual endpoint changes can be avoided in the future.

Discovery endpoint is always https://discover.enreachvoice.com/api/user/ for production use. Discovery application also provides a browser interface that the users can use to discover their default web interfaces. This is found at site root address https://discover.enreachvoice.com/, but is not relevant for integrations.

The discovery API requires a single parameter: username of the user logging in. This must be a full username, no partial matching is performed. The request can be made with either GET or POST method.

Result contains a list of endpoints where given username is found. Usually given username is found in a single endpoint only. However, if relevant for the use case, multiple endpoints should be supported so that if there are multiple results, a selection dialog is shown for the user.

If the username is not found at all, a 404 Not found response is returned.

Each individual endpoint result contains urls for both API and additionally other information for Enreach Client use, which are not relevant in API integraiton use cases. For integrations, the API endpoint is used as API root address for all actual API requests.

After endpoint result is discovered, it should be stored locally and cached for the duration of application runtime.

Request properties

When using GET, the username is passed as a query parameter.

When using POST, the username is passed in the request body as a JSON object.

Response properties

Key acquisition (Classic authentication)

EnreachAPI supports two authentication models: Modern authentication and Classic authentication.

Modern authentication via Enreach Identity is OpenId Connect/OAuth2 bearer token based authnetication method. It is currently supported only for Enreach Client applications.

Classic authentication is based on SecretKey and HTTP Basic Authentication. Classic authentication is used for all external API integrations.

Each request to EnreachAPI must be authenticated (except operations where it is not possible, e.g. authentication and password recovery). The requests are authenticated with username and SecretKey, a random string acquired from backend.

There are two ways to acquire the SecretKey:

Password authentication

If there are no pre-configured credentials available, usually in cases where the actual end-user is expected to log in to the system with their own credentials, the client can perform a direct password authentication against the API using the POST /authuser/{email}/ endpoint. First, the client should collect end-user credentials and authenticate to API with. SecretKey property should be then extracted from the response and used in further communication. This is the usual way for end-user interfaces.

Off-band key delivery

Username and SecretKey can be delivered off-band directly. In this case, the related account does not have an actual password set and cannot perform the username+password authentication step described below. It is not needed either, as the SecretKey is used directly to authenticate the requests. This mechanism is mostly used for server-side integrations where a single static integration account is used.

Request authentication

Each request to EnreachAPI must be authenticated (except operations where it is not possible, e.g. authentication and password recovery). The requests are authenticated with username and SecretKey (acquisition described in [key acquisition)(#key-acquisition)]).

There are two different mechanisms that can be used to authenticate the requests. Basic authentication should be used for new development, signature-based model is supported for backwards-compatibility.

Basic authentication

string GetBasicAuthorizationHeader(string user, string key)
{
    var combined = user + ":" + key;
    var bytes = System.Text.Encoding.UTF8.GetBytes(combined);
    var base64 = System.Convert.ToBase64String(bytes);
    var headerValue = "Basic " + base64;
    var header = "Authorization: " + headerValue;
    return header;
}

import base64
def get_header(user, key):
    combined = user + u":" + key
    bytes = bytes(combined, "utf-8")
    b64string = base64.b64encode(bytes).decode("utf-8")
    return "Authorization: Basic " + b64string

Basic authentication is the recommended mechanism for authentication. It relies on standard Basic authentication, using SecretKey as password.

Note that due to backwards-compatibility requirements and multiple authentication mechanisms, standard WWW-Authenticate header is not returned for 401 Unauthorized responses.

Most client libraries support Basic authentication out of the box. It can be also implemented manually very simply. Example below uses username: test.user@test.com, Secretkey: badkey

• username and key are combined with a single colon
  • test.user@test.com:badkey
• result string is represented as a byte array (using UTF-8 encoding), which is then encoded as a base64 string
  • dGVzdC51c2VyQHRlc3QuY29tOmJhZGtleQ==
• The base64 string is prepended by "Basic "
  • Basic dGVzdC51c2VyQHRlc3QuY29tOmJhZGtleQ==
• The value is sent as request Authorization header
  • Authorization: Basic dGVzdC51c2VyQHRlc3QuY29tOmJhZGtleQ==

Signature-based (legacy)

import urllib2, hmac, hashlib, base64

# request is urllib2.Request
request = build_your_own_request()

# Your credentials
user = "user.name@test.com"
key = "badkey"

msgstring = "\n".join([
        request.get_method(),
        request.get_header("Content-md5", default=""),
        request.get_header("Content-type", default=""),
        request.get_header("Date", default=""),
        request.get_selector()
    ])

hash = hmac.new(key, msgstring, hashlib.sha1)
encoded = base64.b64encode(hash.digest())

headerval = base64.b64encode("%s:%s" % (user, encoded))
header = "BeneAPI %s" % headerval

request.add_header("Authorization”, header)

using System.Convert;
using System.Text;
using System.Security.Cryptography;
using System.Collections.Specialized;

public static string CalculateRequestHash(
    String httpMethod,
    String requestUri,
    NameValueCollection headers
)
{
    string signature =
        httpMethod + '\n' +
        headers.Get("Content-MD5") + '\n' +
        headers.Get("Content-Type") + '\n' +
        headers.Get("Date") + '\n' +
        requestUri;

    HMACSHA1 hmac = new HMACSHA1(Encoding.UTF8.GetBytes("1234"));
    byte[] bytes = Encoding.UTF8.GetBytes(signature);
    byte[] hash = hmac.ComputeHash(bytes);
    string b64hash = Convert.ToBase64String(hash);

    return b64hash;
}

With legacy hash calculation mechanism, clients authenticate each request by signing it with their private key. This method is fully supported for backwards-compatibility with existing clients, but for new development Basic authentication is recommended for ease of use.

Note that despite the API being renamed from BeneAPI to EnreachAPI, the legacy BeneAPI scheme is used here.

For each request, client computes a message hash with his private key. This hash is sent along with the request in Authorization header. Each request must contain an Authorization HTTP Header of format:

Authorization: BeneAPI base64encode({Username}:{Signature})

Where username is the provided username and signature is a hash calculated for each request individually. For example:

Authorization: BeneAPI dXNlci5uYW1lQHRlc3QuY29tOmFiY2QxMjM0

Hash is calculated from selected parts of the request:

• HTTP method
• Content-MD5 header value
• Content-Type header value
• Date header value
• Request path and query

The exact values of these fields are joined together with a \n (new line) character. If some header is not used in the request, an empty string is used instead in calculation. A HMAC-SHA1 hash is then calculated from the result string (UTF-8 encoded bytes) using the acquired secret key as the key.

Every request must have Date header containing current UTC time. It must be sufficiently close (a few minutes) to server time for request to be accepted. Date format should conform to RFC2616, e.g.:

Date: Wed, 11 Feb 2015 09:14:55 GMT

For convenience YYYY-MM-DD HH:MM:SS GMT is also accepted, e.g.:

Date: 2015-02-11 09:14:55 GMT

Detailed sample calculation

• A GET request is made to an endpoint:
  • https://beneapi30.beneservices.com/users/c24a0acb-8fd1-e511-874c-00155d000507/availability/active?PresenceTypeIds=0
• Request contains a Content-Type header but as no actual content is sent, Content-MD5 header is not present and empty string is used instead
  • GET\n\napplication/json\n2016-02-15 10:28:52 GMT\n/users/c24a0acb-8fd1-e511-874c-00155d000507/availability/active?PresenceTypeIds=0
• The constructed string is signed with the example key badkey
  • FothFWvu0L6xWAFJbFC6ku/Ss8Q=
• The hash is joined together with requesting username:
  • test.user@test.com:FothFWvu0L6xWAFJbFC6ku/Ss8Q=
• The joined string is base64 encoded again and string placed in request Authorization header:
  • Authorization: BeneAPI dGVzdC51c2VyQHRlc3QuY29tOkZvdGhGV3Z1MEw2eFdBRkpiRkM2a3UvU3M4UT0=

Authorization

Access to resources is authorized in with permissions related to individual entities in the system: users, service pools, directories and callback lists. Permissions are semi-static, usually defined during the integration setup phase where access credentials are created. Usually minimum permissions for the specific need are configured, e.g. allow access to availability statuses of all users in given group for an integration that displays the statuses somewhere.

Permissions are defined as combinations of a string keyword and CRUD (Create, Read, Update, Delete) -flags. They can be specified as relations between users and/or user groups.

Responses

Example of a faulty request made without a Date header:

GET /calls HTTP/1.1
Accept: application/xml

Response received from server.

HTTP/1.1 400 Bad Request
Content-Length: 96
Content-Type: application/xml; charset=utf-8

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Missing Date
 header</string>

Standard HTTP/1.1 response codes are used to return operation status to client. The most commonly used ones are:

Serialization

XML and JSON serializations are supported for both request and response serialization with application/xml and application/json as the values. Standard HTTP headers are used to specify formats: Accept header requests specific response format, Content-Type header must be used to specify data format when data is sent to the API.

For new development JSON is heavily recommended format. XML is supported for compatibility with existing clients, but will be deprecated and removed at some point.

Accept: application/json
Content-Type: application/json

Additionally, the API supports two JSON flavors. These are referred to as v1 ("Legacy Microsoft") and v2 (modern cross-compatible) formats.

The client requests a specific JSON version by specifying HTTP header X-Json-Serializer: 2. All new development should use the v2 format. v1 is supported for backwards-compatibility, but will be deprecated later.

The differences between the two versions relate to how different data types are handled. The differences are listed below.

Migrating from v1 to v2 requires the following steps:

• Check the data types returned by endpoints you are using
• Alter the serialization/deserialization for the corresponding properties

Using v2 is supported by all tested serializers out-of-the box, whereas using v1 often required customization. Usually, the migration work is just removing that customization.

Existing clients using v1 that cannot be changed to v2 should send X-Json-Serializer: 1 header with their requests to indicate they need the legacy format. This ensures they remain working once the default behavior changes from v1 to v2.

Query parameters

Objects are also serialized to query parameters in some use cases. For example when calling /calls/ with [CallFilterParameters](#callfilterparameters. In these cases the parameter object is serialized as standard query parameters with url-encoded key=value pairs representing object properties. List-type properties are represented as semicolon separated values.

For example an object like: { "StartTime": "2018-01-01T00:00:00", "SomeIntValues": [1, 2] }

Would be serialized to query string as: StartTime=2018-01-01T00:00:00&SomeIntValues=1;2

XML serialization notes

Node ordering

Deserializer expects input XML nodes to be ordered alphabetically ascending by tag name. Nodes in incorrect position are left unhandled.

Valid: <Item><A>Value></A><B>ValueOfB</B></Item>

Invalid: <Item><B>ValueOfB</B><A>Value></A></Item>

Lists

Serialized List<User>

<ArrayofUser>
    <User />
    <User />
</ArrayofUser>

When an operation returns a list, the root node is named ArrayofEntityName.

Serialized list property inside a container

<SomeContainerEntity>
    <Items xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <a:guid>09C28FB6-71A1-4E27-AF0F-9F16536FCC77</a:guid>
    </RecordingIds>
</SomeContainerEntity>

When a returned entity has list-valued property, it works differently. For example, if a SomeContainerEntity has a property named Items with value type List>Guid<, it is serialized with property name as root node name and items as children.

For lists of serialized child types, namespace is serialized similarly

<Items xmlns:a="http://schemas.datacontract.org/2004/07/BeneAPI.Entities">
    <a:ChildItemType>
        <a:Name>Sample key</a:Name>
        <a:Value>Sample value</a:Value>
    </a:ChildItemType>
</Items>

XML serialization is performed with property name as tag name and content as its content. Lists of items are serialized inside .

JSON serialization notes

There are some JSON serialization quirks in used .NET library. These are quite straightforward to work with, but possibly need some attention.

Datetimes

.NET-specific special DateTime format is used for serialization. Milliseconds since Unix epoch with an offset.

Most deserialization implementations cannot deserialize this format to DateTime automatically, but requires manual offset handling. The format is unfortunate but maintained for backwards-compatibility.

// Sample parser using Newtonsoft Json.Net
using Newtonsoft.Json;

DateTime ParseDotNetJsonDate(string input)
{
    DateTimeOffset dto = JsonConvert.DeserializeObject<DateTimeOffset>(input);
    DateTime dt = dto.UtcDateTime + dto.Offset;
    return dt;
}

// Sample parser using regex
DateTime ParseDotNetJsonDate2(string input)
{
    var m = new Regex(@"\\\/Date\((\d+)(?:([+-])(\d\d)(\d\d))?\)")
        .Match(input);

    return
    // From epoch
    new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)
    .AddMilliseconds(long.Parse(m.Groups[1].Value))
    .AddMinutes(
        // Offset sign found
        m.Groups[2].Success ?
            // Sign
            int.Parse(m.Groups[2].Value + "1") *
            // First 2 digits -> hours
            int.Parse(m.Groups[3].Value) * 60 +
            // Last 2 digits -> minutes
            int.Parse(m.Groups[4].Value)
            :
            0
    );
}

TimeSpans

TimeSpan types are serialized to JSON in ISO8601 duration format. For example, a TimeSpan of 2 minutes and 11 seconds is serialized as:

PT2M11S

Dictionaries

Dictionaries are not serialized as plain objects but as an array of objects with Key and Value.

[{"Key":"Key1","Value":"Value1"}]

Authentication and authorization

POST /authuser

Example log in with password

POST /authuser
Content-Type: application/json
Accept: application/json

{
  "UserName":"test.user@test.com",
  "Password":"Test123"
}



HTTP/1.1 200 OK
Content-Length: 250
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Feb 2016 13:55:39 GMT

{
  "CanChangePassword":true,
  "CanRecoverPassword":true,
  "OrganizationalUnitId":"a5055f5a-51a1-e411-9536-00155d000507",
  "Password":null,
  "Permissions":null,
  "SecretKey":"badkey",
  "UserID":"c24a0acb-8fd00c01-e511-874c-00155d000507",
  "UserName":"test.user@test.com"
}

Performs a password login for given username. This operation can be used to authenticate end-user clients when deploying SecretKey via other channels is not practical, for example when creating a generic client that receives credentials as user input. "Log in" is done with password and received SecretKey is securely stored in client and used to perform the other operations.

Validates credentials provided in body containing an AuthUser entity with UserName and Password properties set.

UserName(email) must be set in the content body.

Additional query parameter permissions=1 may be provided to request user permissions information to be included in response.

• Url parameters: none
• Query parameters: none
• Request content: AuthUser
• Response content: AuthUser

POST /authuser/{email}

Example log in with password

POST /authuser/test.user@test.com
Content-Type: application/json
Accept: application/json

{
  "UserName":"test.user@test.com",
  "Password":"Test123"
}



HTTP/1.1 200 OK
Content-Length: 250
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Feb 2016 13:55:39 GMT

{
  "CanChangePassword":true,
  "CanRecoverPassword":true,
  "OrganizationalUnitId":"a5055f5a-51a1-e411-9536-00155d000507",
  "Password":null,
  "Permissions":null,
  "SecretKey":"badkey",
  "UserID":"c24a0acb-8fd00c01-e511-874c-00155d000507",
  "UserName":"test.user@test.com"
}

This endpoint is deprecated. Use POST /authuser instead. Performs a password login for given username. This operation can be used to authenticate end-user clients when deploying SecretKey via other channels is not practical, for example when creating a generic client that receives credentials as user input. "Log in" is done with password and received SecretKey is securely stored in client and used to perform the other operations.

Validates credentials provided in body containing an AuthUser entity with UserName and Password properties set.

UserName must correspond to the one in the URI.

Additional query parameter permissions=1 may be provided to request user permissions information to be included in response.

• Url parameters: {email} - username to authenticate
• Query parameters: none
• Request content: AuthUser
• Response content: AuthUser

PUT /authuser/password

Attempts to change password for a user. UserName(email) must be set in the content body.

• Url parameters: none
• Query parameters: none
• Request content: PasswordChange
• Response content: AuthUser

PUT /authuser/{email}/password

This endpoint is deprecated. Use PUT /authuser/password instead. Attempts to change password for a user.

• Url parameters: {email} - user to change password for
• Query parameters: none
• Request content: PasswordChange
• Response content: AuthUser

POST /authuser/passwordreset

Request a password reset for given user. UserName(email) must be set in the content body.

• Url parameters: none
• Query parameters: none
• Request content: List<PasswordResetVerification>
• Response content: bool - If request was success

Password reset flow

• User navigates to 'Forgot password page'
• Enters username (email)
• If the user has any phone number configured, enters it. Otherwise checks the "no number" box.

• Submits

• API checks the verification and queues the recovery email to be sent if they are correct

• User waits for an email with a link that contains RecoveryToken ​​​in the url.

• Opens the link in email

• Enters username (email)

• Enters a new password twice

• Submits

• PUT /authuser/password is used with RecoveryToken populated instead of the OldPassword

• API checks the token and sets the password

POST /authuser/{email}/passwordreset

This endpoint is deprecated. Use POST /authuser/passwordreset instead. Request a password reset for given user.

• Url parameters: {email} - user to reset password for
• Query parameters: none
• Request content: List<PasswordResetVerification>
• Response content: bool - If request was success

GET /authuser/{userid}/permissions

Returns complete permission list for targeted user. Can be only called for current user, attempting to acquire permissions of another user always returns 403 Forbidden. Returns the exact same list that is included in AuthUser structure, but can be called separately and should be preferred over the ?permissions=1 mechanism described under POST /authuser.

AuthUser

Result of a successful "login" with permissions returned alongside the main entity

{
  "OrganizationalUnitId": "6b98b72a-5b9c-45a4-9549-d549aad2bab5",
  "UserID": "36729336-496c-4d65-99b1-8186f3cd2356",
  "UserName": "current.user@test.com",
  "SecretKey": "long random string",
  "Password": null,
  "CanChangePassword": false,
  "CanRecoverPassword": false,
  "Permissions": [
    {
      "TargetUser": {
        "Id": "74b14bc1-2f08-464a-bd7c-7329ad007c08",
        "UserName": "test.user@test.com",
        "Email": "test.user@test.com",
        "Name": "Test User",
        "FirstName": "Test",
        "LastName": "User",
        "OrganizationID": "acc3ecfc-264a-4d30-a736-3d17797d5a37",
        "Settings": null
      },
      "TargetDirectory": null,
      "TargetQueue": null,
      "TargetCallback": null,
      "KeywordString": "Call",
      "Status": {
        "Create": null,
        "Read": true,
        "Update": null,
        "Delete": null
      }
    }
  ]
}

AuthUser entities are returned when performing a password-based “login”. This can be used to acquire the secret key required for signing all requests, provided the requester knows users configured password. AuthUser entity then contains authentication and authorization related information about the user, like organization id, user id, username, and secret key. Optionally, a list of Permission entities related to the user may be included.

PasswordChange

{
    "UserName":"test.user@test.com",
    "OldPassword":"MyPassword",
    "NewPassword":"New, safe and secure password"
}

Password change entity is received by the API to perform a password change on given user.

PasswordResetVerification

[
    {
        "Type":"Phonenumber",
        "Value":"+358501234567"
    }
]

Password reset entity is received by the API to perform a password reset on given user.

Permission

Example of a single permission indicating that whoever has this permission can read call information of targeted user

{
  "TargetUser": {
    "Id": "9db12574-4320-4167-84e5-e37b7c4d5479",
    "UserName": "test.user@test.com",
    "Email": "test.user@test.com",
    "Name": "Test User",
    "FirstName": "Test",
    "LastName": "User",
    "OrganizationID": "8019cdfb-086b-4e48-9547-d80d9b6831b2",
    "Settings": null
  },
  "TargetDirectory": null,
  "TargetQueue": null,
  "TargetCallback": null,
  "KeywordString": "Call",
  "Status": {
    "Create": null,
    "Read": true,
    "Update": null,
    "Delete": null
  }
}

Permission entity represents a single Permission. Permissions are always resolved from acting user to target entity (User, Queue, Directory, CallbackList). It contains target entity, PermissionKeyword and PermissionStatus entity. Only one entity is present for each permission entity.

PermissionKeywords are related to specific resource permissioning and are optionally provided to allow client customization based on available functionality

PermissionStatus

{
  "Create": null,
  "Read": true,
  "Update": null,
  "Delete": null
}

PermissionStatus is a set of flags Create, Read, Update, Delete, representing the allowed operations relating to the permission.

Impersonation

In some integration cases, it may be necessary a need to communicate with the API as a specific user without requiring the user to fill in their credentials. To enable such use, a high privilege account may be authorized to generate impersonation tokens for specific users. This enables a very simple SSO / IdP style approach in use cases where the integration side has authenticated the user, but that identity cannot be conveniently federated to the API.

The flow on the high level is: - Client connects to the integration side - Client authenticates in a suitable way - Integration side maps the authenticated user to a EnreachAPI user - Integration side acquires an impersonation token from EnreachAPI and passes that to the client - The client proceeds to communicate directly with the API

This behavior is similar to what could be approached using actual SSO with an IdP (such as Azure AD) and our own identity provider. This approach is simpler and does not support any of the finer details, such as refresh tokens, but may be easier to use in integration cases where a full IdP integration is infeasible.

Note that the generated impersonation token is relatively short-lived (in the order of minutes, not hours). Therefore, the integration side must be able to supply a fresh token for the client when appropriate. The actual expiry time can be determined from the expires_in property in the API response. A fresh token can then be generated before the old one expires.

POST /token/{userid}/impersonate

Request a new impersonation token for given user

• Url parameters: {userid} - targeted user
• Query parameters: none
• Request content: none
• Response content: ImpersonationTokenResult
• Status codes:
  • 200 OK - on success
  • 403 Forbidden - token generation is not authorized

ImpersonationTokenResult

{
  "access_token":"aaaa.bbbb.cccc",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type":"Bearer",
  "expires_in":3600
}

Using the token

When making further API calls, the client may simply include the received token in Authorization header. Note that the token_type from the incoming payload should be used as Authorization scheme.

GET /users/user-1234/availability
Authorization: Bearer aaaa.bbbb.cccc

When using Bearer token, API returns 401 Unauthorized in case the supplied token is invalid. Additionally, the response body contains string token_invalid. The client can thus detect that a new token is needed.

User call information

These endpoints return information related to user calls, call recordings and call transcripts. There are two different types of user calls: Direct calls and Service calls (AgentCalls)

Direct calls

Direct calls are incoming calls dialed directly to a user, or outgoing calls made by the user. Direct calls have a special CallPublicity that further limits access. If Direct call is classified as 'private' or 'undefined', only that actual user can access the call information. If the call is classified as 'work', the call information is available to other users having read access to user direct calls.

Service calls (AgentCalls)

There are three types of servicecalls: Incoming QueueCalls, Outgoing QueueCalls and Outgoing CallbackCalls. This endpoint returns service call information from user (agent) perspective. Use /servicecall/, /outbound-servicecall/ and /outbound-callbackcall/ endpoints to retrieve service call information from broader perspective.

Incoming QueueCalls are calls that are allocated to the user from a service queue. Each allocation event creates a separate call event having Result=3 (Allocated). If the user accept the call, a separate call event is created having Result=0 (Answered)'. The same service call (i.e. same callId) can be allocated to user multiple times, each allocation creates a separate user call event.

Outgoing QueueCalls are calls that are made by user in the name of service queue.

Outgoing callback calls are calls that are made by the user for a call list.

Access control

User level calls have three levels of access:

• Call, main information. Shows call details with three last digits of phone numbers masked. Disables querying by phone number
• CallNumbers, number information. Returns unmasked phone numbers instead
• CallRecording, recording information. Allows separately fetching call recording data relating to the calls.
• CallTranscript, transcript information. Allows separately fetching call transcript data relating to the calls.

Permissions are configurable in user level. This means that it is possible to enable an integration account to fetch call information for any subset of all users.

Data update frequency

User call information is updated at roughly 10 second intervals. Calls are exposed over the API only after the call completes and disconnects. This is relevant especially if you acquire information about the existence of a call over another channel (RTE, webhooks) that exposes information about ongoing calls as well.

You can take this into account by delaying the loading of such calls for a short time or by having a mechanism to cover the case where the call is not yet accessible.

GET /calls

Returns a list of user related call events matching filter specified by query parameter.

• Query parameters: CallFilterParameters
• Request content: none
• Response content: List<CallEvent>

GET /calls/{eventId}

Returns a single event specified by call event id.

• Url parameter: {eventId} - id of a specific call event
• Query parameters: none
• Request content: none
• Response content: CallEvent
  

GET /calls/recordings/{recordingId}

Returns a single CallRecording metadata. Contains information about the recording and the url to actual recording stream. RecordingId corresponds to the ids returned in CallEvent

• Url parameter: {recordingId} - id of a specific recording
• Query parameters: none
• Request content: none
• Response content: CallRecording

GET /calls/transcripts/{transcriptId}

Returns a single CallTranscript. Contains the transcription content. TranscriptId corresponds to the ids returned in CallEvent

• Url parameter: {transcriptId} - id of a specific transcript
• Query parameters: none
• Request content: none
• Response content: CallTranscript

PUT /calls/{eventId}/publicity

Sets the publicity category for the given direct call event id. Agent calls cannot be changed. Call event publicity category can only be changed by the same user that owns the call event regardless of permissions. Can be changed if category is Undefined otherwise the call event timestamp needs to be less than two weeks from the date when change occurs.

• Url parameter: {eventId} - id of a specific call event
• Query parameters: none
• Request content: CallPublicityCategory
• Response content: CallEvent

CallEvent

Default JSON serialization of a CallEvent

[
  {
    "ANum": "+358123456789",
    "BNum": "+358987654321",
    "CallID": "2cf79da6-03b8-464d-9a1a-b783f539651c",
    "CallTypeString": "DirectCall",
    "CallbackListId": null,
    "CallbackRequestId": null,
    "CanChangeCallPublicityCategory": true,
    "Direction": 0,
    "Duration": 18,
    "EndResult": 0,
    "ID": "64f5b73e-6d92-ee11-9944-005056895f22",
    "Modified": "\/Date(1701670840717+0000)\/",
    "OrgID": "29f6e823-b484-e611-80c9-00505689257e",
    "PublicityCategoryId": 0,
    "QueueId": null,
    "QueueName": null,
    "RecordingIds": [
      "e5d8d226-6d92-ee11-9944-005056895f22"
    ],
    "Recordings": [
      {
        "CanRead": true,
        "RecordingId": "e5d8d226-6d92-ee11-9944-005056895f22"
      }
    ],
    "Transcripts": [
      {
        "CanRead": true,
        "TranscriptId": "e5d8d226-6d92-ee11-9944-005056895f22"
      }
    ],
    "TimeStamp": "\/Date(1701670773960+0000)\/",
    "UserID": "aa9730c4-ce86-e611-80c9-00505689257e",
    "UserName": "user.name@example.com"
  }
]

Improved JSON seriialization of a CallEvent (X-Json-Serializer: 2)

[
  {
    "ID": "64f5b73e-6d92-ee11-9944-005056895f22",
    "CallID": "2cf79da6-03b8-464d-9a1a-b783f539651c",
    "OrgID": "29f6e823-b484-e611-80c9-00505689257e",
    "UserID": "aa9730c4-ce86-e611-80c9-00505689257e",
    "UserName": "user.name@example.com",
    "TimeStamp": "2023-12-04T06:19:33.96Z",
    "Modified": "2023-12-04T06:20:40.7179304Z",
    "Direction": 0,
    "EndResult": 0,
    "Duration": 18,
    "ANum": "+358123456789",
    "BNum": "+358987654321",
    "RecordingIds": [
      "e5d8d226-6d92-ee11-9944-005056895f22"
    ],
    "Recordings": [
      {
        "RecordingId": "e5d8d226-6d92-ee11-9944-005056895f22",
        "CanRead": true
      }
    ],
    "Transcripts": [
      {
        "TranscriptId": "e5d8d226-6d92-ee11-9944-005056895f22",
        "CanRead": true
      }
    ],
    "QueueName": null,
    "QueueId": null,
    "CallbackListId": null,
    "CallbackRequestId": null,
    "CallTypeString": "DirectCall",
    "PublicityCategoryId": 0,
    "CanChangeCallPublicityCategory": true
  }
]

Represents a single call event relating to a user. Contains general information about the call, such as time, duration and phone numbers.

CallEventRecording

Call recording metadata in relation to a specific call event.

The point of this type is that the existence of a recording related to a call event is considered to be metadata for the call event and not the recording itself. Thus, the presence of the recording should be known if the user is authorized to view the call metadata. This is not the case for the recording itself, which is authorized separately.

This enables exposing the presence of the recording to a user without having to grant the user access to the recording itself. This is useful in many integration cases, where the integration account needs to know that the recording exist but does not actually need to play it back - playback is done with user credentials separately.

CallEventTranscript

Call transcript metadata in relation to a specific call event.

The point of this type is that the existence of a transcript related to a call event is considered to be metadata for the call event and not the transcript itself. Thus, the presence of the transcript should be known if the user is authorized to view the call metadata.

This enables exposing the presence of the transcript to a user without having to grant the user access to the transcript itself. This is useful in many integration cases, where the integration account needs to know that the transcript exist but does not actually need to fetch it.

CallRecording

{
    "ID": "5f674a0e-9e07-ea11-ae70-645d86a0c4da",
    "RecordingID": "5e674a0e-9e07-ea11-ae70-645d86a0c4da",
    "CallID": "4e2c3dd5-65b5-40ec-a047-c461ded67425",
    "OrgID": "67303a08-9e07-ea11-ae70-645d86a0c4da",
    "OrgName": null,
    "UserID": "90303a08-9e07-ea11-ae70-645d86a0c4da",
    "UserName": null,
    "CallbackListId": "05cd939f-d09c-4f6a-ac1b-fc5f63624274",
    "ContentType": null,
    "ContentLength": "0",
    "URL": "recordingstream/5e674a0e-9e07-ea11-ae70-645d86a0c4da.mp3",
    "ReasonCollected": "false",
    "ReasonFreeTextEnabled" : "true",
    "ReasonOptions": [
        "Security check",
        "Customer support",
        "Troubleshooting",
        "Just for fun"
    ],
    "Expires": null
}

A single call recording (conversion). A single recording can have many conversions in different formats (mp3, wav, etc.), although in practice there usually exists only one in MP3 format. Contains url to the actual audio stream. Url includes token query string for authorization if token authorization can be made, othwerwise contains plain url. Token is valid for 10 minutes.

CallTranscript

{
    "ID": "5f674a0e-9e07-ea11-ae70-645d86a0c4da",
    "RecordingID": "5e674a0e-9e07-ea11-ae70-645d86a0c4da",
    "CallID": "4e2c3dd5-65b5-40ec-a047-c461ded67425",
    "OrgID": "67303a08-9e07-ea11-ae70-645d86a0c4da",
    "UserID": "90303a08-9e07-ea11-ae70-645d86a0c4da",
    "CallbackListId": "05cd939f-d09c-4f6a-ac1b-fc5f63624274",
    "DurationMillis": null,
    "Expires": null,
    "TranscriptStatus": "Completed",
    "Phrases": [
        {
            "ChannelId": 0,
            "DurationMillis": 1000,
            "OffsetMillis": 1000,
            "Confidence": 0.1,
            "Text": "Hello",
      "Locale": "en-GB"
        },
        {
            "ChannelId": 1,
            "DurationMillis": 1000,
            "OffsetMillis": 1000,
            "Confidence": 0.1,
            "Text": "Hello",
      "Locale": "en-GB"
        }
    ]
}

A single call transcript that will contain many transcribed phrases.

CallTranscriptPhrase

A single transcribed phrase

CallFilterParameters

Specifies allowed query parameters for call search.

Sample of CallFilterParameters serialized to query params (line breaks added for readability).

Requests calls connected between 1.1.2015 06:00 UTC and 1.1.2015 07:00 UTC that belong to user 471D995A-8F56-43FF-98B7-7D750514E9EA and were answered.

GET /calls/?StartTime=2015-01-01+06%3A00%3A00
&EndTime=2015-01-01+07%3A00%3A00
&UserIds=471D995A-8F56-43FF-98B7-7D750514E9EA
&Result=Handled

Requests calls modified between 1.1.2015 06:00 UTC and 1.1.2015 07:00 UTC that belong to user 471D995A-8F56-43FF-98B7-7D750514E9EA. Use ModifiedAfter and ModifiedBefore instead of StartTime and EndTime if you need to sync call records to external system.

GET /calls/?ModifiedAfter=2015-01-01+06%3A00%3A00
&ModifiedBefore=2015-01-01+07%3A00%3A00
&UserIds=471D995A-8F56-43FF-98B7-7D750514E9EA

Requests calls with specific callID. Note that multiple calls events can have the same callID

GET /calls/?CallId=471D995A-8F56-43FF-98B7-7D750514E9EA

Following changes were introduced in version 2023.7.0 (December 2023):

• Time range is limited to 31 days when using StartTime+Endtime or ModifiedAfter+ModifiedBefore from version 2023.7.0 (December 2023).
• Lookup with CallId does not require time range anymore.

CallType

Enumeration of call main types.

Direction

Enumeration of possible call directions.

Result

Enumeration of call end results

CallPublicityCategory

Enumeration of call publicity category.

CallOrderBy

Enum describes sort order.

Service call information

Service calls are incoming calls made to service pools. Detailed information about call progress in the system is available via ServiceCallDetail events, while ServiceCall provides high-level information about the overall call.

Access control

Service level calls have three levels of access:

• ServiceCall, main information. Shows call details with three last digits of phone numbers masked. Disables querying by phone number
• ServiceCallNumbers, number information. Returns unmasked phone numbers instead
• ServiceCallDetail, detailed event information. Allows fetching list of ServiceCallDetail events for the call

Permissions are configurable in service pool level. This means that it is possible to enable an integration account to fetch call information for any subset of all service pools. As each service call entry is owned by the service pool the call first arrived to, it is often necessary to target all service pools that can have interaction between them to properly work with overflows, scheduled transfers etc.

Data update frequency

Service call information is updated at roughly 10 second intervals. The information is exposed even when the call is ongoing, but the information can change as long as the call is ongoing. New detail events may appear for the call as long as it remains ongoing, meaning it has Result == Ongoing (0).

Once the call completes and disconnects, there will be no further detail events. Also, once the call has been completed (Result != Ongoing (0)), the result will not change again.

This is relevant if you load new calls frequently. In such case, you need to handle the ongoing calls by reloading them later after the call has completed. Also, if you acquire information about the existence of a call over another channel (RTE, webhooks) that exposes information about ongoing calls as well, handling ongoing calls separately may be necessary.

GET /servicecall

Get all inbound servicecalls in a time range

GET /servicecall/?StartTime=2015-02-01+00%3A00%3A00
&EndTime=2015-02-02+00%3A00%3A00

Returns a list of service call events matching filter specified by query parameter

• Query parameters: ServiceCallFilterParameters
• Request content: none
• Response content: List<ServiceCall>

GET /servicecall/{callId}

Returns information about a specific service call only

• Url parameter: {callId} - id of call
• Query parameters: none
• Request content: none
• Response content: ServiceCall

GET servicecall/{callId}/details

Returns a list of detailed events relating to a single call.

• Url parameter: {callId} - id of call
• Query parameters: none
• Request content: none
• Response content: List<ServiceCallDetail>

ServiceCall

Header information for a service call. Service calls are calls made to service pools and are represented in more detail than simple CallEvents.

{
    "ANum": "+358501231234",
    "AnswerQueueId": "C0A7E3FB-56D2-4079-AAE8-25B0630406FD",
    "AnswerQueueName": "Support (FI)",
    "AnswerTime": "2015-02-02T06:15:27Z",
    "AnsweringUserId": "D716DC55-4C78-4CE9-933F-AA9B08E66940",
    "AnsweringUserName": "User Name",
    "BNum": "+358101231234",
    "DisconnectTime": "2015-02-02T06:16:32Z",
    "EntryQueueId": "FF2F680F-184F-470A-AF86-D50B8C5B3CC6",
    "EntryQueueName": "Switchboard IVR",
    "Id": "bec058a6-74da-4dc6-8402-74d6a1a02880",
    "LastEventTime": "2015-02-02T06:16:32Z",
    "LastQueueId": "C0A7E3FB-56D2-4079-AAE8-25B0630406FD",
    "LastQueueName": "Support (FI)",
    "OrganizationId": "d6838fc1-d649-e211-9c34-005056aa29fb",
    "Result": 0,
    "Timestamp": "2015-02-02T06:15:01Z",
    "Modified": "2015-02-02T06:15:03Z",
    "WaitTime": "00:00:25.847"
}

<ServiceCall>
    <ANum>+358501231234</ANum>
    <AnswerQueueId>C0A7E3FB-56D2-4079-AAE8-25B0630406FD</AnswerQueueId>
    <AnswerQueueName>Support (FI)</AnswerQueueName>
    <AnswerTime>2015-02-02T06:15:27.03</AnswerTime>
    <AnsweringUserId>D716DC55-4C78-4CE9-933F-AA9B08E66940</AnsweringUserId>
    <AnsweringUserName>User Name</AnsweringUserName>
    <BNum>+358101231234</BNum>
    <DisconnectTime>2015-02-02T06:16:32.27</DisconnectTime>
    <EntryQueueId>FF2F680F-184F-470A-AF86-D50B8C5B3CC6</EntryQueueId>
    <EntryQueueName>Switchboard IVR</EntryQueueName>
    <Id>bec058a6-74da-4dc6-8402-74d6a1a02880</Id>
    <LastEventTime>2015-02-02T06:16:32.27</LastEventTime>
    <LastQueueId>C0A7E3FB-56D2-4079-AAE8-25B0630406FD</LastQueueId>
    <LastQueueName>Support (FI)</LastQueueName>
    <Modified>2015-02-02T06:15:03.311</Modified>
    <OrganizationId>d6838fc1-d649-e211-9c34-005056aa29fb</OrganizationId>
    <Result>Answered</Result>
    <Timestamp>2015-02-02T06:15:01.183</Timestamp>
    <WaitTime>PT25.847S</WaitTime>
</ServiceCall>

ServiceCallResultType

Enum describes possible call results.

UserRoleInCall

Enum describes the roles a user can be in a single call. Used in ServiceCallFilterParameters.

ServiceCallFilterParameters

Filter object used for searching ServiceCalls. Can contain relevant information such as arrival queue, agent role in call etc in addition to basic timestamp-like information. It is serialized as query parameter when making calls to service call resource.

Sample usage, find calls in time range answered by a specific user

?StartTime=2015-02-01+00%3A00%3A00
&EndTime=2015-02-02+00%3A00%3A00
&CallResult=Answered
&UserRole=Answered
&Users=D716DC55-4C78-4CE9-933F-AA9B08E66940

ServiceCallDetail

Sample list of service call detail events for a single call

[
    {
        "Id": "8232c9d2-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:15.093Z",
        "EventTypeId": 1,
        "EventType": "CallConnect",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": null,
        "userName": null,
        "Reason": "ServiceQueue",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    },
    {
        "Id": "8432c9d2-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:15.297Z",
        "EventTypeId": 100,
        "EventType": "QueueArrive",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": null,
        "userName": null,
        "Reason": "ServiceQueue",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    },
    {
        "Id": "8532c9d2-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:15.343Z",
        "EventTypeId": 200,
        "EventType": "QueueAllocateUser",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
        "userName": "User Name",
        "Reason": "ServiceQueue",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    },
    {
        "Id": "8732c9d2-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:19.357Z",
        "EventTypeId": 201,
        "EventType": "UserAnswer",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
        "userName": "User Name",
        "Reason": "ServiceQueue",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    },
    {
        "Id": "266376db-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:29.653Z",
        "EventTypeId": 410,
        "EventType": "WrapUpStarted",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
        "userName": "User Name",
        "Reason": null,
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    },
    {
        "Id": "276376db-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:29.657Z",
        "EventTypeId": 7,
        "EventType": "Recording",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
        "userName": "User Name",
        "Reason": "servicequeue",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [
            {
                "RecordingId": "2c6376db-9d58-ef11-9949-005056895f22",
                "CanRead": false
            }
        ],
        "Transcripts": [
            {
                "TranscriptId": "ccefe498-51c1-4eed-dd6d-08dcba9cdc7d",
                "CanRead": false
            }
        ]
    },
    {
        "Id": "286376db-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:29.66Z",
        "EventTypeId": 2,
        "EventType": "CallDisconnect",
        "QueueId": null,
        "QueueName": null,
        "UserId": null,
        "userName": null,
        "Reason": "",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    },
    {
        "Id": "315165ed-9d58-ef11-9949-005056895f22",
        "CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
        "Timestamp": "2024-08-12T11:27:59.763Z",
        "EventTypeId": 411,
        "EventType": "WrapUpTerminated",
        "QueueId": "77c4f037-3811-ec11-9929-005056895f22",
        "QueueName": "Queue Name",
        "UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
        "userName": "User Name",
        "Reason": "timer",
        "RecordingId": null,
        "TranscriptId": null,
        "Recordings": [],
        "Transcripts": []
    }
]   

Detailed step information for a call. A number of these are nested under a single ServiceCall, representing individual steps a call takes inside the system (arrive, get allocated, answered etc.)

ServiceCallEventType

Enum describes different event types that ServiceCallDetail events can have. Each type has a Reason field that can contain additional information about the event. The content depends on the event type.

ServiceCallOrderBy

Enum describes sort order.

Outbound service call information

When a user makes an outbound call, the call is by default considered a user call). In some cases, however, the call is signalled (usually before the call is initialized) to instead be an outbound service call.

There are two types of outbound service calls: Outbound queue calls and outbound callback calls

Outbound queue call

Outbound queue calls are initiated by the user, but are partially taken over by the service queue on behalf of which the call is made. Usually, the agent chooses to call on behalf of a queue, for example to contact customers without exposing their own identity. The process can be automatic as wel depending on configuration.

Outbound queue calls are recorded based on queue configuration, and the resulting call information as well as the recording belong primarily to the queue.

GET /outbound-servicecall

Looks up outbound service calls

• Query parameters: OutboundServiceCallFilter
• Request content: none
• Response content: List<OutboundServiceCall>

GET /outbound-servicecall/{id}

Returns a specific outbound service call by id

• Query parameters: none
• Request content: none
• Response content: OutboundServiceCall

OutboundServiceCall

Outbound service call made on behalf of a queue

{
    "Id": "bec058a6-74da-4dc6-8402-74d6a1a02880",
    "CallId": "85c0f45f-ddae-49bc-adab-023502b41688",
    "DisplayNumber": "+4613129399232",
    "DurationSeconds": 66,
    "QueueId": "ca251a76-73e2-4c3c-96d2-2d61e49b2eaf",
    "QueueName": "Support (FI)",
    "RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
    "TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
    "Recordings": [
      {
        "CanRead": true,
        "RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
      }
    ],
    "Transcripts": [
      {
        "CanRead": true,
        "TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
      }
    ],
    "ResultType": "Answered",
    "TargetNumber": "+35810110010",
    "Timestamp": "2023-01-01T01:33:55Z",
    "Modified": "2023-01-01T01:34:01Z",
    "UserId": "66a62777-3785-4744-be15-4c9988457519",
    "Username": "some.user@customer.com",
    "WaitTimeSeconds": 12
}

OutboundServiceCallResult

Possible result types for the OutboundServiceCall

OutboundServiceCallFilter

Filter object to be used when looking up outbound service calls

Outbound callback call

Outbound callback calls are made to handle a pending callback request. The agent indicates they are calling to handle a specific request, and the call is taken over by the correspoding callback list and its configuration.

Outbound callback calls are recorded based on list configuration. The resulting call information as well as the recording belong primarily to the callback list.

GET /outbound-callbackcall

Searches outbound callback calls

• Query parameters: OutboundCallbackFilter
• Request content: none
• Response content: List<OutboundCallbackCall>

GET /outbound-callbackcall/{id}

Returns a single outbound callback call by id or 404

• Query parameters: none
• Request content: none
• Response content: OutboundCallbackCall

OutboundCallbackCall

{
    "Id": "bec058a6-74da-4dc6-8402-74d6a1a02880",
    "CallbackListId": "78c79e79-32c7-4a76-9513-6fc5ca0227d6",
    "CallbackListName": "Back Office FI",
    "CallbackRequestId": "a014b3ba-1569-4798-b699-98b9601fe291",
    "CallId": "85c0f45f-ddae-49bc-adab-023502b41688",
    "DisplayNumber": "+4613129399232",
    "DurationSeconds": 66,
    "RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
    "TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
    "Recordings": [
      {
        "CanRead": true,
        "RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
      }
    ],
    "Transcripts": [
      {
        "CanRead": true,
        "TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
      }
    ],
    "ResultType": "Answered",
    "TargetNumber": "+35810110010",
    "Timestamp": "2023-01-01T01:33:55Z",
    "Modified": "2023-01-01T01:35:22Z",
    "UserId": "66a62777-3785-4744-be15-4c9988457519",
    "Username": "some.user@customer.com",
    "WaitTimeSeconds": 12
}

Outbound call relating to a specific callback item

OutboundCallbackCallResult

Possible result types for the OutboundCallbackCall

OutboundCallbackFilter

Filter object for looking up outbound callback calls

Sample usage, find succesfull outbouncd callbackcalls in time range from specific list

?StartTime=2023-02-01+00%3A00%3A00
&EndTime=2023-02-02+00%3A00%3A00
&Result=Answered
&CallbackListIds=D716DC55-4C78-4CE9-933F-AA9B08E66940

Queue information

Entities related to service pools/queues, agents attached to them and relevant statuses.

Authorization

Queue entities cannot currently be managed via API, they are read only.

QueueUser entities can be managed and require permissions on both targeted queue and user.

There are two related PermissionKeywords:

• Queue
  • Read - View queue and its information
  • Update - Update QueueUsers mapped to the queue, in combination with separate QueueUser permission
  • Create and Delete are not used
• QueueUser
  • Create and Delete are required on target user to add/remove relevant QueueUser entity completely in addition to having Queue Update on target queue
  • Read allows reading the entities
  • Update allows updating Priority and Activity properties of QueueUser entity

GET /queues

• Url parameters: none
• Query parameters: QueueFilterParameters
• Request content: none
• Response content: List<Queue>

Returns a list of all authorized queues, meaning all queues user has Queue Read permission to.

If OnlyForUser parameter is specified, requester must have QueueUser Read on target user. Otherwise 401 will be returned.

QueueUser property for Queue entity is not populated in this resource.

QueueFilterParameters

Filter object for queue listing resource.

GET /queues/{queueid}

• Url parameters: queueid - target queue
• Query parameters: none
• Request content: none
• Response content: Queue

Requires Queue Read permission on targeted queue.

Returns a single queue with QueueUser property populated.

POST /queues/{queueid}/queueusers

• Url parameters: queueid - target queue
• Query parameters: none
• Request content: List<QueueUserUpdate> - queue users to update
• Response content: List<QueueUser> - updated queue users

Updates a collection of QueueUsers received in body. Missing entities are created and existing ones updated.

Requires a Queue Update permission on target queue and QueueUser Create/Update on target users.

DELETE /queues/{queueid}/queueusers/{userid}

• Url parameters:
  • queueid - targeted queue
  • userid - targeted user
• Query parameters: none
• Request content: none
• Response content: QueueUser - deleted user

Completely removes targeted QueueUser entity.

Requires a Queue Update permission on target queue and QueueUser Delete on target user.

GET /users/{userid}/queues

• Url parameters: userid - targeted user
• Query parameters: UserQueueFilterParameters
• Request content: none
• Response content: List<QueueUser>

From users personal perspective, returns a list of all authorized QueueUser entities for the user.

Requires a QueueUser Read permission on targeted user.

UserQueueFilterParameters

Filter for endpoint returning QueueUser mappings

POST /users/{userid}/queues

Example updating single queue activity

POST /users/974ae113-5ea1-e411-9536-00155d000507/queues/ HTTP/1.1
Date: 2016-02-12 14:09:57 GMT
Content-type: application/json
Accept: application/json

[{"QueueId":"1F03A1C1-A3AB-E411-9536-00155D000507", "UserId":"974ae113-5ea1-e411
-9536-00155d000507", "Active":true}]


HTTP/1.1 200
Content-Length: 194
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Feb 2016 14:09:38 GMT

[{"Active":true,"AvailabilityEvents":null,"Priority":100,"Queue":null,"QueueId":
"1f03a1c1-a3ab-e411-9536-00155d000507","Status":null,"User":null,"UserId":"974ae
113-5ea1-e411-9536-00155d000507"}]

• Url parameters: userid - targeted user
• Query parameters: none
• Request content: List<QueueUserUpdate>
• Response content: List<QueueUser>

Updates the entire collection of users personal QueueUser entities. Looks at received QueueUser collection, compares them to the existing ones and changes the matching ones. Ones missing from backend are not created, and existing ones missing from input are not deleted.

Requires a QueueUser Update permission on targeted user. No permission on target Queue is required. Does not allow changing Priority property.

GET /queues/{queueid}/configuration

Returns the QueueConfiguration for given queue.

• Url parameters: queueid
• Query parameters: none
• Request content: none
• Response content: QueueConfiguration
• Response codes:
  • 403 Forbidden - When user is not authorized to access the queue

PUT /queues/{queueid}/configuration

Updates the QueueConfiguration for given queue.

• Url parameters: queueid
• Query parameters: none
• Request content: QueueConfiguration - values to update (only non-null fields are updated)
• Response content: QueueConfiguration - updated values
• Response codes:
  • 400 Bad Request - When some updated property is invalid
  • 403 Forbidden - When user is not authorized to access the queue

GET /queuegroups

Returns list of queue qroups. Returns NotFound if no queue groups exist. If QueueIds is null or empty then no queues are attached to the group.

• Url parameters: none
• Request content: none
• Response content: List<QueueGroup>

[
    {
        "Name": "Group 1",
        "Description": "Description 1",
        "QueueIds": [
            "9f8ff7a2-b2c3-4cda-917a-b31815a47d78"
        ]
    },
    {
        "Name": "Group 2",
        "Description": "",
        "QueueIds": null,
    }
]

GET /queuegroups/{groupid}

Returns a queue qroup. Returns NotFound if no queue group exist. If QueueIds is null or empty then no queues are attached to the group.

• Url parameters: none
• Request content: none
• Response content: QueueGroup

{
    "Name": "Group 1",
    "Description": "Description 1",
    "QueueIds": [
        "9f8ff7a2-b2c3-4cda-917a-b31815a47d78"
    ]
}

POST /queuegroups

Creates a new queue qroup. Can be used to create a single group or create a single group and also attach the queues to the group at the same time by giving the queue ids. Returns BadRequest if group cannot be created. Calling user has to have permission to create the group. Does not allow to create a group with existing group name.

• Url parameters: none
• Request content: QueueGroup
• Response content: QueueGroup

{
    "Name": "Group 3",
    "Description": "Description 3",
    "QueueIds": [
        "9f8ff7a2-b2c3-4cda-917a-b31815a47d78"
    ]
}

PUT /queuegroups/{groupid}

Updates a existing queue qroup. Can be used to update a single groups properties and attach the queues to the group by giving the queue ids. If QueueIds is null then no action is taken updating the queues. If QueueIds is empty then queue attachment is cleared. If QueueIds contains ids then queue attachments is cleared and replaced with the new ids. Returns BadRequest if group cannot be updated. Calling user has to have permission to update the group. Does not update a group name to a existing group name.

• Url parameters: none
• Request content: QueueGroup
• Response content: QueueGroup

{
    "Name": "Renamed group",
    "QueueIds": [
        "9f8ff7a2-b2c3-4cda-917a-b31815a47d78",
        "5623241e-624f-4b9a-a663-b24bd3735a24"
    ]
}

DELETE /queuegroups/{groupid}

Deletes a existing queue qroup. Returns BadRequest if group cannot be deleted. Calling user has to have permission to delete the group.

• Url parameters: none
• Request content: none
• Response content: QueueGroup

POST /queuegroups/{groupid}/activate/{userId}

Looks up all the queues in target group that the target user is a member of and activates the user in those queues.

QueueUser.Update permission on target user is required.

• Url parameters:
  • groupId - Queue group id
  • userId - User to activate
• Request content: none
• Response content: List<QueueUser>

POST /queuegroups/{groupid}/deactivate/{userId}

Looks up all the queues in target group that the target user is a member of and deactivates the user in those queues.

QueueUser.Update permission on target user is required.

• Url parameters:
  • groupId - Queue group id
  • userId - User to activate
• Request content: none
• Response content: List<QueueUser>

Queue

{
    "Status": {
        "QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
        "OngoingCalls": 0,
        "QueueLength": 0,
        "ActiveAgents": 1,
        "FreeAgents": 1,
        "MaxWaitTime": 0,
        "ServingAgents": 1,
        "OpenStatus": 5
    },
    "TypeId": 4,
    "QueueUser": null,
    "UsePriorities": true,
    "CallAgeBonus": 100,
    "Numbers": [
     "+358100980900"
    ],
    "OrganizationalUnitId": "7af5db69-d038-4723-9a0b-7db10878fb99",
    "Id": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
    "Name": "Some queue",
    "CanUpdate": true
}

Represents a single queue in the system. Contains id, name, numbers and other related information. Also possibly contains a list of attached agents, and a QueueStatus entity.

QueueConfiguration

{
    "QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
    "QueueName": "Some queue",
    "CanUpdate": true,
    "CallAgeBonus": 100
}

DTO for configuring basic properties of a queue

QueueTypes

Enumeration of possible queue types

QueueStatus

{
    "QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
    "OngoingCalls": 0,
    "QueueLength": 0,
    "ActiveAgents": 1,
    "FreeAgents": 1,
    "MaxWaitTime": 0,
    "ServingAgents": 1,
    "OpenStatus": 3,
    "AgentsOnWrapUp" : 0
}

Represents current status of a queue. Displays number of active calls, agents, maximum wait time etc.

QueueOpenStatus

Enumeration for QueueStatus.OpenStatus. Status info is rather detailed, representing uncertainness when there is some around due to scripted interactions, dynamic lookups etc.

QueueUser

{
    "Status": {
        "Available": true,
        "Serving": true,
        "Schedule": true,
        "Talking": false,
        "ParkedCalls": 0,
        "CanBeAllocatedTo": true,
        "ServiceTerminals": 2
    },
    "Priority": 500,
    "QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
    "UserId": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
    "Queue": null,
    "AvailabilityEvents": [
        {
            "Note": null,
            "EndDate": null,
            "StartDate": null,
            "TransferNumber": null,
            "Timestamp": "2016-02-12T07:03:55Z",
            "UserID": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
            "PresenceTypeID": 0,
            "EventSourceCategory": null,
            "EventSourceCategoryID": 0,
            "EventSource": null,
            "EventSourceID": 0,
            "TransferTargetID": 0,
            "EventTypeID": 0,
            "Id": null
        }
    ],
    "User": {
        "UserName": null,
        "Name": "Test User",
        "FirstName": null,
        "Settings": null,
        "OrganizationID": "00000000-0000-0000-0000-000000000000",
        "LastName": null,
        "Id": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
        "Email": "test.user@test.com"
    },
    "Active": true
}

Represents a queue-user attachment, meaning a single user being attached to a single queue. Contains information related to the attachment, such as activity flag, priority and UserStatus entity.

Delivered containing either QueueId only or also Queue, depending on the point of view of the retrieval operation. When retriveving QueueUsers for a specific user, Queue is set but when retrieving them for a Queue, having full Queue here would be redundant

QueueUserUpdate

{
    "Priority": 500,
    "QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
    "UserId": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
    "Active": true
}

Represents a queue-user update information.

UserStatus

{
    "UserId": "82f46bf4-93c1-4336-85ee-3ff472fc2f58",
    "Available": true,
    "Serving": true,
    "Schedule": true,
    "Talking": false,
    "TalkingStatusChanged": null,
    "ParkedCalls": 0,
    "CanBeAllocatedTo": true,
    "ServiceTerminals": 2,
    "WrapUpStart": null,
    "WrapUpEnd": null,
    "ServingCallback": null,
    "ActiveQueueId": null
}

Represents users status from queue components view. Contains information about users serving status, such as talking, available and the ultimate “can receive calls” result.

QueueGroup

Represents a single queue group in the system. Contains id, name, description. Also possibly contains a list of attached queues.

User information

Things related to user-specific functionality.

Authorization

Accessing users is authorized with User.READ permission. Usually, users have this access to all other users in their organization.

GET /users

Returns a list of all authorized users, optionally filtered by query parameters.

• Url parameters: none
• Query parameters: UserFilterParameters
• Request content: none
• Response content: List<User>

GET /users/{userid}

Returns a single user by id.

• Url parameters: userid - target user
• Query parameters: none
• Request content: none
• Response content: User

User

{
    "Id": "74b14bc1-2f08-464a-bd7c-7329ad007c08",
    "UserName": "test.user@test.com",
    "Email": "test.user@test.com",
    "Name": "Test User",
    "FirstName": "Test",
    "LastName": "User",
    "OrganizationID": "acc3ecfc-264a-4d30-a736-3d17797d5a37"
}

User entity represents a single system user. It contains general information about the user, like name, email and id.

UserFilterParameters

UserFilterParameters is passed as query parameters to user resource to allow searching for users based on given conditions, like emails or organization ids.

Availability information

Things related to user availability and terminal status.

• User availability: Is user available for communication or not. Calls does not affect user availability
• Terminal status: Is there ongoing call

Authorization

All resources operate on Availability permission. Operations require read, create, update, delete permissions on targeted user accordingly.

GET /users/{userid}/availability/current

Example result for a user who's currently having lunch

[{
    "Note": "Lunch",
    "EndDate": "/Date(1455522300000+0200)/",
    "StartDate": "/Date(1455520500000+0200)/",
    "TransferNumber": null,
    "Timestamp": "/Date(1455519988447+0200)/",
    "UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
    "PresenceTypeID": 0,
    "EventSourceCategory": "User",
    "EventSourceCategoryID": 1,
    "EventSource": "SomeUI",
    "EventSourceID": 2,
    "TransferTargetID": 1,
    "EventTypeID": 3,
    "Id": "59464b6f-c3d3-e511-874c-00155d000507",
    "IsActive": true,
    "IsUpcoming": false
}]

• Url parameters: userid - targeted user
• Query parameters: AvailabilityFilterParameters
• Request content: none
• Response content: List<AvailabilityEvent>

Returns currently active availability events, optionally filtered by parameters. This is the appropriate endpoint if you only need the user's current availability.

GET /users/{userid}/availability/active

Example result for a user who's currently having lunch and has a meeting later in the afternoon

[{
    "Note": "Meeting",
    "EndDate": "2016-02-15T12:00:00Z",
    "StartDate": "2016-02-15T11:15:00Z",
    "TransferNumber": null,
    "Timestamp": "2016-02-15T09:23:50Z",
    "UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
    "PresenceTypeID": 0,
    "EventSourceCategory": "User",
    "EventSourceCategoryID": 1,
    "EventSource": "SomeUI",
    "EventSourceID": 2,
    "TransferTargetID": 1,
    "EventTypeID": 2,
    "Id": "2cd78edc-c5d3-e511-874c-00155d000507",
    "IsActive": false,
    "IsUpcoming": true
},
{
    "Note": "Lunch",
    "EndDate": "2016-02-15T09:45:00Z",
    "StartDate": "2016-02-15T09:15:00Z",
    "TransferNumber": null,
    "Timestamp": "2016-02-15T09:06:28Z",
    "UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
    "PresenceTypeID": 0,
    "EventSourceCategory": "User",
    "EventSourceCategoryID": 1,
    "EventSource": "SomeUI",
    "EventSourceID": 2,
    "TransferTargetID": 1,
    "EventTypeID": 3,
    "Id": "59464b6f-c3d3-e511-874c-00155d000507",
    "IsActive": true,
    "IsUpcoming": false
}]

• Url parameters: userid - targeted user
• Query parameters: AvailabilityFilterParameters
• Request content: none
• Response content: List<AvailabilityEvent>

Returns currently active and upcoming availability events, optionally filtered by parameters. Use this endpoint only if you require information about the upcoming availabilities as well.

POST /users/{userid}/availability

Example POSTing a new continous OffWork event

POST /users/c24a0acb-8fd1-e511-874c-00155d000507/availability HTTP/1.1
Date: 2016-02-15 10:17:33 GMT
Content-type: application/json
Authorization: BeneAPI dGVzdC51c2VyQHRlc3QuY29tOmcwS01XYUlEZGRWcHZoRE82TFcrZUVNS
URjZz0=
Accept: application/json

{ "Note":"I am gone.", "EventTypeID":3, "EventSource":"Test application", "UserI
D":"c24a0acb-8fd1-e511-874c-00155d000507"}

HTTP/1.1 200 OK
Content-Length: 354
Content-Type: application/json; charset=utf-8
Date: Mon, 15 Feb 2016 10:17:14 GMT

{"EndDate":null,"EventSource":"Test application","EventSourceCategory":"User","E
ventSourceCategoryID":0,"EventSourceID":0,"EventTypeID":3,"Id":null,"Note":"I am
 gone.","PresenceTypeID":0,"StartDate":"\/Date(1455531434789)\/","Timestamp":"\/
Date(1455531434805)\/","TransferNumber":null,"TransferTargetID":0,"UserID":"c24a
0acb-8fd1-e511-874c-00155d000507","IsActive":true,"IsUpcoming":false}

• Url parameters: userid - targeted user
• Query parameters: none
• Request content: AvailabilityEvent
• Response content: AvailabilityEvent - created event

Resource for creating new availability events.

EventSource property must specify integrating application's identifier, e.g. CustomCRMClient 0.1.3. This is a free string, but should be identifiable for possible troubleshooting needs.

If created event starts later, StartDate should be specified. If it's meant to begin right away, StartDate should be left null, making the server use current server time instead.

GET /users/{userid}/availability/{eventid}

• Url parameters:
  • userid - targeted user
  • eventid - target event
• Query parameters: none
• Request content: none
• Response content: AvailabilityEvent

Returns a single availability event by id.

PUT /users/{userid}/availability/{eventid}

• Url parameters:
  • userid - targeted user
  • eventid - target event
• Query parameters: none
• Request content: AvailabilityEvent - new info
• Response content: AvailabilityEvent - updated info

Updates target event with data from request body.

DELETE /users/{userid}/availability/{eventid}

• Url parameters:
  • userid - targeted user
  • eventid - target event
• Query parameters: none
• Request content: none
• Response content: AvailabilityEvent - deleted event

Completely deletes target availability event. Generally status should always be changed by POSTing a new availability, as simply deleting target availability can in some cases lead to unexpected resulting states for example with working hours handling.

GET /availability/

• Url parameters: none
• Query parameters: AvailabilityBulkFilterParameters
• Request content: none
• Response content: List<AvailabilityEvent>

Special resource for acquiring AvailabilityEvents for multiple users simultaneously. It can be used in cases where targeted users have been specified via some channel (for example directory synchronization) and live updating is only needed for availability information.

Requires that UserIds parameter is specified in query parameters.

AvailabilityEvent

Example, implicit available when nothing else is specified

{
    "Note": null,
    "EndDate": null,
    "StartDate": null,
    "TransferNumber": null,
    "Timestamp": "2016-02-15T09:06:34Z",
    "UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
    "PresenceTypeID": 0,
    "EventSourceCategory": null,
    "EventSourceCategoryID": 0,
    "EventSource": null,
    "EventSourceID": 0,
    "TransferTargetID": 0,
    "EventTypeID": 0,
    "Id": null,
    "IsActive": true,
    "IsUpcoming": false
}

Example, 30-minute lunch OffWork availability

{
    "Note": "Lunch",
    "EndDate": "2016-02-15T09:45:00Z",
    "StartDate": "2016-02-15T09:15:00Z",
    "TransferNumber": null,
    "Timestamp": "2016-02-15T09:06:28Z",
    "UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
    "PresenceTypeID": 0,
    "EventSourceCategory": "User",
    "EventSourceCategoryID": 1,
    "EventSource": "SomeUI",
    "EventSourceID": 2,
    "TransferTargetID": 1,
    "EventTypeID": 3,
    "Id": "59464b6f-c3d3-e511-874c-00155d000507",
    "IsActive": true,
    "IsUpcoming": false
}

Example active call on a mobile terminal

{
    "EndDate": null,
    "EventSource": "AVA",
    "EventSourceCategory": "Call",
    "EventSourceCategoryID": 2,
    "EventSourceID": 8,
    "EventTypeID": 1,
    "Id": "ff3c28d8-00ad-e811-982e-005056aa29fb",
    "IsActive": true,
    "IsUpcoming": false,
    "Note": null,
    "PresenceTypeID": 1,
    "StartDate": "2018-08-31T09:33:01Z",
    "Timestamp": "2018-08-31T09:33:01Z",
    "TransferNumber": null,
    "TransferTargetID": 1,
    "UserID": "c24a0acb-8fd1-e511-874c-00155d000507"
}

Represents a single availability event for user. Contains information such as start and end time and event type (do not disturb, off work, ..). Also includes terminal statuses for user (ongoing call in mobile, MS Teams, etc. terminals).

EventTypeID

Base types availability events can describe. These relate to displayed availability, call control etc.