API

The Zadarma API interface allows clients to use our service for their personal applications, and to integrate it with any CRM system as well as softphones for call centers. It is easy for a client to set up a cloud PBX and connect it with the API interface in order to integrate Zadarma’s business phone system with their own applications.

Main functions available in the API:

  • SIP account and PBX settings display and changing;
  • Statistics and balance display;
  • Calls and SMS (CallBack to internal and external numbers);
  • External server notifications for incoming calls and call routing.

API link: https://api.zadarma.com

API version: v1

Final link on method: https://api.zadarma.com/v1/METHOD/

PHP, C#, Python classes are available for download on GitHub.

Integration manual for your own CRM and Zadarma telephony

Authorization

Each authorization request should be sent with an additional header:
"Authorization: user_key: signature"

Authorization keys must be generated in your personal account.

The signature is made according to the following algorithm:

  • The array of transmitted data (GET, POST, PUT, DELETE) is sorted by the key name in alphabetical order;
  • The received array forms the query strip (for example, http_build_query function in PHP), example "from=DATEFROM&to=DATETO…";
  • It is then concatenated as follows: line = method_name request_line md5(request_line), where “method_name” is the request line after the domain (with indication of API version) till the beginning of the parameters list, for example - '/v1/sip'
  • The resulting string is hashed by the algorithm sha1 with the secret user key: hash = hash( string, secret_key )
  • And then the hash is encrypted in base64 signature = base64_encode( hash )

PHP Example:

ksort($params);

$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);

$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));

$header = 'Authorization: ' . $userKey . ':' . $sign;

You can download the complete PHP class for Zadarma API on GitHub.

The response formats: json (default) and xml.

To get the response from the API in xml format, the “format=xml” parameter must be added to the request line.

Restrictions

Each response contains information about the limits and the current request, for example:

X-Zadarma-Method: /v1/
X-RateLimit-Reset: 1434371160
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99

Where:

  • X-Zadarma-Method - current requested method;
  • X-RateLimit-Remaining - the amount of requests remaining after taking into account the method and user limits;
  • X-RateLimit-Limit - the total number of request limits per minute;
  • X-RateLimit-Reset - limit reset time.

Total limits - 100 requests per minute, for statistics methods - 10 requests per minute.

In case of blocking, the method returns the response with 429 header "You exceeded the rate limit".

The response contains a mandatory "status" key (success or error). Afterwards, depending on the method, corresponding keys are provided with the requested information.

In case of an error, additional "message" key is provided with an error description.

Also all responses are provided with corresponding HTTP-headers.

Example of an error response:

JSON:

	{
		"status":"error",
		"message":"Check phone's number"
	}

XML:

	<?xml version="1.0"?>
	<answer>
		<status>error</status>
		<message>Check phone's number</message>
	</answer>

