API navigation

Introduction

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 )
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

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

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.

Methods

get /v1/info/balance/

                                        {
    "status":"success", 
    "balance":10.34, 
    "currency":"USD"
}
                                    

user balance

get /v1/info/price/

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

call rate in the user's current price plan

Parameters:

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


get /v1/info/timezone/

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

user's timezone

get /v1/tariff/

                                        {
    "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
    }
}
                                    

information about the user's current price plan

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.

get /v1/request/callback/

                                        {
    "status":"success", 
    "from":442037691880, 
    "to":442037691881, 
    "time":1435573082
}
                                    

callback

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.);

post /v1/sms/send/

                                        {
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}
                                    

sending the SMS messages

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

post /v1/info/number_lookup/

                                        Response 1:
{ "status":"success", "info":{ "mcc":"250", "mnc":"01", "mccName":"Russia", "mncName":"Mobile TeleSystems", "ported":false, "roaming":false, "errorDescription":"No Error" } }
                                        Response 2:
{ "status":"success" }
                                        Response 3:
{ "success":true, "description":"Success", "result": [ { "mcc":"250", "mnc":"01", "ported":false, "roaming":false, "errorDescription":"No Error", "mccName":"Russia", "mncName":"Mobile TeleSystems", "number":"791234567890", }, ... ] }

user database check

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:

Example of the result for several numbers:

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

SIP

get /v1/sip/

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

the list of user's SIP-numbers

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).

get /v1/sip/<SIP>/status/

                                        {
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}
                                    

the user's SIP number online status

put /v1/sip/callerid/

                                        {
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}
                                    

changing of the CallerID

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.

get /v1/sip/redirection/

                                        {
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"442037691880"
        },
    ...
    ]
}
                                    

display of the current call forwarding based on the user's SIP numbers

Parameters:

  • id – (optional) selection of the specific SIP ID.

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.

put /v1/sip/redirection/

                                        {
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}
                                    

call forwarding switch on/off based on the SIP number

Parameters:

  • id – SIP ID;
  • status – the call forwarding status on the selected SIP number.

put /v1/sip/redirection/

                                        {
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}
                                    

changing of the call forwarding parameters

Parameters:

  • id – SIP ID;
  • type – call forwarding type: phone – to the phone;
  • number – phone number.

Statistics

get /v1/statistics/

                                        Response 1:
{ "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" }, … ] }
                                        Response 2:
{ "status":"success", "start":"2015-06-01 00:00:00", "end":"2015-06-29 14:03:57", "stats":[ { "cost":38.094, "currency":"USD", "seconds":9785 } ] }

receive overall statistics

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.

?type=cost_only: (Response 2)

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.

get /v1/statistics/pbx/

                                        {
    "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"
        },
        …
    ]
}
                                    

PBX statistics

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.

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);

get /v1/statistics/callback_widget/

                                        {
    "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"
                }
            ]
        },
        ...
    ]
}
                                    

callBack widget statistics

json_0 xml_0

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.

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').

PBX

get /v1/pbx/internal/

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

the PBX extension numbers display

where

  • pbx_id – the user's PBX ID;
  • numbers – the list of extension numbers.

get /v1/pbx/internal/<PBXSIP>/status/

                                        {
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}
                                    

online status of the PBX extension number

where

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

put /v1/pbx/internal/recording/

                                        {
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com"
}
                                    

enabling of the call recording on the PBX extension number

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.

get /v1/pbx/record/request/

                                        Response 1:
{ "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 2:
{ "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" }

call recording file request

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.

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

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

Parameters:

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

post /v1/pbx/redirection/

                                        {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer"
}
                                    

changing of the call forwarding parameters on the PBX extension number

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;

get /v1/pbx/redirection/

                                        {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
}
                                    

receiving call forwarding parameters on the PBX extension number

Parameters:

  • pbx_number – PBX extension number, for example 100;

Speech recognition

get /v1/speech_recognition/

                                        {        
    "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
        }
    ]
}
                                    

