To access an API interface in the Dstny Core an authentication, based on the API tickets, needs to be done.

A ticket can be granted for one or several API scopes

• Contact search
• Call setup
• User info
• Queue statistics
• Event channel
• SMS sending
• ACD/attendant queues
• Reports
• Communication Log
• Personal contacts
• Call control
• Call recording
• Line state
• Voicemail settings

These APIs can only be reached from a user’s token. For example, a superuser cannot use the Contact search API. The token is obtained by creating a ticket in the Dstny Core and is valid for a year.

The authentication is done by setting Bearer {token} as the value in Authorization in the header.

The Core API uses the following HTTP methods for manipulating data

• GET – read data from a resource, subscribe to data from a resource
• POST – create a resource
• PUT – update a resource
• DELETE – remove a resource

HTTP clients who are unable to use PUT or DELETE HTTP operations should translate PUT and DELETE to POST operations with an additional X-HTTP-Method-Override header, for example:

• POST /… HTTP/1.1 X-HTTP-Method-Override:PUT Core responds to POST+X-HTTP-Method-Override request as if the content of the X-HTTP-Method-Override header was the actual HTTP operation requested.

All requests must have the HTTP-headers Content-Type and Accept set to an applicable value according to the respective operation, e.g. application/json or application/xml.

https://bc.dstny.se/api or https://bc2.dstny.se/api

When using non-7-bit ASCII characters in URIs, they need to be percent-encoded by using UTF-8. For example, to create a user group named mötley crüe, use the following URL:

• http://{base url}/api/admin/organization/test.com/userGroups/m%C3%B6tley%20cr%C3%BCe

Never use a newline (line break) within a name. The newlines will then become part of the name. This applies to all data; names and functions. Boolean data types only have the legal literals in lower case (true, false).

It is preferred to use JSON instead of XML to access all APIs. For example:

• http://{base url}/api/event/v1/domain.com/user

New operations have primarily support for JSON, older operations have support for both JSON and XML. XML shall be seen as a deprecated format and will be removed in the coming releases. Only Core JSON version 2 is supported from 5.1, “jsonver=2” can still be used but is not needed.

Core returns the following HTTP error response codes when encountering problems:

400     Bad Request – When receiving an invalid request URI, invalid HTTP header, or invalid message body. Usually including a body consisting of validation result.

401     Not Authorized – When missing authorization credentials or not authorized to access the requested resource.

403     Forbidden – The server authorizes the request, but it is forbidden to be fulfilled. The authorization will not help. The current authorization context does not allow the request.

404     Found – The server does not find the resource that matches the request URI.

405     Method Not Allowed – The method specified in the request is not allowed for the resource identified by the request.

406     Not Acceptable – The request does not meet the response that the method can provide. An example is when Accept header demands XML while the method can provide only JSON.

409     Conflict – The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.

500     Internal Server Error – This is the default code that is used for all unrecognized errors.

501     Not Implemented – The request was valid but has not yet been implemented by Core.

503     Service Unavailable – A Management Node responds with a 503 response code along with a custom header X-Telepo-Server-Status, when the node is not in READY state. The below are the possible values in a 503 response:
        - STARTING – The node is starting
        - STARTED – The node is started, but has not reached the READY state (e.g. Management Node does not know to which Service Node an organization domain belongs)
        - SHUTTING_DOWN – The node is shutting down
        - MAINTENANCE – The node is put in maintenance 

Core may add a Warning header with warning code 703 to the response in case of errors. The header text will contain a log token in the form “Error occurred, see {token}“. More information will be available in the server log by searching for this token.

Successful requests

Depending on the operation a response body may be returned upon a successful request. See the respective operation for a description of the possible response structure. Example JSON for GET http://{base url}/api/contacts/list/company.com/john?query=doe using Content-Type: application/json:

{
"query" : "doe",
"contact" : [ {
"id" : "jane@company.com",
"firstname" : "Jane",
"lastname" : "Doe",
"company" : "Company 0120",
"presence" : { },
"inlist" : true,
"type" : "SHORTCUT",
"vcard" : 2,
"contactStatus" : "FAVORITE",
"preferredNumber" : "+1234567001"
}, {
"id" : "mac@company.com",
"firstname" : "Mac",
"lastname" : "Doe",
"company" : "Company 0120",
"presence" : { },
"inlist" : false,
"type" : "DIRECTORY",
"vcard" : 1,
"contactStatus" : "CONTACT",
"preferredNumber" : "+1234567004"
} ]
}

Failed requests

When Core returns an error response as a result of invalid input data, depending on what is set in the Accept header, it returns JSON or XML describing the reason for the error. Example JSON for validation errors http://{base url}/api/contacts/list/company.com/john?query=doe using Content-Type: application/json:

{
"field":[
        {
"fieldName":"{value}",
"code":"{value}",
"description":"{value}",
"name":"{value}"
        }
   ]
}

where {value} is replaced by:

• fieldName – the field name of the provided element that had invalid data. If it is an error that is not limited to a single field this field is not output.
• code – an error code specified in a hierarchical fashion, for example, ‘admin.user.password.invalidLength’.
• description – a human-readable description. The description can sometimes contain a log token in the form “, see {token}” in case of errors. More information about this error can then be found in the server log by searching for this token.
• name – the field contents causing the error or warning.

JSON GET Requests

All JSON GET requests must have the HTTP header Accept: application/json. Example commands for getting results in JSON:

curl -s -H "Accept: application/json" -H "Authorization: Bearer 2.VDo4YFlZjZkNGJmOTQ2Mzg2" 'http://{base url}/api/admin/user/domain.com'

wget -qO- --header="Accept": application/json" --header="Authorization: Bearer 2.VDo4YFlZjZkNGJmOTQ2Mzg2" 'http://{base url}/api/admin/user/domain.com'

JSON POST and PUT Requests

If a body is used, the request must have the HTTP header Content-Type: application/json. An example command for using JSON with POST:

curl -s -X POST -H "Accept: application/json" -H "Content- Type: application/json"  -H "Authorization: Bearer 2.VDo4YFlZjZkNGJmOTQ2Mzg2" -d'{}' 'http://{base url}/api/...'

The ACD/Attendant Group API is used to manage agent login status as well as retrieving information about groups and agents.
Use the ACD/Attendant Group API to:

• Manage login status for agents in ACD, ACD Light or Attendant group
• Retrieve information about specified ACD/Attendant group for user
• List ACD/ACD Light or Attendant groups for a user

The Distribution Group API allows the calling user to view and handle status for distribution groups (ACD, ACD Light and Attendant groups) that the user has access to, including handling call log items to these groups.
Use the Distribution Group API to:

• Log in a user to a distribution group
• Log out a user from a distribution group
• List the distribution groups available to a user
• Get the call history for a user
• Get the call history for a user for a specific distribution group
• Assign a call to a user
• List calls assigned to a user
• List calls assigned to a user for a specific distribution group
• Subscribe to queue statistics

The Queue Statistics API gives access to statistics on ACD and attendant groups. Queue statistics is authenticated using api tickets for Queue statistics.
To be able to fetch the queue statistics, the Supervisor license must be assigned to the organization.
Use the Queue Statistics API to:

• Get queue statistics for an organization
• Get queue statistics for a user
• Get queue statistics for a queue