Available methods:

  • /v1/info/balance/
    user balance.
  • /v1/info/price/
    call rate in the user's current price plan.
  • /v1/info/timezone/
    user's timezone.
  • /v1/tariff/
    information about the user's current price plan.
  • /v1/request/callback/
    callback.
  • /v1/sip/
    the list of user's SIP-numbers.
  • /v1/sip/<SIP>/status/
    The user's SIP number online status.
  • /v1/sip/callerid/
    changing of the CallerID.
  • /v1/sip/redirection/
    Display of the current call forwarding based on the user's SIP numbers.
  • /v1/direct_numbers/
    information about the user's phone numbers.
  • /v1/sip/redirection/
    call forwarding switch on/off based on the SIP number.
  • /v1/sip/redirection/
    changing of the call forwarding parameters.
  • /v1/pbx/internal/
    the PBX extension numbers display.
  • /v1/pbx/internal/<PBXSIP>/status/
    online status of the PBX extension number.
  • /v1/pbx/internal/recording/
    enabling of the call recording on the PBX extension number.
  • /v1/pbx/record/request/
    call recording file request.
  • /v1/pbx/redirection/
    changing of the call forwarding parameters on the PBX extension number.
  • /v1/pbx/redirection/
    receiving call forwarding parameters on the PBX extension number.
  • /v1/sms/send/
    sending the SMS messages.
  • /v1/statistics/
    receive overall statistics.
  • /v1/statistics/pbx/
    PBX statistics.
  • /v1/statistics/callback_widget/
    CallBack widget statistics
  • /v1/info/number_lookup/
    user database check.
  • /v1/speech_recognition/
    obtaining recognition results.
  • /v1/speech_recognition/
    start recognition.
  • JSON
  • XML
{
    "status":"success",
    "balance":10.34,
    "currency":"USD"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <balance>10.34</balance>
    <currency>USD</currency>
</answer>

Parameters:

  • number – phone number
  • caller_id (optional) – CallerID, which is used to make the call.

  • JSON
  • XML
{
    "status":"success",
    "info":{
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <prefix>4420</prefix>
        <description>United Kingdom, London</description>
        <price>0.009</price>
        <currency>USD</currency>
    </info>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "unixtime":1483228800,
    "datetime":"2017-01-01 00:00:00",
    "timezone":"UTC+0"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <unixtime>1483228800</unixtime>
    <datetime>2017-01-01 00:00:00</datetime>
    <timezone>UTC+0</timezone>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "info": {
        "tariff_id":5,
        "tariff_name":"Standart, special",
        "is_active":false,
        "cost":0,
        "currency":USD,
        "used_seconds":1643,
        "used_seconds_mobile":34,
        "used_seconds_fix":726,
        "tariff_id_for_next_period":5,
        "tariff_for_next_period":Standart, special
    }
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <tariff_id>5</tariff_id>
        <tariff_name>Standart, special</tariff_name>
        <is_active>false</is_active>
        <cost>0</cost>
        <currency>USD</currency>
        <used_seconds>1643</used_seconds>
        <used_seconds_mobile>726</used_seconds_mobile>
        <used_seconds_fix>726</used_seconds_fix>
        <tariff_id_for_next_period>5</tariff_id_for_next_period>
        <tariff_for_next_period>Standart, special</tariff_for_next_period>
    </info>
</answer>

where

  • tariff_id– user's current price plan ID;
  • tariff_name – the name of the user's current price plan;
  • is_active – the current price plan is active or inactive;
  • cost – the cost of the price plan;
  • currency – the price plan currency;
  • used_seconds – the amount of price plan seconds used;
  • used_seconds_mobile – the amount of price plan seconds used on calls to mobiles;
  • used_seconds_fix – the amount of price plan seconds used on calls to landlines;
  • tariff_id_for_next_period – the user's price plan ID for the next time period;
  • tariff_for_next_period – the name of the user's price plan for the next time period.

Parameters:

  • from – your phone/SIP number, the PBX extension number or the PBX scenario, to which the CallBack is made;
  • to – the phone or SIP number that is being called;
  • sip (optional) – SIP user's number or the PBX extension number (for example: 100), which is used to make the call. The CallerID of this number will be used; this SIP/PBX extension number will be displayed in the statistics; call recording and prefix dialling will be used if enabled for this number;

  • predicted (optional) – if this flag is specified the request is predicted (the system calls the “to” number, and only connects it to your SIP, or your phone number, if the call is successful.);
  • JSON
  • XML
{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "sips":[
        {
            "id":"00001",
            "display_name":"SIP 1",
            "lines":3
        },
        {
            "id":"00002",
            "display_name":"SIP 2",
            "lines":3
        }
    ],
    "left":3
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sips>
        <value>
            <id>00001</id>
            <display_name>SIP 1</display_name>
            <lines>3</lines>
        </value>
        <value>
            <id>00002</id>
            <display_name>SIP 2</display_name>
            <lines>3</lines>
        </value>
    </sips>
    <left>1</left>
</answer>

where

  • id– SIP ID;
  • display_name – displayed name;
  • lines – the number of lines;
  • left – the number of remaining SIPs, which can be created (depends on the user's balance and the total number of SIPs already created).
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <is_online>false</is_online>
</answer>

Parameters:

  • id – the SIP ID, which needs the CallerID to be changed;
  • number – the new (changed) phone number, in international format (from the list of confirmed or purchased phone numbers.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <new_caller_id>442037691880</new_caller_id>
</answer>

Parameters:

  • id – (optional) selection of the specific SIP ID.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
        "sip_id":"00001",
        "status":"on",
        "condition":"always",
        "destination":"phone",
        "destination_value":"442037691880",
        },
    ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <sip_id>00001</sip_id>
            <status>on</status>
            <condition>always</condition>
            <destination>phone</destination>
            <destination_value>442037691880</destination_value>
        </value>
    ...
    </info>
</answer>

where

  • sip_id – the user's SIP ID;
  • status – current status: on or off;
  • condition – call forwarding conditions: always – always (default), unavailable – when the call is unanswered or if there is no SIP connection;
  • destination – where the call is forwarded to: phone – to the phone number, pbx – to the PBX;
  • destination_value – the number for the call forwarding: phone number or the PBX ID.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Великобритания</country>
            <description>Лондон</description>
            <number_name>null</number_name>
            <sip>00001</sip>
            <sip_name>Example</sip_name>
            <start_date>2015-01-01 18:14:44</start_date>
            <stop_date>2016-02-11 18:14:40</stop_date>
            <monthly_fee>2</monthly_fee>
            <currency>USD</currency>
            <channels>2</channels>
            <autorenew>true</autorenew>
            <is_on_test>false</is_on_test>
            <type>common</type>
        </value>
    ...
    </info>
</answer>

The fields can vary depending on the number type! The fields descriptions:

  • number – the user's purchased virtual phone number;
  • status – the phone number status;
  • country – country (for common and revenue);
  • description – description: city or type (for common and revenue);
  • number_name – the virtual phone number "name" (set by the user);
  • sip – the SIP connected to the phone number;
  • sip_name – the "name" of the SIP connected to the phone number;
  • start_date – the date of purchase;
  • stop_date – the end date of the user's payment period;
  • monthly_fee – the phone number cost (for common);
  • currency – the currency of the phone number cost (for common);
  • channels – the number of lines on the phone number (for common);
  • minutes – the total duration of incoming calls for the current month (for revenue);
  • autorenew – the automatic phone number extension is enabled or disabled (for common, revenue, rufree);
  • is_on_test – the phone number is being tested or not;
  • type – phone number type: common (virtual number), inum (free international number), rufree (free Moscow number), revenue (free Moscow 495 number)

Parameters:

  • id – SIP ID;
  • status – the call forwarding status on the selected SIP number.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <current_status>on</current_status>
</answer>

Parameters:

  • id – SIP ID;
  • type – call forwarding type: phone – to the phone;
  • number – phone number.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <destination>442037691880</destination>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <numbers>
        <value>100</value>
        <value>101</value>
        ...
    </numbers>
</answer>

where

  • pbx_id – the user's PBX ID;
  • numbers – the list of extension numbers.
  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <number>100</number>
    <is_online>false</is_online>
</answer>

where

  • pbx_id – PBX ID;
  • number – PBX extension number;
  • is_online – online-status (true|false).

Parameters:

  • id – PBX extension number;
  • status – status: "on" - switch on, "off" - switch off, "on_email" - enable the option to send the recordings to the email address only, "off_email" - disable the option to send the recordings to the email address only, "on_store" - enable the option to save the recordings to the cloud, "off_store" - disable the option to save the recordings to the cloud;
  • email – (optional) change the email address, where the call recordings will be sent. You can specify up to 3 email addresses, separated by comma.
  • JSON
  • XML
{
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <internal_number>100</internal_number>
    <recording>on</recording>
    <email>on</email>
</answer>

Parameters:

  • call_id – unique call ID, it is specified in the name of the file with the call recording (unique for every recording);
  • pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications);
  • lifetime – (optional) the link's lifetime in seconds (minimum - 180, maximum - 5184000, default - 1800).

Note: It is enough to specify one of the two identification parameters (pbx_call_id or call_id), if pbx_call_id is specified, several links might be returned.

  • JSON
  • XML

Response example when only call_id is specified, only one link will be returned:

{
    "status":"success",
    "link": "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
    "lifetime_till": "2016-01-01 23:56:22"
}

Response example when only pbx_call_id is specified, several links might be returned:

{
    "status":"success",
    "links":[
        "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
        "https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
    ],
    "lifetime_till": "2016-01-01 23:56:22"
}

Response example when only call_id is specified, only one link will be returned:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Response example when only call_id is specified, several links might be returned:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <links>
        <value>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</value>
        <value>https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3</value>
    </links>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Parameters:

  • link – the link to the file with the conversation;
  • lifetime_till – until what time will the link work.

Parameters:

To switch on and set up the call forwarding:

  • pbx_number – PBX extension number, for example 100;
  • status – on;
  • type – call forwarding type: voicemail or phone type;
  • destination – phone number or email address, depending on the previous parameter;
  • condition – call forwarding condition, possible values: always or noanswer;
  • voicemail_greeting – notifications about call forwarding, possible values: no, standart, own. Specified only when type = voicemail;
  • greeting_file – file with notification in mp3 format or wav below 5 MB. Specified only when type = voicemail and voicemail_greeting = own;

To switch on the call forwarding:

  • pbx_number – PBX extension number, for example 100;
  • status – off;
  • JSON
  • XML
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

<?xml version="1.0"?>
    <answer>
    <status>success</status>
    <current_status>on</current_status>
    <pbx_id>1234</pbx_id>
    <pbx_name>100</pbx_name>
    <type>phone</type>
    <destination>79123456789</destination>
    <condition>noanswer</condition>
    </answer>

Parameters:

  • pbx_number – PBX extension number, for example 100;
  • JSON
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

Parameters:

  • number – phone number, where to send the SMS message (several numbers can be specified, separated by comma);
  • message – message (standard text limit applies; the text will be separated into several SMS messages, if the limit is exceeded);
  • caller_id – (optional) phone number, from which the SMS messages is sent (can be sent only from list of user's confirmed phone numbers).
Please note: sending SMS messages is only available outside the Russian Federation
  • JSON
  • XML
{
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <value>
        <messages>1</messages>
        <cost>0.24</cost>
        <currency>1</currency>
    </value>
</answer>

Parameters:

  • start - the start date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • end - the end date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • sip (optional) - filter based on a specific SIP number;
  • cost_only (optional) - display only the amount of funds spent during a specific period;
  • type (optional - only for the overall statistics) - request type: overall (is not specified in the request), toll and ru495. (for the toll free numbers statistics and free 495 phone numbers).
  • skip (optional - not taken into account when the parameter is cost_only) - number of lines to be skipped in the sample. The output begins from skip +1 line (used for the pagination with the limit parameter, equals to 0 by default);
  • limit (optional - not taken into account when the parameter is cost_only) - the limit on the number of input lines (used for the pagination with the skip parameter, the maximum value is 1000, the default value is 1000).

Maximum period of getting statistics is - 1 month. If the limit in the request is exceeded, the time period automatically decreases to 30 days. If the start date is not specified, the start of the current month will be selected. If the end date is not specified, the current date and time will be selected.
Maximum number of input lines for one request - 1000. For pagination use the skip and limit parameters.

  • JSON
  • XML
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":442037691880,
            "to":442037691881,
            "description":"United Kingdom, London",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"USD"
        },
        …
    ]
}

?type=cost_only:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"USD",
            "seconds":9785
        }
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 13:58:22</end>
    <stats>
        <value>
            <id>155112249</id>
            <sip>00001</sip>
            <callstart>2015-06-02 12:20:25</callstart>
            <description>United Kingdom, London</description>
            <disposition>busy</disposition>
            <billseconds>0</billseconds>
            <cost>0.195</cost>
            <billcost>0</billcost>
            <currency>USD</currency>
            <from>442037691880</from>
            <to>442037691881</to>
        </value>
        …
    </stats>
</answer>

?type=cost_only:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 14:03:30</end>
    <stats>
    <value>
        <cost>38.094</cost>
        <currency>USD</currency>
        <seconds>9785</seconds>
    </value>
    </stats>
</answer>

where

  • start – start date of the statistics display;
  • end – end date of the statistics display;
  • id – call ID;
  • sip – SIP-number;
  • callstart – the call start time;
  • description – description of call destination;
  • disposition – the call status:
    • 'answered' – conversation,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' - no answer,
    • 'failed' - failed,
    • 'no money' - no funds, the limit has been exceeded,
    • 'unallocated number' - the phone number does not exist,
    • 'no limit' - the limit has been exceeded,
    • 'no day limit' - the day limit has been exceeded,
    • 'line limit' - the line limit has been exceeded,
    • 'no money, no limit' - the limit has been exceeded;
  • billseconds – the amount of seconds;
  • cost – the cost per minute of calls to this destination;
  • billcost – the cost of the paid minutes;
  • currency – the cost currency;
  • from – which number was used to make a call;
  • to – the phone number that was called.

Parameters:

  • start - the start date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • end - the end date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • version - format of the statistics result (2 - new, 1 - old);
  • skip (optional) - number of lines to be skipped in the sample. The output begins from skip +1 line (used for the pagination with the limit parameter, equals to 0 by default);
  • limit (optional) - the limit on the number of input lines (used for the pagination with the skip parameter, the maximum value is 1000, the default value is 1000).
  • call_type (optional) - call destination ('in' for incoming, 'out' for outgoing). If not specified, all calls are displayed.
  • JSON
  • XML
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "version":2,
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-30 23:59:59</end>
        <version>2</version>
        <stats>
        <value>
            <call_id>1439981389.2702773</call_id>
            <sip>200</sip>
            <callstart>2015-06-01 15:04:00</date>
            <clid>200</clid>
            <destination>5</destination>
            <disposition>answered</disposition>
            <seconds>5</seconds>
            <is_recorded>true</is_recorded>
            <pbx_call_id>in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d</pbx_call_id>
        </value>
        …
    </stats>
</answer>

where

  • start – the start date of the statistics display;
  • end – the end date of the statistics display;
  • version - format of the statistics result (2 - new, 1 - old);
  • call_id – unique call ID, it is specified in the name of the file with the call recording (unique for every recording);
  • sip – SIP-number;
  • callstart – the call start time;
  • clid – CallerID;
  • destination – the call destination;
  • disposition – the call status:
    • 'answered' – conversation,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' - no answer,
    • 'failed' - failed,
    • 'no money' - no funds, the limit has been exceeded,
    • 'unallocated number' - the phone number does not exist,
    • 'no limit' - the limit has been exceeded,
    • 'no day limit' - the day limit has been exceeded,
    • 'line limit' - the line limit has been exceeded,
    • 'no money, no limit' - the limit has been exceeded;
  • seconds – the amount of seconds;
  • is_recorded – (true, false) recorded or no conversations;
  • pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications);

Parameters:

  • start - the start date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • end - the end date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • widget_id - (optional) - widget identification; if the parameter is not specified, statistics from all widgets is taken;
Maximum period of getting the statistics is - 1 month. If the limit in the request is exceeded, the time period automatically decreases to 30 days. If the start date is not specified, the start of the current month will be selected. If the end date is not specified, the current date and time will be selected.
Maximum number of input lines for one request - 1000. For pagination use the skip and limit parameters.
  • JSON
  • XML
{
    "status":"success",
    "start":"2016-09-01 00:00:00",
    "end":"2016-09-30 23:59:59",
    "stats":[
        {
            "id":"57d16d6a1e46c53d1f8ce323",
            "widget_id":"1",
            "sip":"00001",
            "ip":"127.0.0.1",
            "actions":[
                {
                    "kind":"come",
                    "date":"2016-09-08 16:53:45",
                    "referrer_url":"http://test.domain.com/page1/",
                    "url":"http://home.domain.com/page2/"
                },
                {
                    "kind":"show",
                    "date":"2016-09-08 16:53:46",
                    "rate":15
                },
                {
                    "kind":"call_request",
                    "date":"2016-09-08 16:54:07",
                    "number":"442037691880",
                    "request_call_date":"2016-09-09 10:00:00",
                    "redial":"n"
                },
                {
                    "kind":"close",
                    "date":"2016-09-08 16:54:35"
                }
            ]
        },
        ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2016-09-01 00:00:00</start>
    <end>2016-09-30 23:59:59</end>
    <stats>
        <value>
            <id>57d16d6a1e46c53d1f8ce323</id>
            <widget_id>1</widget_id>
            <sip>00001</sip>
            <ip>127.0.0.1</ip>
            <actions>
                <value>
                    <kind>come</kind>
                    <date>2016-09-08 16:53:45</date>
                    <referrer_url>http://test.domain.com/page1/</referrer_url>
                    <url>http://home.domain.com/page2/</url>
                </value>
                <value>
                    <kind>show</kind>
                    <date>2016-09-08 16:53:46</date>
                    <rate>15</rate>
                </value>
                <value>
                    <kind>call_request</kind>
                    <date>2016-09-08 16:54:07</date>
                    <number>442037691880</number>
                    <request_call_date>2016-09-09 10:00:00</request_call_date>
                    <redial>n</redial>
                </value>
                <value>
                    <kind>close</kind>
                    <date>2016-09-08 16:54:35</date>
                </value>
            </actions>
        </value>
            ...
    </stats>
</answer>

where

  • start – the start date of the statistics display;
  • end – the end date of the statistics display;
  • id – session ID;
  • widget_id – widget ID;
  • sip – SIP-number;
  • ip – user's IP-address;
  • kind – event type:
    • 'come' – the user visited the page with the widget,
    • 'show' – the widget form is displayed,
    • 'call' – CallBack request,
    • 'call_request' – delayed CallBack request,
    • 'rate' – the user rated the call,
    • 'fail' – the user reported that there was no CallBack,
    • 'close' – the user has closed the widget form;
  • date – the event date and time;
  • referrer_url – the URL address, from which the user came to the page with the widget(only for the event 'come');
  • url – the URL address of the widget page (only for the event 'come');
  • rate – for the event 'show' - number of points, for the event 'rate' - call rate;
  • request_call_date – the date and time for the CallBack specified by the user(only for the event 'call_request');
  • redial – (true, false) was there a CallBack for the delayed CallBack request (only for the event 'call_request');
  • number – the phone number entered by the user (for the events: 'call', 'call_request', 'rate', 'fail').

Parameters:

  • numbers – list of numbers for user database check in international format.

If numbers contain 1 number the result will be delivered immediately; if there is a list of numbers the result will be sent to the address specified on the user database check page or, if the address was not specified, to the email address.

Attention: to set up this method go to the user database check page in your personal account.

Example of the result for 1 number:


{
    "status":"success",
    "info":{
        'mcc' : '250',
        'mnc': '01',
        'mccName': 'Russia',
        'mncName': 'Mobile TeleSystems',
        'ported': false,
        'roaming': false,
        'errorDescription': 'No Error'
    }
}

Example of the result for several numbers:


{
    "status":"success"
}

Example of the result sent to the address specified on the user database check page:


{
    'success': true,
    'description': 'Проверено успешно',
    'result': [
        {
            'mcc': '250',
            'mnc': '01',
            'ported': false,
            'roaming': false,
            'errorDescription': 'No Error',
            'mccName': 'Russia',
            'mncName': 'Mobile TeleSystems',
            'number': '791234567890',
        }, ...
    ]
}

Parameters:

  • call_id – unique call id, this id is indicated in the recording file name (unique for every recording in the statistics);
  • lang - recognition language (not required);
  • return - returned result. Options: words - words, phrases - phrases. (not required. phrases by default);
  • alternatives - return alternative results. Options: 0 - no, 1 - yes. (not required. 0 by default).
  • JSON
{
    "status": "success",
    "lang": "en-EN",
    "recognitionStatus": "in progress",
    "otherLangs": ["es-ES"],
    "words": [
        {
            "result": [
                {
                        "s": 0.02,
                        "e": 0.22,
                        "w": "word",
                },
                {
                        "s": 0.31,
                        "e": 0.56,
                        "w": "one",
                }
            ],
            "channel": 1
        }
    ],
    "phrases": [
        {
            "result": "word one",
            "channel": 1
        }
    ]
}

where

  • lang – language;
  • recognitionStatus: recognition status. Options:
    • in progress - in the process of recognition,
    • error - an error occured during recognition,
    • recognized - recognition complete
    • ready for recognize - recording is ready for recognition,
    • not available for recognize - recording is not available for recognition.
  • result:
    • words - array:
      • result - list of words (array):
        • s - word beginning time
        • e - word ending time
        • w - word
      • channel - channel number
    • phrases - array:
      • result - phrase
      • channel - channel number

Parameters:

  • call_id – unique call id, this id is indicated in the recording file name (unique for every recording in the statistics);
  • lang - recognition language (not required).
  • JSON
{
    'status' => 'success'
}

API ZCRM available methods:

 

  • Clients
  • customers
    Restores client list.
  • customers/<c_id>
    Restores client by ID.
  • customers
    Creates a new client with indicated data.
  • customers/<c_id>
    Updates an existing client with indicated ID.
  • customers/<c_id>
    Deleted a client by its ID.
  • Labels
  • customers/labels
    Restores the list of all labels and their statistics.
  • customers/labels
    Creates new label.
  • customers/labels/<l_id>
    Deletes label from the system using its ID.
  • Additional features
  • customers/custom-properties
    Restores additional features.
  • Client timeline
  • customers/<c_id>/feed
    Restores records in client timeline.
  • customers/<c_id>/feed
    Adds a text note to client timeline with an ability to attach files.
  • customers/<c_id>/feed/<i_id>
    Updates an existing text note by its ID.
  • customers/<c_id>/feed/<i_id>
    Deletes a note in client timeline by its ID.
  • Employees
  • customers/<c_id>/employees
    Restores client employees list by its ID.
  • customers/<c_id>/employees/<e_id>
    Restores client employee by its ID.
  • customers/<c_id>/employees
    Creates and saves a new employee for a chosen client.
  • customers/<c_id>/employees/<e_id>
    Updates an existing employee with an indicated ID.
  • customers/<c_id>/employees/<e_id>
    Deletes an employee by ID.
  • Tasks
  • events
    Restores task list.
  • events/<event_id>
    Restores a task by its ID.
  • events
    Created a new task with indicated information.
  • events/<event_id>
    Updates an existing task with indicated ID.
  • events/<event_id>/close
    Completes (closes) the task.
  • events/<event_id>
    Deleted a task by its ID.
  • Leads
  • leads
    Restores lead list.
  • leads/<lead_id>
    Restores lead by its ID.
  • leads
    Creates a new lead with indicated information.
  • leads/<lead_id>
    Updates an existing lead with an indicated ID.
  • leads/<lead_id>
    Deleted a lead by its ID.
  • Users
  • users
    Restores users list.
  • users/<user_id>
    Restores user by its ID.
  • users/<user_id>/working-hours
    Restores user work hours.
  • users/groups
    Restores groups and users rights in each of them.
  • Calls
  • calls
    Restores call list.
  • Generalized contacts
  • contacts
    Restores the whole list of contacts (clients, employees, leads, users) with phone numbers.
  • contacts/identify
    Identifies contact (client, employee, lead, user) by the phone number.
  • Files
  • files/<file_id>
    Gives files by its ID.

GET /v1/zcrm/customers

Restores client list.

Parameters

  • search (optional) - search bar. Search is carried out in combination by:
    • client name
    • client phone numbers
    • client description
    • address and zip code
    • website
    • email address
    • messengers
    • employees’ names
    • employees’ phone numbers
    • employees’ description
    • employees’ email addresses
    • employees’ messengers
  • filter (optional) - client filter. The filter works only for specified fields. Filter structure:
    {
    "status": "company",
    "type": "client",
    "country": "GB",
    "city": "London",
    "label": 12,
    "employees_count": "50",
    "responsible": 20
    }
    
    where:
    • status — client status. Valid values:
      • individual — personal user
      • company — company/business
    • type — client type. Valid values:
      • potential — potential client
      • client — client
      • reseller — reseller
      • partner — partner
    • country — client country. Two-letter code (US, UK etc.)
    • city — client city (line)
    • label — tag (identification)
    • employees_count — number of employees. Valid values:
      • 50 — less than 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • responsible — responsible (user identification)
    Any of the filter parameters can be skipped, meaning it is not required.
  • sort (optional) - client sorting. Parameter structure:
    {
      "attr": "name",
      "desc": 0
    }
    
    where:
    • attr — sorting field. Valid values:
      • name — client name
      • status — client status
      • type — client type
    • desc — sorting direction. Valid values:
      • 0 — ascending
      • 1 — descending
  • take (pagination) - how many clients to return (20 by default)
  • skip (pagination) - how many clients to skip (0 by default)

Response

{
  "totalCount": 82,
  "customers": [
    {
      "id": 65,
      "name": "Good company",
      "status": "company",
      "type": "client",
      "responsible_user_id": 20,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "created_at": "2020-04-28 05:47:47",
      "created_by": 20,
      "lead_source": "manual",
      "lead_created_at": null,
      "lead_created_by": null,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 12,
          "label": "Best clients"
        }
      ]
    }
  ]
}

where:

  • totalCount — total number of clients (including search and filter)
  • customers — client array (including pagination). Each array element contains the following parameters:
    • id — client identification
    • name — client name
    • status — client status. Possible values:
      • individual — personal user
      • company — company/business
    • type — client type. Possible values:
      • potential — potential client
      • client — client
      • reseller — reseller
      • partner — partner
    • responsible_user_id — responsible (user identification)
    • employees_count — number of employees. Possible values:
      • 50 — less than 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — client description
    • country — client country. Two-letter code (UK, US etc.)
    • city — client city
    • address — client address
    • zip — zip code
    • website — client website
    • created_at — client creation date and time (format YYYY-MM-DD HH:mm:ss)
    • created_by — created by (user identification)
    • lead_source — source. Possible values:
      • manual — manual
      • call_incoming — incoming call
      • call_outgoing — outgoing call
      • form — form
    • lead_created_at — lead creation date and time, if the client was created from a lead (format YYYY-MM-DD HH:mm:ss)
    • lead_created_by — lead created by, if the client was created from a lead (user identification)
    • phones — client phone numbers array. Each number contains the following fields:
      • type — number type. Possible values:
        • work — work
        • personal — personal
      • phone — phone number
    • contacts — client contacts array. Each contact contains the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value
    • labels — tags/labels array, assigned to a client. Each label contains the following fields:
      • id — label identification
      • label — label value

GET /v1/zcrm/customers/<c_id>

Restores client by ID.

Address parameters

  • c_id — client identification

Response

{
  "id": 65,
  "name": "Good company",
  "status": "company",
  "type": "client",
  "responsible_user_id": 20,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "created_at": "2020-04-28 05:47:47",
  "created_by": 20,
  "lead_source": "manual",
  "lead_created_at": null,
  "lead_created_by": null,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 12,
      "label": "Best clients"
    }
  ],
  "custom_properties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

where:

  • id — client identification
  • name — client name
  • status — client status. Possible values:
    • individual — personal user
    • company — company/business
  • type — client type. Possible values:
    • potential — potential client
    • client — client
    • reseller — reseller
    • partner — partner
  • responsible_user_id — responsible (user identification)
  • employees_count — number of employees. Possible values:
    • 50 — less than 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — client description
  • country — client country. Two-letter code (UK, US etc.)
  • city — client city
  • address — client address
  • zip — zip code
  • website — client website
  • created_at — client creation date and time (format `YYYY-MM-DD HH:mm:ss`)
  • created_by — created by (user identification)
  • lead_source — source. Possible values:
    • manual — manual
    • call_incoming — incoming call
    • call_outgoing — outgoing call
    • form — form
  • lead_created_at — lead creation date and time, if the client was created from a lead (format `YYYY-MM-DD HH:mm:ss`)
  • lead_created_by — lead created by, if the client was created from a lead (user identification)
  • phones — client phone numbers array. Each number contains the following fields:
    • type — number type. Possible values:
      • work — work
      • personal — personal
    • phone — phone number
  • contacts — client contacts array. Each contact contains the following fields:
    • type — client type. Possible values:
      • email_work — work e-mail
      • email_personal — personal e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — contact value
  • labels — tags/labels array, assigned to a client. Each label contains the following fields:
    • id — label identification
    • label — label value
  • custom_properties — additional features array. Each additional feature contains the following fields:
    • id — additional feature identification
    • key — additional feature unique name
    • title — additional feature displayed name
    • value — additional feature value

POST /v1/zcrm/customers

Creates a new client with indicated data.

  • customer — new client information. Client structure:

Parameters

{
    "name": "Good company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
  ],
    "custom_properties": [
    {
        "id": 18,
        "value": "high"
      }
    ]
}