obtaining recognition results

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).

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

put /v1/speech_recognition/

                                        {
    "status":"success"
}
                                    

start recognition

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).

Virtual numbers

get /v1/direct_numbers/

                                        {
    "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"
        },
    ...
    ]
}
                                    

information about the user's phone numbers

Parameters:

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).

get /v1/direct_numbers/number/

                                        {
    "status": "success",
    "info": {
    "number": "35924913550",
        "status": "on",
        "country": "Bulgaria",
        "description": "Sofia",
        "number_name": "TT",
        "sip": "00004",
        "sip_name": "SIP",
        "start_date": "2016-06-08 14:32:17",
        "stop_date": "2016-06-29 10:52:18",
        "monthly_fee": 2,
        "currency": "USD",
        "channels": "2",
        "autorenew": "true",
        "receive_sms": null,
        "is_on_test": "false"
    }
}
                                    

purchased number information

Parameters:

  • type - can have one of three values:
    • 'revenue' - Free Moscow 495 number;
    • 'inum' - Free international number;
    • 'common' - Regular number, all others;
  • number - number.

get /v1/direct_numbers/autoprolongation/

                                        {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "on"
}
                                    

automatic extension status (NB! inum not included in this list)

Parameters:

  • type - can have one of two values:
    • 'revenue' - Free Moscow 495 number;
    • 'common' - Regular number, all others;
  • number - number.

put /v1/direct_numbers/autoprolongation/

                                        {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "off"
}
                                    

change automatic extension status (NB! inum not included in this list)

Parameters:

  • type - can have of two values:
    • 'revenue' - Free Moscow 495 number;
    • 'common' - Regular number, all others;
  • number - number;
  • value - new automatic extension status, on or off.

get /v1/direct_numbers/countries/

                                        {
    "status": "success",
    "info": [
        {
            "countryCode": "61",
            "countryCodeIso": "AU",
            "name": "Australia"
        },
        ...
    ]
}
                                    

list of countries numbers can be ordered from

Parameters:

  • language - optional, if not set Personal account language will be used.

get /v1/direct_numbers/country/

                                        {
    "status": "success",
    "info": [
        {
            "id": "3753",
            "countryCode": "49",
            "areaCode": "800",
            "name": "Номер 800 (Toll-free)",
            "connect_fee": 0,
            "monthly_fee": 15,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Certificate of registration copy or passport or ID copy (both sides)",
                    "Proof of address (a copy of utility bill no older than of 6 months) - 
                    your current address (city, street, number and postal code). 
                    The address must be located in the country of ordered phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "true",
            "feature": "Available from all networks"
            "connect_time": "0"
        },
        {
            "id": "3766",
            "countryCode": "49",
            "areaCode": "821",
            "name": "Аугсбург",
            "connect_fee": 3,
            "monthly_fee": 3,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Passport or ID copy (both sides)"
                ],
                "specify": [
                    "You current address (city, street, number and postal code). 
                    The address must be located in the region of the city 
                    where you ordered the phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "false",
            "feature": null,
            "connect_time": "0"
        },
        ...
    ]
}
                                    

list of destinations in the country, where a number can be ordered

Parameters

  • language - optional, if not set Personal account language will be used;
  • country - iso country code (ISO 3166-1 alpha-2).

put /v1/direct_numbers/set_caller_name/

                                        {
    "status": "success",
    "number": "74996388980",
    "caller_name": "test"
}
                                    

caller name setup

Parameters

  • type - can have one of two values:
    • 'revenue' - Free Moscow 495 number;
    • 'common' - Regular number, all others;
  • number - number;
  • caller_name - to clear - just submit an empty field.

put /v1/direct_numbers/set_sip_id/

                                        {
    "status": "success",
    "number": "74996388980",
    "sip_id": "00001"
}
                                    

assigning a number to sip or test mode enabling

Parameters

  • type - can have one of three values:
    • 'revenue' - Free Moscow 495 number;
    • 'inum' - Free international number;
    • 'common' - Regular number, all others;
  • number - number;
  • sip_id - sip number or external server address;
  • test_mode - optional, (on|off) - for enabling test mode.

