Connecting to API

This API is based on REST principles.

API authentication

We use HTTP Basic authentication where username is the api key and password is the calculated request signature that changes with every request. The secret should never be sent, instead it's used to generate the request signature. Api key and secret can be generated in our Admin.

The signature is a hex-encoded HMAC-SHA1 hash calculated from the canonical request using provided secret.

Canonical request takes form of {http method} {complete request path} {unix timestamp}, e.g. GET /v1/some/url?attributes=123&some=aaa 1548240417

PHP example

$time = time();
$method = 'GET';
$path = '/v1/user';
$api = '';
$apiKey = 'ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l';
$secret = 'ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq';
$canonicalRequest = sprintf('%s %s %s', $method, $path, $time);
$signature = hash_hmac('sha1', $canonicalRequest, $secret);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, sprintf('%s:%s', $api, $path));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $apiKey.':'.$signature);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Date: ' . gmdate('Ymd\THis\Z', $time),
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$response = curl_exec($ch);
echo $response;

Python example

import hmac
import hashlib
import time
import requests
import base64
from datetime import datetime
method = "GET"
path = "/v1/user/self"
timestamp = int(time.time())
api = ""
apiKey = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l"
secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq"
canonicalRequest = "%s %s %s" % (method, path, timestamp)
signature =, canonicalRequest.encode('utf-8'), hashlib.sha1).hexdigest()
headers = {
    "Authorization": "Basic %s" % (base64.b64encode("%s:%s" % (apiKey, signature))),
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Date": datetime.fromtimestamp(timestamp).isoformat()
print requests.get("%s%s" % (api, path), headers=headers).content

Please add Authorization: header to all requests. Example: Authorization: Basic aHR0cHdhdGNoOmY= (last string is base64 encoded version of <apiKey>:<signature>) Additionally all request must contain a valid Date header with the time used for the signature in the ISO8601 basic format, in the GMT timezone.

Connection is encrypted with SSL, so all your requests are safe.

Deprecation notice

Legacy authentication using plain username and password remains functional but will be removed in a forthcoming future. Please updated your clients as soon as possible.

Request and response formats

This API is using JSON format in both directions. Please add these two headers to your request:

The communication through API is using UTF-8 encoding.

Allowed HTTPs requests

Most frequent server response descriptions

Messages above 400 are in the following format:

response 400

    "code": 400,
    "message": "This is an example error message!"


API supports different languages in validation messages. You can change language with header Accept-Language: en_us. Supported languages are: en_us, sk, cs_cz, hu.