where:

  • name — client name
  • status — client status. Possible values:
    • individual — personal user
    • company — company/business
  • type — client type. Possible values:
    • potential — potential client
    • client — client
    • reseller — reseller
    • partner — partner
  • responsible_user_id — responsible (user identification)
  • employees_count — number of employees. Possible values:
    • 50 — less than 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — client description
  • country — client country. Two-letter code (UK, US etc.)
  • city — client city
  • address — client address
  • zip — zip code
  • website — client website
  • lead_source — source. Possible values:
    • manual — вручную
    • call_incoming — incoming call
    • call_outgoing — outgoing call
    • form — form
  • phones — phone numbers array. Each number contains the following fields:
    • type — number type. Possible values:
      • work — work
      • personal — personal
    • phone — number value
  • contacts — client contacts array. Each contact contains the following fields:
    • type — contact type. Possible values:
      • email_work — work e-mail
      • email_personal — personal e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — contact value
  • labels — tags/labels array, assigned to a client. Each label contains the following fields:
    • id — existing label identification
  • custom_properties — additional features array. Each element must contain:
    • id — additional feature identification:
    • key — additional feature unique name
    • value — additional feature value

Response:

{
"id": 65
}

where:

  • id — created client identification

PUT /v1/zcrm/customers/<c_id>

Updates an existing client with indicated ID.

Address parameters

  • c_id — client identification

Parameters

  • customer — new client data. Client structure:
{
    "name": "Good company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
  ],
    "custom_properties": [
    {
        "id": 18,
        "value": "high"
      }
    ]
}