ZCRM methods

Clients

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. Filter structure:

Response 1

Response 1:
{ "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:

Response 2

Response 2:
{ "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

Response 3

Response 3:
{ "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

Response

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

Response 1

Response 1:
{ "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:

Response 2

Response 2:
{ "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:

Response

Response:
{ "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

Labels

get /v1/zcrm/customers/labels

Restores the list of all labels and their statistics

Response

Response

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

Response

Response:
{ "id": 13, "label": "Very 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

Additional features

get /v1/zcrm/customers/custom-properties

Restores additional features

Response

Response

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

Client timeline

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

Restores records in client timeline

Address parameters

  • c_id — client identification

Response

Response

Response:
{ "totalCount": 17, "items": [ { "id": 37825, "type": "note", "content": "Call to the client", "time": "2020-06-08 06:55:02", "user_id": 20, "user_name": "John Beam", "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": "document.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

Response

Response:
{ "id": 37825, "type": "note", "content": "Call to the client", "time": "2020-06-08 06:55:02", "user_id": 20, "user_name": "John Beam", "attached_files": [ { "file_id": 576, "original_filename": "document.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

Employees

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

Restores client employees list by its ID

Address parameters

  • c_id — client identification

Response

Response

Response:
{ "totalCount": 5, "employees": [ { "id": 23, "customer_id": 11, "name": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@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

Response

Response:
{ "id": 23, "customer_id": 11, "name": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@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:

Response 1

Response 1:
{ "name": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@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

Response 2

Response 2:
{ "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:

Response

Response:
{ "name": "Steven Knight", "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

Tasks

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:

Response 1

Response 1:
{ "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:

Response 2

Response 2:
{ "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

Response 3

Response 3:
{ "totalCount": 4, "events": [ { "id": 40, "type": "task", "title": "Create text for Good Company", "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": "Good Company", "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)
    • 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

Response

Response:
{ "id": 40, "type": "task", "title": "Create text for Good Company", "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": "Good Company", "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)
  • 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:

Response 1

Response 1:
{ "type": "task", "title": "Create text for Good Company", "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)
  • 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

Response 2

Response 2:
{ "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:

Response

Response:
{ "title": "Create text for Good Company", "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)
  • 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>

Completes (closes) the task

Parameters

  • comment (optional) - comment

delete /v1/zcrm/events/<event_id>

Deleted a task by its ID

Leads

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:

Response 1

Response 1:
{ "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:

Response 2

Response 2:
{ "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

Response 3

Response 3:
{ "totalCount": 100, "uncategorizedCount": 10, "leads": [ { "id": 3486, "name": "Good Company", "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

Response

Response:
{ "id": 3486, "name": "Good Company", "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": "Лучшие клиенты" } ], "custom_properties": [ { "id": 12, "key": "loyalty", "title": "Лояльность", "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:

Response 1

Response 1:
{ "name": "Good Company", "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 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

Response 2

Response 2:
{ "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:

Response

Response:
{ "name": "Good Company", "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

Users

get /v1/zcrm/users

Restores users list

Response

Response

Response:
{ "totalCount": 2, "users": [ { "id": 234, "email": "john@example.com", "name": "John Beam", "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": "ivanov@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

Response

Response:
{ "id": 234, "email": "john@example.com", "name": "John Beam", "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": "simpson@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

Response

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

Response

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

Calls

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:

Response 1

Response 1:
{ "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:

Response 2

Response 2:
{ "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

Response 3

Response 3:
{ "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": "Good Company", "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

Generalized contacts

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

Response 1

Response 1:
{ "totalCount": 128, "contacts": [ { "contact_type": "customer", }, { "contact_type": "employee", }, { "contact_type": "lead", }, { "contact_type": "user", } ] }

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

Response 2

Response 2:
{ "contact_type": "customer", "id": 3486, "name": "Good Company", "status": "company", "type": "client", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John 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 field:
    • id — user identification
    • name — user name
    • ext_num — user PBX extension number

Client's employee

Response 3

Response 3:
{ "contact_type": "employee", "id": 8, "name": "Michael Simpson", "phone": { "phone": "+44123456789", "type": "work" }, "position": { "position": "manager", "title": "" }, "customer": { "id": 3486, "name": "Good Company" }, "responsible": { "id": 234, "name": "John 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 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

Response 4

Response 4:
{ "contact_type": "lead", "id": 3486, "name": "Good Company", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John 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

Response 5

Response 5:
{ "contact_type": "user", "id": 234, "name": "John Beam", "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

Response 1

Response 1:
{ "contact_type": "customer", "id": 3486, "name": "Good Company", "status": "company", "type": "client", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John 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

Response 2

Response 2:
{ "contact_type": "employee", "id": 8, "name": "Michael Simpson", "phone": { "phone": "+44123456789", "type": "work" }, "position": { "position": "manager", "title": "" }, "customer": { "id": 3486, "name": "Good Company" }, "responsible": { "id": 234, "name": "John 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

Response 3

Response 3:
{ "contact_type": "lead", "id": 3486, "name": "Good Company", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John 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

Response 4

Response 4:
{ "contact_type": "user", "id": 234, "name": "John Beam", "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)

Files

get /v1/zcrm/files/<file_id>

Gives files by its ID

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

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:

Response

Response:
$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:

Response 1

Response 1:
{ "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:

Response 2

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

where,

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

Play digits:

Response 3

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

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

Response 4

Response 4:
{ "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:

Response 5

Response 5:
{ "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:

Response 6

Response 6:
{ "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:

Response 7

Response 7:
{ "redirect": ID, "return_timeout": TIMEOUT (необязательное) }

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:

Response 8

Response 8:
{ "hangup": 1 }

For each response you can additionally set:

A name for incoming number:

Response 9

Response 9:
{ "caller_name": NAME }

where,

  • caller_name - caller name.

Lists of popular phrases:

  • Hello
  • Good afternoon
  • Call forwarding
  • Call from the website
  • Welcome
  • Test message
  • Please stay on the line
  • You have reached us outside our working hours
  • Currently all our agents are busy, you call will be answered shortly
  • Enter caller’s extension number
  • Enter employee’s extension number
  • Enter the extension number
  • Please hold
  • Enter the extension number and hold to connect with a representative
  • Please leave a message
  • Please leave a message after the tone
  • Please call back during our work hours
  • Thank you for calling our company
  • Thank you for calling
  • Please hold to be connected to a representative
  • Your call is very important to us
  • The call is being recorded
  • We are currently unavailable to take your call
  • We will return your call as soon as possible
  • We are out of the office today

NOTIFY_INTERNAL

the start of an incoming call to the PBX extension number

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:

Response

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

NOTIFY_ANSWER

the internal or external call response

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:

Response

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

NOTIFY_END

the end of an incoming call to the PBX extension number

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:

Response

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

NOTIFY_OUT_START

the start of an outgoing call from the PBX

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:

Response

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

NOTIFY_OUT_END

the end of an outgoing call from the PBX

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:

Response

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

NOTIFY_RECORD

the call recording is ready for download

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:

Response

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

NOTIFY_IVR

caller’s response to the assigned action

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:

Response

Response:
$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

SPEECH_RECOGNITION

speech recognition result

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

Parameters that send out a notification link:

  • event – event (NUMBER_LOOKUP);
  • success – successful check flag;
  • description – textual description of check completion status;
  • result – report results;
    • number – checked number;
    • mcc – mobile country code;
    • mnc – mobile network code;
    • ported – sign of number porting to other provider;
    • roaming – sign of being in roaming;
    • error – error status;
    • errorDescription – textual error description;
    • mccName – country name;
    • mncName – provider name;

Test signature creation:

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

CALL_TRACKING

information about calls to the numbers connected to call tracking

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));

SMS

information about incoming SMS messages

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));