where:

  • name — client name
  • status — client status. Possible values:
    • individual — personal user
    • company — company/business
  • type — client type. Possible values:
    • potential — potential client
    • client — client
    • reseller — reseller
    • partner — partner
  • responsible_user_id — responsible (user identification)
  • employees_count — number of employees. Possible values:
    • 50 — less than 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — client description
  • country — client country. Two-letter code (UK, US etc.)
  • city — client city
  • address — client address
  • zip — zip code
  • website — client website
  • created_at — client creation date and time (format YYYY-MM-DD HH:mm:ss)
  • created_by — created by (user identification)
  • lead_source — source. Possible values:
    • manual — manual
    • call_incoming — incoming call
    • call_outgoing — outgoing call
    • form — form
  • phones — phone number array. Each number must contain the following fields:
    • type — number type. Possible values:
      • work — work
      • personal — personal
    • phone — phone number value
  • contacts — client contacts array. Each contact contains the following fields:
    • type — contact type. Possible values:
      • email_work — work e-mail
      • email_personal — personal e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — contact value
  • labels — tags/labels array, assigned to a client. Each label contains the following fields:
    • id — label identification
    • label — label value
  • custom_properties — additional features array. Each element must contain:
    • id — additional features identification or
    • key — additional features unique name
    • value — additional features values
  • DELETE /v1/zcrm/customers/<c_id>

    Deleted a client by its ID.

    Address parameters

    • c_id — client identification

    GET /v1/zcrm/customers/labels

    Restores the list of all labels and their statistics.

    Response

    {
      "totalCount": 5,
      "labels": [
        {
          "id": 12,
          "label": "Best clients",
          "count": 14
        }
      ]
    }

    where:

    • totalCount — total number of labels in the system
    • labels — labels array. Each label has the following fields:
      • id — label identification
      • label — label name
      • count — number of clients and leads using this label

    POST /v1/zcrm/customers/labels

    Creates new label.

    Parameters

    • name — new label name

    Response

    {
      "id": 13,
      "label": "Best clients",
      "count": 0
    }

    where:

    • id — created label identification
    • label — label name
    • count — number of clients and leads using this label (here always equals 0)

    DELETE /v1/zcrm/customers/labels/<l_id>

    Deletes label from the system using its ID.

    Address parameters

    • l_id — label identification

    GET /v1/zcrm/customers/custom-properties

    Restores additional features.

    Response

    {
      "totalCount": 8,
      "customProperties": [
        {
          "id": 18,
          "key": "loyalty",
          "title": "Loyalty"
        }
      ]
    }

    where:

    • totalCount — total number of additional features.
    • customProperties — array of additional features. Each additional feature includes the following fields:
      • id — additional feature identification
      • key — additional feature unique name
      • title — additional feature displayed name

    GET /v1/zcrm/customers/<c_id>/feed

    Restores records in client timeline.

    Address parameters

    • c_id — client identification

    Response

    {
      "totalCount": 17,
      "items": [
        {
          "id": 37825,
          "type": "note",
          "content": "Call to client",
          "time": "2020-06-08 06:55:02",
          "user_id": 20,
          "user_name": "John Smith",
          "call_id": null,
          "call_type": null,
          "call_status": null,
          "call_phone": null,
          "call_duration": null,
          "call_record": null,
          "call_contact_name": null,
          "attached_files": [
            {
              "file_id": 576,
              "original_filename": "filename.doc"
            }
          ]
        }
      ]
    }

    where:

    • totalCount — total number of records
    • items — records array. Each record contains the following attributes:
      • id — records identification
      • type — record type. Possible values:
        • event — event
        • note — text note
        • call — call
      • content — content. If record type is note, this attribute contains note text. If record type is event, this attribute contains event identification, for example:
        • CUSTOMER_CREATED — client creation event
        • LEAD_CREATED — lead creation event
      • time — record time in format `YYYY-MM-DD hh:mm:ss`
      • user_id — user identification, who created the record
      • user_name — user name, who created the record
      • call_id — call identification (if record type is call)
      • call_type — call type. Possible values:
        • incoming — incoming call
        • outgoing — outgoing call
      • call_status — call status. Possible values:
        • answer — successful call
        • noanswer — no answer
        • cancel — canceled
        • busy — busy
        • failed — failed call
      • call_phone — call phone number
      • call_duration — call duration in seconds
      • call_record — if call recording is enabled
      • call_contact_name — call contact name
      • attached_files — array of files attached to a note (if record type is a note). Each array element contains the following attributes:
        • file_id — file identification
        • original_filename — original file name

    POST /v1/zcrm/customers/<c_id>/feed

    Adds a text note to client timeline with an ability to attach files.

    Address parameters

    • c_id — client identification

    Parameters

    • content — note text content
    • files — attached files array

    Response

    {
      "id": 37825,
      "type": "note",
      "content": "Call to client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Smith",
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "filename.doc"
        }
      ]
    }

    where:

    • id — record identification
    • type — record type. In this case is equal to:
      • note — text note
    • content — note text content
    • time — record time in format `YYYY-MM-DD hh:mm:ss`
    • user_id — user identification, who created a record
    • user_name — user name, who created a record
    • attached_files — array of files attached to a note (if record type is a note). Each array element contains the following attributes:
      • file_id — file identification
      • original_filename — original file name

    PUT /v1/zcrm/customers/<c_id>/feed/<i_id>

    >Updates an existing text note by its ID.

    Address parameters

    • c_id — client identification
    • i_id — text note identification

    Parameters

    • content — new note text

    DELETE /v1/zcrm/customers/<c_id>/feed/<i_id>

    Deletes a note in client timeline by its ID.

    Address parameters

    • c_id — client identification
    • i_id — text note identification

    GET /v1/zcrm/customers/<c_id>/employees

    Restores client employees list by its ID.

    Address parameters

    • c_id — client identification

    Response

    {
      "totalCount": 5,
      "employees": [
        {
          "id": 23,
          "customer_id": 11,
          "name": "John Smith",
          "position": "manager",
          "position_title": "",
          "comment": "",
          "phones": [
            {
              "type": "work",
              "phone": "+44123456789"
            }
          ],
          "contacts": [
            {
              "type": "email_work",
              "value": "john@example.com"
            }
          ]
        }
      ]
    }

    where:

    • totalCount — number of client’s employees
    • employees — client’s employees array. Each array element contains the following attributes:
      • id — employee identification
      • customer_id — client identification to whom the employee is attached
      • name — employee name
      • position — employee position. Possible values:
        • ceo — CEO
        • director — director
        • manager — manager
        • sales_manager — sales manager
        • hr — HR
        • support — support
        • custom — custom
      • position_title — custom position title (for position = custom)
      • comment — employee description
      • phones — employee phone numbers array. Each number includes the following fields:
        • type — number type. Possible value:
          • work — work
          • personal — personal
        • phone — phone number value
      • contacts — employee contacts array. Each contact contains the following field:
        • type — contact type. Possible values:
          • email_work — work e-mail
          • email_personal — personal e-mail
          • skype
          • telegram
          • viber
          • whatsapp
        • value — contact value

    GET /v1/zcrm/customers/<c_id>/employees/<e_id>

    Restores client employee by its ID.

    Address parameters

    • c_id — client identification
    • e_id — employee identification

    Response

    {
      "id": 23,
      "customer_id": 11,
      "name": "John Smith",
      "position": "manager",
      "position_title": "",
      "comment": "",
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "john@example.com"
        }
      ]
    }

    where:

    • id — employee identification
    • customer_id — client identification to whom the employee is attached
    • name — employee name
    • position — employee position. Possible values:
      • ceo — CEO
      • director — director
      • manager — manager
      • sales_manager —sales manager
      • hr — HR
      • support — support
      • custom — custom
    • position_title — custom position title (for position = custom)
    • comment — employee description
    • phones — employee phone number array. Each number contains the following field:
      • type — number type. Position values:
        • work — work
        • personal — personal
      • phone — phone number value
    • contacts — employee contacts array. Each contact contains the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value

    POST /v1/zcrm/customers/<c_id>/employees

    Creates and saves a new employee for a chosen client.

    Address parameters

    • c_id — client identification

    Parameters

    • employee — new employee information. Employee structure:
    {
        "name": "John Smith",
        "position": "manager",
        "position_title": "",
        "comment": "",
        "phones": [
          {
            "type": "work",
            "phone": "+44123456789"
          }
        ],
        "contacts": [
          {
            "type": "email_work",
            "value": "john@example.com"
          }
        ]
      }

    where:

    • name — employee name
    • position — employee position. Possible values:
      • ceo — CEO
      • director — director
      • manager — manager
      • sales_manager — sales manager
      • hr — HR
      • support — support
      • custom — custom
    • position_title — custom position title (for position = custom)
    • comment — employee description
    • phones — employee phone number array. Each number contains the following field:
      • type — phone number. Possible values:
        • work — work
        • personal — personal
      • phone — phone number value
    • contacts — employee contacts array. Each contact contains the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value

    Response

    {
      "id": 23
    }

    where:

    • id — new employee identification

    PUT /v1/zcrm/customers/<c_id>/employees/<e_id>

    Updates an existing employee with an indicated ID.

    Address parameters

    • c_id — client identification
    • e_id — employee identification

    Parameters

    • employee — new employee information. Structure:
    {
        "name": "John Smith",
        "position": "manager",
        "position_title": "",
        "comment": "",
        "phones": [
          {
            "type": "work",
            "phone": "+44123456789"
          }
        ],
        "contacts": [
          {
            "type": "email_work",
            "value": "john@example.com"
          }
        ]
    }

    where:

    • name — employee name
    • position — employee position. Possible values:
      • ceo — CEO
      • director — director
      • manager — manager
      • sales_manager — sales manager
      • hr — HR
      • support — support
      • custom — custom
    • position_title — custom position title (for position = custom)
    • comment — employee description
    • phones — employee phone number array. Each number contains the following field:
      • type — phone number. Possible values:
        • work — work
        • personal — personal
      • phone — phone number value
    • contacts — employee contacts array. Each contact contains the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value

    DELETE /v1/zcrm/customers/<c_id>/employees/<e_id>

    Deletes an employee by ID.

    Address parameters

    • c_id — client identification
    • e_id — employee identification

    GET /v1/zcrm/events

    Restores task list.

    Parameters

    • search (optional) - search bar. Search is carried out in combination by:
      • task name
      • task description
      • comments to completed tasks
    • filter (optional) - task filter. Filter structure:
      {
          "responsible": 456,
          "createdBy": 456,
          "start": "2020-06-03 02:56:00",
          "end": "2020-06-12 02:56:00",
          "completed": 1
      }

      where:

      • responsible —responsible (user identification)
      • createdBy — created by (user identification)
      • start — display tasks starting after the specified time (in format `YYYY-MM-DD hh:mm:ss`)
      • end — display tasks ending before the specified time (in format `YYYY-MM-DD hh:mm:ss`)
      • completed — set in 1 to also display completed tasks
    • sort (optional) - task sorting. Parameter structure:
      {
          "attr": "start",
          "desc": 0
      }

      where:

      • attr — sorting field. Valid value:
        • responsible — responsible user
        • title — task title
        • start — task beginning time
        • end — task ending time
      • desc — sorting order. Valid value:
        • 0 — ascending
        • 1 — descending

    Response

    {
      "totalCount": 4,
      "events": [
        {
          "id": 40,
          "type": "task",
          "title": "Call to GoodCompany",
          "description": "",
          "start": "2020-05-26 09:00:00",
          "end": "2020-05-26 12:30:00",
          "allDay": false,
          "created_by": 234,
          "responsible_user": 234,
          "phone": "",
          "call_done": 0,
          "completed": 0,
          "completed_comment": "",
          "members": [234, 235],
          "customers": [
            {
              "id": 3486,
              "name": "GoodCompany",
              "status": "company",
              "type": "client",
              "lead_source": "manual",
              "lead_status": "not_processed",
              "contact_type": "customer"
            }
          ]
        }
      ]
    }

    where

    • totalCount — total number of tasks
    • events — tasks array. Each task contains the following attributes:
      • id — task identification
      • type — task type. Possible values:
        • task — task
        • call — call
      • title — task title
      • description — task description (in format: Quill Delta: https://quilljs.com/docs/delta/)
      • start — task beginning date and time (in format `YYYY-MM-DD hh:mm:ss`)
      • end — task ending date and time (in format `YYYY-MM-DD hh:mm:ss`)
      • allDay — all-day task (`true` or `false`) — date is determined by parameter start
      • created_by — identification of the user who created the task
      • responsible_user — identification of the responsible user
      • phone — phone number for a call (if task type is call)
      • call_done — indicates if the call was made
      • completed — indicated of the task was marked as complete
      • completed_comment — comment to a completed task
      • members — task members array (only users’ identifications)
      • customers — array of clients and leads attached to the task. Each array element contains the following fields:
        • id — client/lead identification
        • name — client/lead name
        • status — client status. Possible values:
          • individual — personal user
          • company — company/business
        • type — client type. Possible values:
          • potential — potential client
          • client — client
          • reseller — reseller
          • partner — partner
        • lead_source — lead source. Possible values:
          • manual — manual
          • call_incoming — incoming call
          • call_outgoing — outgoing call
          • form — form
        • lead_status — lead status. Possible values:
          • not_processed — not processed
          • in_progress — in progress
          • finished — finished
        • contact_type — contact type. Possible values:
          • customer — client
          • lead — lead

    GET /v1/zcrm/events/<event_id>

    Restores a task by its ID.

    Response

    {
      "id": 40,
      "type": "task",
      "title": "Call to GoodCompany",
      "description": "",
      "start": "2020-05-26 09:00:00",
      "end": "2020-05-26 12:30:00",
      "allDay": false,
      "created_by": 234,
      "responsible_user": 234,
      "phone": "",
      "call_done": 0,
      "completed": 0,
      "completed_comment": "",
      "members": [234, 235],
      "customers": [
        {
          "id": 3486,
          "name": "GoodCompany",
          "status": "company",
          "type": "client",
          "lead_source": "manual",
          "lead_status": "not_processed",
          "contact_type": "customer"
        }
      ]
    }

    where

    • id — task identification
    • type — task type. Possible values:
      • task — task
      • call — call
    • title — task title
    • description — task description (in format Quill Delta: https://quilljs.com/docs/delta/)
    • start — task starting date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • end — task ending date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • allDay — all-day task (`true` or `false`)
    • created_by — identification of the user who created the task
    • responsible_user — identification of the responsible user
    • phone — phone number for the call (if task type is call)
    • call_done — indicates if the call was made
    • completed — indicated the task was completed
    • completed_comment — comments to a completed task
    • members — task members array (only user identifications)
    • customers — array of clients and leads attached to the task. Each array element contains the following fields:
      • id — client/lead identification
      • name — client/lead name
      • status — client status. Possible values:
        • individual — personal user
        • company — company/business
      • type — client type. Possible values:
        • potential — potential client
        • client — client
        • reseller — reseller
        • partner — partner
      • lead_source — lead source. Possible value:
        • manual — manual
        • call_incoming — incoming call
        • call_outgoing — outgoing call
        • form — form
      • lead_status — lead status. Possible values:
        • not_processed — not processed
        • in_progress — in progress
        • finished — finished
      • contact_type — contact type. Possible values:
        • customer — client
        • lead — lead

    POST /v1/zcrm/events

    Created a new task with indicated information.

    Parameters

    • event — new task information. Structure:
    {
        "type": "task",
        "title": "Call to GoodCompany",
        "description": "",
        "start": "2020-05-26 09:00:00",
        "end": "2020-05-26 12:30:00",
        "allDay": false,
        "responsible_user": 234,
        "phone": "",
        "members": [234, 235],
        "customers": [3486, 3487]
    }

    where

    • type — task type. Valid values:
      • task — task
      • call — call
    • title — task title
    • description — task description (in format Quill Delta: https://quilljs.com/docs/delta/)
    • start — task beginning date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • end — task ending date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • allDay — all-day task (`true` or `false`)
    • responsible_user — responsible user identification
    • phone — phone number for the call (if task type is call)
    • members —task members array (only user identifications)
    • customers — attached clients and leads array (only client and lead identification)

    Response

    {
      "id": 7216
    }

    where

    • id — new task identification

    PUT /v1/zcrm/events/<event_id>

    Updates an existing task with indicated ID.

    >

    Parameters

    • event — new task information. Structure:
    {
        "title": "Call to GoodCompany",
        "description": "",
        "start": "2020-05-26 09:00:00",
        "end": "2020-05-26 12:30:00",
        "allDay": false,
        "created_by": 234,
        "responsible_user": 234,
        "phone": "",
        "members": [234, 235],
        "customers": [3486, 3487]
    }

    where

    • title — task title
    • description — task description (in format Quill Delta: https://quilljs.com/docs/delta/)
    • start — task beginning date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • end — task ending date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • allDay — all-day task (`true` or `false`)
    • responsible_user — responsible user identification
    • phone — phone number for the call (if task type is call)
    • members — task members array (only user identification)
    • customers — attached client and lead array (only client and lead identification)

    POST /v1/zcrm/events/<event_id>/close

    Completes (closes) the task.

    Parameters

    • comment (optional) - comment

    DELETE /v1/zcrm/events/<event_id>

    Deleted a task by its ID.

    No parameters

    GET /v1/zcrm/leads

    Restores lead list.

    Parameters

    • search (optional) - search bar. Search is carried out in combination by:
      • lead name
      • lead phone number
      • lead description
      • address and zip code
      • website
      • email address
      • messengers
    • filter (optional) - lead filter. Filter structure:
      {
          "source": "call_incoming",
          "responsible": 32,
          "label": 12,
          "createdAfter": "2020-06-11 12:24:00",
          "createdBefore": "2020-06-26 12:24:00"
      }

    where

    • source — lead source. Possible values:
      • manual — manual
      • call_incoming — incoming call
      • call_outgoing — outgoing call
      • form — callback form
    • responsible — responsible (user identification). The parameter also allows special values:
      • null — will return all leads assigned to someone
      • –1 — will return all raw leads
      • –2 — will return all leads (assigned and raw)
    • label — label/tag (identification)
    • createdAfter — display only leads created after the specified time (format: `YYYY-MM-DD hh:mm:ss`)
    • createdBefore — display only leads created before the specified time (format: `YYYY-MM-DD hh:mm:ss`)
    Any of the filter parameters can be skipped, meaning it is not required.
    • sort (optional) - lead sorting. Parameter structure:
      {
          "attr": "name",
          "desc": 0
      }

      where

      • attr — sorting field. Possible values:
        • name — lead name
        • lead_source — lead source
        • lead_status — lead status
        • responsible_user_id — responsible user
        • lead_created_at — lead creation time
      • desc — sorting order. Possible values:
        • 0 — ascending
        • 1 — descending
    • take (pagination) - how many leads to return (20 by default)
    • skip (pagination) - how many leads to skip (0 by default)

    Response

    {
      "totalCount": 100,
      "uncategorizedCount": 10,
      "leads": [
        {
          "id": 3486,
          "name": "GoodCompany",
          "responsible_user_id": 234,
          "employees_count": "50",
          "comment": "",
          "country": "GB",
          "city": "London",
          "address": "",
          "zip": "",
          "website": "",
          "lead_status": "not_processed",
          "lead_source": "manual",
          "lead_created_at": "2020-04-28 05:47:47",
          "lead_created_by": 234,
          "phones": [
            {
              "type": "work",
              "phone": "+44123456789"
            }
          ],
          "contacts": [
            {
              "type": "email_work",
              "value": "good_company@example.com"
            }
          ],
          "labels": [
            {
              "id": 22,
              "label": "Best clients"
            }
          ]
        }
      ]
    }

    where

    • totalCount — total number of found leads (including search bar and filter)
    • uncategorizedCount — total number of raw leads (including search bar and filter)
    • leads — lead array (including pagination). Each array element contains the following parameters:
      • id — lead identification
      • name — lead name
      • responsible_user_id — responsible (user identification)
      • employees_count — number of employees. Possible values:
        • 50 —less than 50
        • 50_250 — 50 – 250
        • 250_500 — 250 – 500
      • comment — lead description
      • country — lead county. Two-letter code (UK, US etc.)
      • city — lead city
      • address — lead address
      • zip — zip code
      • website — lead website
      • lead_status — lead status. Possible values:
        • not_processed — not processed
        • in_progress — in progress
        • finished — finished
      • lead_source — lead source. Possible values:
        • manual — manual
        • call_incoming — incoming call
        • call_outgoing — outgoing call
        • form —form
      • lead_created_at — lead creation date and time (in format `YYYY-MM-DD HH:mm:ss`)
      • lead_created_by — who created the lead (user identification)
      • phones — lead phone numbers array. Each number contains the following fields:
        • type — number type. Possible values:
          • work —work
          • personal — personal
        • phone — number value
      • contacts — lead contacts array. Each contact contains the following fields:
        • type — contact type. Possible values:
          • email_work — work e-mail
          • email_personal — personal e-mail
          • skype
          • telegram
          • viber
          • whatsapp
        • value — contact value
      • labels — array of leads assigned to a lead. Each label contains the following fields:
        • id — label identification
        • label — label value

    GET /v1/zcrm/leads/<lead_id>

    Restores lead by its ID.

    Response

    {
      "id": 3486,
      "name": "GoodCompany",
      "responsible_user_id": 234,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "lead_status": "not_processed",
      "lead_source": "manual",
      "lead_created_at": "2020-04-28 05:47:47",
      "lead_created_by": 234,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 22,
          "label": "Best clients"
        }
      ],
      "custom_properties": [
        {
          "id": 12,
          "key": "loyalty",
          "title": "Loyalty",
          "value": "high"
        }
      ]
    }

    where

    • id — lead identification
    • name — lead name
    • responsible_user_id — responsible (user identification)
    • employees_count — number of employees. Possible values:
      • 50 — less than 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — lead description
    • country — lead country. Two-letter code (UK, US etc.)
    • city — lead city
    • address — lead address
    • zip — zip code
    • website — lead website
    • lead_status — lead status. Possible values:
      • not_processed — not processed
      • in_progress — in progress
      • finished —finished
    • lead_source — lead source. Possible values:
      • manual — manual
      • call_incoming — incoming call
      • call_outgoing — outgoing call
      • form — form
    • lead_created_at — lead creation date and time (in format `YYYY-MM-DD HH:mm:ss`)
    • lead_created_by — who created the lead (user identification)
    • phones — lead phone numbers array. Each number contains the following fields:
      • type — number type. Possible values:
        • work — work
        • personal — personal
      • phone — number value
    • contacts — lead contacts array. Each contact contains the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value
    • labels — array of labels assigned to a lead. Each label contains the following fields:
      • id — label identification
      • label — label value

    POST /v1/zcrm/leads

    Creates a new lead with indicated information.

    Parameters

    • convert — convert lead to client. Valid values:
      • 0 — don not convert, create a lead
      • 1 — create a client
      • 2 — poor (the action will be canceled – lead or client will not be created)
    • lead — new lead information. Lead structure:
      {
          "name": "GoodCompany",
          "responsible_user_id": 234,
          "employees_count": "50",
          "comment": "",
          "country": "RU",
          "city": "Москва",
          "address": "",
          "zip": "",
          "website": "",
          "lead_source": "manual",
          "lead_status": "in_progress",
          "phones": [
            {
              "type": "work",
              "phone": "+44123456789"
            }
          ],
          "contacts": [
            {
              "type": "email_work",
              "value": "good_company@example.com"
            }
          ],
          "labels": [
            { "id": 22 },
            { "id": 23 }
        ],
          "custom_properties": [
          {
              "id": 12,
              "value": "high"
            }
          ]
      }

      where

      • name — lead name
      • responsible_user_id — responsible (user identification)
      • employees_count — number of employees. Valid values:
        • 50 — less than 50
        • 50_250 — 50 – 250
        • 250_500 — 250 – 500
      • comment — lead description
      • country — lead country. Two-letter code (UK, US etc.)
      • city — lead city
      • address — lead address
      • zip — lead zip code
      • website — lead website
      • lead_source — lead source. Valid values:
        • manual — manual
        • call_incoming — incoming call
        • call_outgoing — outgoing call
        • form —form
      • lead_status — lead status. Valid values:
        • not_processed — not processed
        • in_progress — in progress
        • finished — finished
      • phones — phone number array. Each number must contain the following fields:
        • type — number type. Possible values:
          • work — work
          • personal — personal
        • phone — number value
      • contacts — lead contacts array. Each contact must contain the following fields:
        • type — contact type. Possible values:
          • email_work — work e-mail
          • email_personal — personal e-mail
          • skype
          • telegram
          • viber
          • whatsapp
        • value — contact value
      • labels — array of labels assigned to the lead. Each element must contain:
        • id — existing label identification
        • custom_properties — additional features array. Each element must contain:
          • id — additional feature identification or:
          • key — additional feature unique name
          • value — additional feature value

    Response

    {
      "id": 123
    }

    where

    • id — created lead identification

    PUT /v1/zcrm/leads/<lead_id>

    Updates an existing lead with an indicated ID.

    Parameters

    • convert — convert lead to client. Valid values:
      • 0 — do not convert
      • 1 — create a client
      • 2 — poor (delete lead)
    • lead — new lead information. Lead structure:
    {
        "name": "GoodCompany",
        "responsible_user_id": 234,
        "employees_count": "50",
        "comment": "",
        "country": "GB",
        "city": "London",
        "address": "",
        "zip": "",
        "website": "",
        "lead_source": "manual",
        "lead_status": "in_progress",
        "phones": [
          {
            "type": "work",
            "phone": "+44123456789"
          }
        ],
        "contacts": [
          {
            "type": "email_work",
            "value": "good_company@example.com"
          }
        ],
        "labels": [
          { "id": 22 },
          { "id": 23 }
      ],
        "custom_properties": [
        {
            "id": 12,
            "value": "high"
          }
        ]
    }

    where

    • name — lead name
    • responsible_user_id — responsible (user identification)
    • employees_count — number of employees. Valid values:
      • 50 — less than 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — lead description
    • country — lead country. Two-letter code (UK, US etc.)
    • city — lead city
    • address — lead address
    • zip — lead zip code
    • website — lead website
    • lead_source — lead source. Valid value:
      • manual — manual
      • call_incoming — incoming call
      • call_outgoing — outgoing call
      • form — form
    • lead_status — lead status. Valid values:
      • not_processed — not processed
      • in_progress — in progress
      • finished — finished
    • phones — phone numbers array. Each number must contain the following fields:
      • type — number type. Possible values:
        • work — work
        • personal — personal
      • phone — number value
    • contacts — lead contacts array. Each contact must contain the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value
    • labels — array of labels assigned to a lead. Each element must contain:
      • id — existing label identification
    • custom_properties — additional features array. Each element must contain:
      • id — additional features identification or:
      • key — additional features unique name
      • value — additional features value

    DELETE /v1/zcrm/leads/<lead_id>

    Deleted a lead by its ID.

    No parameters

    GET /v1/zcrm/users

    Restores users list.

    Response

    {
      "totalCount": 2,
      "users": [
        {
          "id": 234,
          "email": "john_smith@example.com",
          "name": "John Smith",
          "group_id": 653,
          "is_superadmin": 1,
          "enabled": 1,
          "created_at": "2020-04-27 01:01:31",
          "avatar": 2457,
          "role": "",
          "status": "",
          "language": "en",
          "color": "220",
          "color_hex": "5678BD",
          "internal_number": "100",
          "timezone": "Europe/London",
          "first_day": 1,
          "device": "webphone",
          "phone_widget_location": "right",
          "phones": [
            {
              "phone": "+44123456789",
              "type": "work"
            }
          ],
          "contacts": [
            {
              "type": "email_work",
              "value": "smith@example.com"
            }
          ]
        }
      ]
    }

    where

    • totalCount — total number of users
    • users — user array. Each array element contains the following attributes:
      • id — user identification
      • email — user account e-mail
      • name — user name
      • group_id — user group identification
      • is_superadmin — indicates if the user is a super-adminitrator (1 or 0)
      • enabled — if the user is unblocked (1 or 0)
      • created_at — user creation date and time (in format `YYYY-MM-DD hh:mm:ss`)
      • avatar — user avatar (file identification)
      • role — user position
      • status — user status
      • language — user interface language. Possible values:
        • de — German
        • en — English
        • es — Spanish
        • pl — Polish
        • ru — Russian
        • ua — Ukranian
      • color — task color in ZCRM interface (only hue value — from 0 to 359)
      • color_hex —task color in ZCRM (hex-presentation)
      • internal_number — user PBX extension number
      • timezone — user timezone
      • first_day —indicates what week day is the beginning of the week:
        • 0 — Sunday
        • 1 — Monday
      • device — what is used for calls. Possible values:
        • webphone — webphone
        • softphone — third-party softphone
      • phone_widget_location — webphone widget location. Possible values:
        • left — display the widget on the left
        • right — display the widget on the right
      • phones — user phone numbers array. Each number contains the following fields:
        • phone — number value
        • type — number type. Possible values:
          • work — work
          • personal — personal
      • contacts — user contacts array. Each contact contains the following fields:
        • type — contact type. Possible values:
          • email_work — work e-mail
          • email_personal — personal e-mail
          • skype
          • telegram
          • viber
          • whatsapp
        • value — contact value

    GET /v1/zcrm/users/<user_id>

    Restores user by its ID.

    Response

    {
      "id": 234,
      "email": "john_smith@example.com",
      "name": "John Smith",
      "group_id": 653,
      "is_superadmin": 1,
      "enabled": 1,
      "created_at": "2020-04-27 01:01:31",
      "avatar": 2457,
      "role": "",
      "status": "",
      "language": "ru",
      "color": "220",
      "color_hex": "5678BD",
      "internal_number": "100",
      "timezone": "Europe/London",
      "first_day": 1,
      "device": "webphone",
      "phone_widget_location": "right",
      "phones": [
        {
          "phone": "+44123456789",
          "type": "work"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "smith@example.com"
        }
      ],
      "pending_email_change_request": false
    }

    where

    • id — user identification
    • email — user e-mail account
    • name — user name
    • group_id — user group identification
    • is_superadmin — indicates if the user is a super-adminitrator (1 or 0)
    • enabled — if the user is unblocked (1 or 0)
    • created_at — user creation date and time (in format `YYYY-MM-DD hh:mm:ss`)
    • avatar — user avatar (file identification)
    • role — user position
    • status — user status
    • language — user interface language. Possible values:
      • de — German
      • en — English
      • es — Spanish
      • pl — Polish
      • ru — Russian
      • ua — Ukranian
    • color — task color in ZCRM interface (only hue value — from 0 to 359)
    • color_hex — task color in ZCRM (hex-presentation)
    • internal_number — user PBX extension number
    • timezone — user timezone
    • first_day — what week day is the beginning of the week:
      • 0 — Sunday
      • 1 — Monday
    • device — what is used for calls. Possible values:
      • webphone — webphone
      • softphone — third-party softphone
    • phone_widget_location — webphone widget location. Possible values:
      • left — display the widget on the left
      • right — display the widget on the right
    • phones — массив телефонных номеров пользователя. Каждый номер содержит следующие поля:
      • phone — значение номера
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
    • contacts — user phone numbers array. Each number contains the following fields:
      • type — contact type. Possible values:
        • email_work — work e-mail
        • email_personal — personal e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — contact value
    • pending_email_change_request —if account email change has been sent, but is not yet confirmed, this parameter will be set in true

    GET /v1/zcrm/users/<user_id>/working-hours

    Restores user work hours.

    Response

    {
      "schedulePeriod": 7,
      "scheduleWorkingHours": [
        {
          "time_start": "2020-06-15 09:00:00",
          "time_end": "2020-06-15 18:00:00"
        }
      ],
      "scheduleFixes": [
        {
          "index": 2,
          "repeat_index": 1,
          "time_start": "2020-06-24 09:00:00",
          "time_end": "2020-06-24 13:00:00",
          "deleted": 0
        }
      ],
      "customWorkingHours": [
        {
          "time_start": "2020-06-27 11:00:00",
          "time_end": "2020-06-27 15:00:00"
        }
      ]
    }

    where

    • schedulePeriod — schedule frequency, *how often* is it repeated. For a regular week it’s 7 days, for day-in day-out it’s 2 days etc.
    • scheduleWorkingHours — work schedule array. Each work schedule contains the following attributes:
      • time_start — beginning of work time in format `YYYY-MM-DD hh:mm:ss`
      • time_end — end of work time in format `YYYY-MM-DD hh:mm:ss`
    • scheduleFixes — array of changes entered during working periods indicated in parameter scheduleWorkingHours. Each array element contains the following attributes:
      • index — element index in scheduleWorkingHours, meaning what working period was changed
      • repeat_index — schedule frequency index, in which the changes of future periods occur
      • time_start — new beginning of working time in format `YYYY-MM-DD hh:mm:ss`
      • time_end — new end of working time in format `YYYY-MM-DD hh:mm:ss`
      • deleted — if it equals 1, the working period is fully deleted
    • customWorkingHours — array of custom, single working periods. Each working period contains the following attributes:
      • time_start — beginning of work time in format `YYYY-MM-DD hh:mm:ss`
      • time_end — end of work time in format `YYYY-MM-DD hh:mm:ss`

    GET /v1/zcrm/users/groups

    Restores groups and users rights in each of them.

    Response

    {
      "totalCount": 4,
      "groups": [
        {
          "id": 45,
          "type": "manager",
          "title": "",
          "permissions": {
            "customers_create": true,
            "customers_edit": true,
            "customers_delete": true,
            "customers_import_export": true,
            "customers_view_all": false,
            "calendar_other_users_access": false,
            "calls_other_users_access": false,
            "leads_view": false,
            "leads_edit": false,
            "leads_delete": false,
            "leads_import_export": false,
            "team_add": false,
            "team_edit": false
          }
        }
      ]
    }

    where

    • totalCount — total number of groups
    • groups — groups array. Each group contains the following attributes:
      • id — group identification
      • type — group type. Possible values:
        • admin — admins
        • manager — managers
        • chat_operator — operators
        • trainee — trainees
        • custom — custom
      • title — custom group title ( or type = custom)
      • permissions — group user rights. Admins have a full access, that is why for admins this subject will be empty. Other groups contain the following attributes (each of them can be equal to `true` or `false`):
        • customers_create — client creation allowed
        • customers_edit — client editing allowed
        • customers_delete — client deletion allowed
        • customers_import_export — client import and export allowed
        • customers_view_all — all client viewing is allowed, including the ones assigned by other users
        • calendar_other_users_access — other users’ task viewing allowed
        • calls_other_users_access — access to other users’ calls is allowed
        • leads_view — only viewing of other users’ leads is allowed
        • leads_edit — other users’ lead editing is allowed
        • leads_delete — other users’ lead deletion is allowed
        • leads_import_export — lead export and import are allowed
        • team_add — adding and inviting other users to the team is allowed
        • team_edit — user editing is allowed

    GET /v1/zcrm/calls

    Restores call list.

    Parameters

    • search (optional) - search bar. Search is carried out in combination by:
      • phone numbers
      • contact names (clients, employees, leads or users)
    • filter (optional) - call filter. Filter structure:
      {
          "user": 23,
          "type": "incoming",
          "status": "answer",
          "dateFrom": "2020-06-03 14:56:00",
          "dateTo": "2020-06-26 14:56:00"
      }

      where

      • user — user (identification)
      • type — call type. Valid values:
        • incoming — incoming call
        • outgoing — outgoing call
      • status — call status. Valid values:
        • answer — successful call
        • noanswer — no answer
        • cancel — canceled calls
        • busy — busy
        • failed — failed call
      • dateFrom — display only calls made after specified time (format: `YYYY-MM-DD hh:mm:ss`)
      • dateTo — display only calls made before specified time (format: `YYYY-MM-DD hh:mm:ss`)
    Any of the filter parameters can be skipped, meaning it is not required.
    • sort (optional) - call sorting. Parameter structure:
        {
          "attr": "time",
          "desc": 0
        }

      where

      • attr — sorting field. Valid values:
        • phone — phone number
        • status — call status
        • duration — call duration
        • time — call time
      • desc — sorting direction. Valid values:
        • 0 — ascending
        • 1 — decending
    • take (pagination) - how many calls to return (20 by default)
    • skip (pagination) - how many calls to skip (0 by default)

    Response

    {
      "totalCount": 233,
      "calls": [
        {
          "id": 127,
          "type": "outgoing",
          "status": "answer",
          "phone": "+44123456789",
          "user_id": 179,
          "time": "2019-07-31 17:58:40",
          "duration": 9,
          "pbx_call_id": "out_807ghh1h7f09fa7a188dbf8a6998b1c9ghg4ij06",
          "record": 1,
          "record_url_till": "2020-07-24 20:08:10",
          "contact_type": "customer",
          "contact_name": "GoodCompany",
          "contact_customer_id": 3486,
          "contact_employee_id": null,
          "employee_customer_id": null,
          "contact_user_id": null,
          "is_lead": 1,
          "record_urls": [
            {
              "url": "https://api.zadarma.com/v1/pbx/record/download/[...]/[...]/[...].mp3"
            }
          ]
        }
      ]
    }

    where

    • totalCount — total number of calls (including search bar and filter)
    • calls — call array (including pagination). Each array element contains the following parameters:
      • id — call identification
      • type — call type. Possible values:
        • incoming — incoming call
        • outgoing — outgoing call
      • status — call status. Possible values:
        • answer — successful call
        • noanswer — no answer
        • cancel — canceled
        • busy — busy
        • failed — failed call
      • phone — phone number
      • user_id — user, who initiated or accepted the call
      • time — call time in format `YYYY-MM-DD hh:mm:ss`
      • duration — call duration in seconds
      • pbx_call_id — call identification in Zadarma PBX
      • record — if call recording enabled
      • record_url_till — time, until when call recording link will be active
      • contact_type — contact type. Possible values:
        • customer — client or lead (see parameter is_lead)
        • employee — client employee
        • user — user
      • contact_name — contact name
      • contact_customer_id — client or lead identification (if the call is related to a client)
      • contact_employee_id — employee identification (if the call is related to an employee)
      • employee_customer_id — parent entity identification (if the call is related to an employee)
      • contact_user_id — user identification (if the call is related to a user)
      • is_lead — shows if the call is related to a lead
      • record_urls — call recordings array (can be missing, as has to be specifically requested). Each array element is an object that contains the following field:
        • url — link to the call recording

    GET /v1/zcrm/contacts

    Restores the whole list of contacts (clients, employees, leads, users) with phone numbers.

    Parameters

    • search (optional) - search bar. Search is carried out in combination by:
      • names and phone numbers of clients, leads, employees and users
      • users PBX extension number
    • take (pagination) - how many contacts to return (20 by default)
    • skip (pagination) - how many contacts to skip (0 by default)

    Response

    {
      "totalCount": 128,
      "contacts": [
        {
          "contact_type": "customer",
          // clients attributes...
        },
        {
          "contact_type": "employee",
          // employee attributes...
        },
        {
          "contact_type": "lead",
          // leads attributes...
        },
        {
          "contact_type": "user",
          // users attributes...
        }
      ]
    }

    where

    • totalCount — total contact number (including search bar)
    • contacts — contact array. Each of the contacts depending on its type (client, employee, lead, user) will have its own set of attributes.

      Clients

      {
          "contact_type": "customer",
          "id": 3486,
          "name": "GoodCompany",
          "status": "company",
          "type": "client",
          "phone": {
            "phone": "+44123456789",
            "type": "work"
          },
          "responsible": {
            "id": 234,
            "name": "John Smith",
            "ext_num": "100"
          }
      }

      where

        li>contact_type — contact type:
        • customer —client
      • id — client identification
      • name — client name
      • status — client status. Possible values:
        • individual — personal user
        • company — company/business
      • type — client type. Possible values:
        • potential — potential client
        • client — client
        • reseller — reseller
        • partner — partner
      • phone — phone number. Contains the following fields:
        • phone — the number itself
        • type — number type. Possible values:
          • work — work
          • personal — personal
      • responsible — responsible user. Contains the following field:
        • id — user identification
        • name — user name
        • ext_num — user PBX extension number

      Client's employee

      {
              "contact_type": "employee",
              "id": 8,
              "name": "John Smith",
              "phone": {
                "phone": "+44123456789",
                "type": "work"
              },
              "position": {
                "position": "manager",
                "title": ""
              },
              "customer": {
                "id": 3486,
                "name": "GoodCompany"
              },
              "responsible": {
                "id": 234,
                "name": "John Smith",
                "ext_num": "100"
              }
      }

      where

      • contact_type — contact type:
        • employee — employee
      • id — employee identification
      • name — employee name
      • phone — phone number. Contains the following fields:
        • phone — the number itself
        • type — number type. Possible values:
          • work — work
          • personal — personal
      • position — employee position. Contains the following dields:
        • position — position value. Possible values:
          • ceo — CEO
          • director — director
          • manager — manager
          • sales_manager — sales manager
          • hr — HR
          • support — support
          • custom — custom
        • title — custom position title (for position = custom)
      • customer — client to whom the employee is attached. Contains the following fields:
        • id — client identification
        • name — client name
        • responsible — user responsible for parent entity client. Contains the following fields:
          • id — user identification
          • name — user name
          • ext_num — user PBX extension number

      Lead

      {
      "contact_type": "lead",
      "id": 3486,
      "name": "GoodCompany",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "responsible": {
        "id": 234,
        "name": "John Smith",
        "ext_num": "100"
      }
      }

      where

      • contact_type — contact type:
        • lead — lead
      • id — lead identification
      • name — lead name
      • phone — phone number. Contains the following fields:
        • phone — the number itself
        • type — number type. Possible values:
          • work — work
          • personal — personal
      • responsible — responsible user. Contains the following fields:
        • id — user identification
        • name — user name
        • ext_num — user PBX extension number

      User

      {
          "contact_type": "user",
          "id": 234,
          "name": "John Smith",
          "avatar": 2457,
          "role": "",
          "status": "",
          "phone": {
            "phone": "100",
            "type": "internal"
          },
          "group": {
            "type": "admin",
            "title": ""
          }
        }

      where

      • contact_type — contact type:
        • user — user
      • id — user identification
      • name — user name
      • avatar — user avatar (file identification)
      • role — user role
      • status — user status
      • phone — phone number. Contains the following fields:
        • phone — the number itself
        • type — number type. Possible values:
          • work — work
          • personal — personal
          • internal — PBX extension number
      • group — user group. Contains the following fields:
        • type — group type. Possible values:
          • admin — admins
          • manager — managers
          • chat_operator — operators
          • trainee — trainees
          • custom — custom
        • title — custom group title (for type = custom)

    GET /v1/zcrm/contacts/identify

    Identifies contact (client, employee, lead, user) by the phone number.

    Parameters

    • phone — phone number

    Response

    The response will depend on the found contact (client, employee, lead, user).

    Client

    {
      "contact_type": "customer",
      "id": 3486,
      "name": "GoodCompany",
      "status": "company",
      "type": "client",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "responsible": {
        "id": 234,
        "name": "Jim Beam",
        "ext_num": "100"
      }
    }

    where

    • contact_type — contact type:
      • customer — client
    • id — client identification
    • name — client name
    • status — client status. Possible values:
      • individual — personal user
      • company — company/business
    • type — client type. Possible values:
      • potential — potential client
      • client — client
      • reseller — reseller
      • partner — partner
    • phone — phone number. Contains the following fields:
      • phone — the number itself
      • type — number type. Possible values:
        • work — work
        • personal — personal
    • responsible — responsible user. Contains the following fields:
      • id — user identification
      • name — user name
      • ext_num — user PBX extension number

    Client's employee

    {
      "contact_type": "employee",
      "id": 8,
      "name": "John Smith",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "position": {
        "position": "manager",
        "title": ""
      },
      "customer": {
        "id": 3486,
        "name": "GoodCompany"
      },
      "responsible": {
        "id": 234,
        "name": "Jim Beam",
        "ext_num": "100"
      }
    }

    where

    • contact_type — contact type:
      • employee — employee
    • id — employee identification
    • name — employee name
    • phone — phone number. Contains the following fields:
      • phone — the number itself
      • type — number type. Possible values:
        • work — work
        • personal — personal
    • position — employee position. Contains the following fields:
      • position — position. Possible values:
        • ceo — CEO
        • director — director
        • manager — manager
        • sales_manager — sales manager
        • hr — HR
        • support — support
        • custom — custom
      • title — custom position title (for position = custom)
    • customer — client, to whom the employee is attached. Contains the following fields:
      • id — client identification
      • name — client name
    • responsible — user responsible for the parent entity. Contains the following fields:
      • id — user identification
      • name — user name
      • ext_num — user PBX extension number

    Lead

    {
      "contact_type": "lead",
      "id": 3486,
      "name": "GoodCompany",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "responsible": {
        "id": 234,
        "name": "Jim Beam",
        "ext_num": "100"
      }
    }

    where

    • contact_type — contact type:
      • lead — lead
    • id — lead identification
    • name — lead name
    • phone — phone number. Contains the following fields:
      • phone — the number itself
      • type — number type. Possible values:
        • work — work
        • personal — personal
    • responsible — responsible user. Contains the following fields:
      • id — user identification
      • name — user name
      • ext_num — user PBX extension number

    User

    {
      "contact_type": "user",
      "id": 234,
      "name": "John Smith",
      "avatar": 2457,
      "role": "",
      "status": "",
      "phone": {
        "phone": "100",
        "type": "internal"
      },
      "group": {
        "type": "admin",
        "title": ""
      }
    }

    where

    • contact_type — contact type:
      • user — user
    • id — user identification
    • name — user name
    • avatar — user avatar (file identification)
    • role — user role
    • status — user status
    • phone — phone number. Contains the following fields:
      • phone — the number itself
      • type — number type. Possible values:
        • work — work
        • personal — personal
        • internal — PBX extension number
    • group — user group. Contains the following fields:
      • type — group type. Possible values:
        • admin — admins
        • manager — managers
        • chat_operator — operators
        • trainee — trainees
        • custom — custom
      • title — custom group title (for type = custom)

    GET /v1/zcrm/files/<file_id>

    Gives files by its ID.

    No parameters

     

    Incoming call notifications

    Zadarma system can send information about each call to virtual PBX and route calls onto the necessary extension number depending on the response. In order to do this, create an open link, which will accept POST-requests with information from the Zadarma system.

    Available methods:

    • NOTIFY_START
      the start of an incoming call in the PBX.
    • NOTIFY_INTERNAL
      the start of an incoming call to the PBX extension number.
    • NOTIFY_ANSWER
      the internal or external call response.
    • NOTIFY_END
      the end of an incoming call to the PBX extension number.
    • NOTIFY_OUT_START
      the start of an outgoing call from the PBX.
    • NOTIFY_OUT_END
      the end of an outgoing call from the PBX.
    • NOTIFY_RECORD
      the call recording is ready for download.
    • NOTIFY_IVR
      caller’s response to the assigned action.
    • SPEECH_RECOGNITION
      speech recognition result.

    Parameters that are sent to the link for notifications:

    • event – event (NOTIFY_START)
    • call_start – call start time;
    • pbx_call_id – call id;
    • caller_id – caller number;
    • called_did – number called.

    Creating a verification signature for incoming calls notifications, PHP example:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

    For requests NOTIFY_START and NOTIFY_IVR you can change the scenario for a current call “on the run” by responding with one of the following options:

    Play a file:

    {
        "ivr_play": "ID"
    }

    where,

    • ivr_play – the value of the ID column in the list of uploaded/input files for a needed file.

    Play a popular phrase:

    {
        "ivr_saypopular": 1,
        "language": "en"
    }

    where,

    • ivr_saypopular – the number of the phrase on the list;

    Play digits:

    {
        "ivr_saydigits": "12",
        "language": "en"
    }

    Play a number (in accordance with the rules of complex numerals):

    {
        "ivr_saynumber": "123",
        "language": "en"
    }

    where,

    • language can have one of the following values: ru, ua, en, es, pl;

    If ivr_saydigits or ivr_saynumber were set, during the next NOTIFY_IVR event the following parameter will be added:

    "ivr_saydigits": "COMPLETE" or "ivr_saynumber": "COMPLETE"

    For each of the requests specified above a request to input digits from caller can occur:

    {
        "wait_dtmf": {
            "timeout": TIMEOUT,
            "attempts": ATTEMPTS,
            "maxdigits": MAXDIGITS,
            "name": NAME,
            "default": DEFAULT,
        }
    }

    where,

    • timeout - wait time for digits input in seconds;
    • attempts - number of attempts of digits input from caller;
    • maxdigits - maximum number of digits that are expected to be input;
    • name - name that would be in the response;
    • default - an action if no digits were selected. Options:
      • redirection scenario id (in 0-1 format, where 0 is voice menu number, 1 is a scenario number);
      • PBX menu in 0-main format, where 0 is menu id;
      • PBX extension number (three digits);
      • hangup – end call.

    During the next NOTIFY_IVR event an additional parameter will be specified:

    {
      	"wait_dtmf": {
    	    "name": NAME,
    	    "digits": DIGITS,
    	    "default_behaviour": "1"
        }
    }

    where,

    • name - name specified in the previous response;
    • digits - digits entered by the caller;
    • default_behaviour - specifies if the caller did not press any button and default behaviour worked;

    Transfer call:

    {
        "redirect": ID,
        "return_timeout": TIMEOUT (optional)
    }

    where,

    • redirect - redirect scenario id (in 0-1 format, where 0 is voice menu number, 1 is a scenario number); or in 1 format, where 1 is a scenario number(voice menu number is 0 in this case); or PBX menu in 0-main format, where 0 is menu id; or PBX extension number (three digits); or "blacklist" – in this case the call will be declined with a busy signal;
    • return_timeout - value in seconds. Options:
      • 0, call returns to the menu;
      • >= 3 – internal call duration before the call returns to the menu
    • default_behaviour - specified if the caller did not press anything and default behaviour worked;

    End call:

    {
        "hangup": 1
    }

    For each response you can additionally set:

    A name for incoming number:

    {
    	"caller_name": NAME
    }

    where,

    • caller_name - caller name.

    Lists of popular phrases:

    Parameters glossary:

    • event – the event (NOTIFY_INTERNAL)
    • call_start – the call start time;
    • pbx_call_id – the call ID;
    • caller_id – the caller's phone number;
    • called_did – the phone number that was called;
    • internal – (optional) extension number.

    Creation of verification signature for notification about incoming calls, example on PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

    Parameters glossary:

    • event – the event (NOTIFY_ANSWER)
    • caller_id – the caller's phone number;
    • destination – the phone number that was called;
    • call_start – the call start time;
    • pbx_call_id – the call ID;
    • internal – (optional) extension number.

    Creation of verification signature for notification about incoming calls, example on PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

    Parameters glossary:

    • event – the event (NOTIFY_END)
    • call_start – the call start time;
    • pbx_call_id – the call ID;
    • caller_id – the caller's phone number;
    • called_did – the phone number that was called;
    • internal – (optional) extension number;
    • duration – length in seconds;
    • disposition – call status:
      • 'answered' – conversation,
      • 'busy' – busy,
      • 'cancel' - cancelled,
      • 'no answer' - no answer,
      • 'failed' - failed,
      • 'no money' - no funds, the limit has been exceeded,
      • 'unallocated number' - the phone number does not exist,
      • 'no limit' - the limit has been exceeded,
      • 'no day limit' - the day limit has been exceeded,
      • 'line limit' - the line limit has been exceeded,
      • 'no money, no limit' - the limit has been exceeded;
    • last_internal – extension number, the last call participant (after transfer or pickup);
    • status_code – call status code Q.931;
    • is_recorded – 1 - there is a call recording, 0 - there is no call recording;
    • call_id_with_rec – the ID of the call with call recording (we recommend you to download the recorded file in 40 seconds after the notification, as certain time period is needed for the file with the recording to be saved).

    Creation of verification signature for notification about incoming calls, example on PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

    Parameters glossary:

    • event – the event (NOTIFY_OUT_START)
    • call_start – the call start;
    • pbx_call_id – the call ID;
    • destination – the phone number that was called;
    • internal – (optional) extension number.

    Creation of verification signature for notification about incoming calls, example on PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['internal'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

    Parameters glossary:

    • event – the event (NOTIFY_OUT_END)
    • call_start – the call start time;
    • pbx_call_id – the call ID;
    • caller_id – the caller's phone number;
    • destination – the phone number that was called;
    • internal – (optional) extension number;
    • duration – length in seconds;
    • disposition – call status:
      • 'answered' – conversation,
      • 'busy' – busy,
      • 'cancel' - cancelled,
      • 'no answer' - no answer,
      • 'failed' - failed,
      • 'no money' - no funds, the limit has been exceeded,
      • 'unallocated number' - the phone number does not exist,
      • 'no limit' - the limit has been exceeded,
      • 'no day limit' - the day limit has been exceeded,
      • 'line limit' - the line limit has been exceeded,
      • 'no money, no limit' - the limit has been exceeded;
    • status_code – call status code Q.931;
    • is_recorded – 1 - there is a call recording, 0 - there is no call recording;
    • call_id_with_rec – the ID of the call with call recording (we recommend you to download the recorded file in 40 seconds after the notification, as certain time period is needed for the file with the recording to be saved).

    Creation of verification signature for notification about incoming calls, example on PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['internal'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

    Parameters glossary:

    • event – the event (NOTIFY_RECORD)
    • call_id_with_rec – unique ID of the call with the call recording;
    • pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications).

    Creation of verification signature for notification about incoming calls, example on PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

    Parameters that are sent to the link for notifications:

    • event – event (NOTIFY_IVR)
    • call_start – call start time;
    • pbx_call_id – call id;
    • caller_id – caller number;
    • called_did – called number.

    Creating a verification signature for incoming calls notifications, PHP example:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

    Possible responses sent to similar responses as to NOTIFY_START requests

    Parameters that are sent to the link for notifications:

    • event – event (SPEECH_RECOGNITION)
    • lang – language;
    • result:
      • words - array:
        • result - list of words (array):
          • s - word beginning time
          • e - word ending time
          • w - word
        • channel - channel number
      • phrases - array:
        • result - phrase
        • channel - channel number

    You can set the link for notifications and enable or disable each type of the notification in the API section of your personal profile.

    In order for the link to be accepted by our system, it is necessary to add the verification code in the beginning of script.

    PHP example:

    <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>

    For security reasons, we recommend you to allow access to your link only from the following IP: 185.45.152.42.

    If you have issued the keys for access to the API, each request will receive an additional header "Signature", which can be used to compare data consistency and authenticity.

    You can see a script example in our repository on GitHub.

    Other notifications:

    Parameter "result" in these notification is set in JSON format. You can receive it in XML format by entering parameter format=xml in the link.

    • NUMBER_LOOKUP
      number lookup report.
    • CALL_TRACKING
      information about calls to the numbers connected to call tracking.
    • SMS
      information about incoming SMS messages.

    Parameters that are sent to the link for notifications:

    • event – event (NUMBER_LOOKUP)
    • success – successful lookup flag;
    • description – textual description of the lookup completion status;
    • result – report results;
      • number – number that is being checked;
      • mcc – mobile country code;
      • mnc – mobile network code;
      • ported – an indication that the number has been ported to another provider;
      • roaming – an indication that the number is currently in roaming zone;
      • error – error status indication;
      • errorDescription – textual description of the error;
      • mccName – country name;
      • mncName – provider name;

    Creating a verification signature:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

    It is sent out every 15 minutes, provided there are new calls.

    Parameters that are sent to the link for notifications:

    • event – event (CALL_TRACKING)
    • result - array
      • tracker - ID tracker (can be found on the code installation page);
      • start - call starting time;
      • duration - call duration in seconds;
      • caller_id - caller’s number;
      • caller_did - the number that was called;
      • country - (optional) the country the call was made from;
      • ga_id - (optional, if Google Analytics ID is specified in the settings) Google Analytics ID of the visitor;
      • metrika_id - (optional, Yandex.Metrika ID is specified in the settings) Yandex.Metrika ID of the visitor;
      • url - address of the page from which the call originated;
      • utm_source, utm_medium, utm_campaign, utm_term, utm_content - (optional, if utm tags were specified when visiting the website) utm tags specified during the last website visit by the user;
      • first_utm - (optional, if utm tags during the first visit differ from the ones specified during the last visit) array of utm tags mentioned above used by the visitor to access the website for the first time;

    Creating a verification signature:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

    Parameters that are sent to link for notifications:

    • event – event (SMS)
    • result – array;
    • caller_id – senders number;
    • caller_did – receivers number;
    • text – message text.

    Creating a verification signature:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));