fb

API

Zadarma API interface allows to use our service for personal applications and also for integration with any CRM system and softphones for call centers.

API is very simple to use and every developer would be up for the task.

The following functions are available in API:

  • Displaying and changing of settings for SIP and PBX;
  • Displaying statistics and balance;
  • Calls and SMS (CallBack to internal and external numbers);
  • External server notifications regarding every incoming call and also external routing of the call.

Link for API: https://api.zadarma.com

API version: v1

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

You can download our PHP and Python classes on our GitHub.

Authorization

Each request that requires authorization, should be set with the additional header:

"Authorization: user_key: signature"

Keys for authorization must be generated in Zadarma personal account.

The signature is made by following the algorithm:

  • The array of transmitted data (GET, POST, PUT, DELETE) is sorted by key name in alphabetical order;
  • The received array forms the query strip (for example, function http_build_query in PHP), example "from=DATEFROM&to=DATETO…";
  • And then concatenated in the following way:
    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 resulted string is hashed by the algorithm sha1 with user secret key:
    hash = line, secret key
  • And then the hash is encrypted in base64
    signature = base64_encode( hash )

PHP Example:

ksort($params);
$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);
$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));

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

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

Response formats: json (by default) and xml.

In order to get the response from the API in xml format, the following parameter must be added to the request line "format=xml".

Restrictions

The response also 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 – the current requested method;
  • X-RateLimit-Remaining – the amount of requests left 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 consists of a mandatory "status" key (success or error). Afterwards, depending on the method, corresponding keys are provided with requested information.

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

Also all responses are provided with corresponding HTTP-headers.

Example of error response:
JSON:

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

XML:

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

Available methods:

GET /v1/info/balance/ - user balance.

read more

Example:
JSON:

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

XML:

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

GET /v1/info/price/ - call rate in user's current tariff plan.

read more

Parameters:
  • number – phone number
  • caller_id (optionally) – CallerID, which will be used for outgoing call.
Example:
JSON:

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

XML:

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

GET /v1/info/timezone/ - user timezone.

read more

Example:
JSON:

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

    XML:

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

GET /v1/tariff/ - information about current tariff plan of user.

read more

Answer example:
JSON:

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

XML:

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

where,

  • tariff_id – ID of current tariff plan of user;
  • tariff_name – name of current tariff plan of user;
  • is_active – active or not active current tariff plan;
  • cost – tariff plan price;
  • currency – tariff plan currency;
  • used_seconds – amount of used seconds in tariff plan;
  • used_seconds_mobile – amount of used seconds in tariff plan on mobile numbers;
  • used_seconds_fix – amount of used seconds in tariff plan on landline numbers;
  • tariff_id_for_next_period – ID of tariff plan of user for next period;
  • tariff_for_next_period – name of tariff plan of user on next period.

GET /v1/request/callback/ - callback request.

read more

Parameters:
  • from – your phone number, or sip number, or extension number of IP PBX, or call scenario of IP PBX, on which callback is requested;
  • to – phone number or SIP number, which is called;
  • sip (optionally) – user SIP number or extension number of IP PBX (for example 100), from which will be call made. CallerID of this number will be used, in statistics will be displayed given SIP number or number of IP PBX, if for that number call recording option or prefixes for outgoing calls are enabled, they will be also used;
  • predicted (optional) – if flag put down, then request is predictive (system calls on number "to" and if call is answered it joins with your SIP or phone number);
Example:
JSON:

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

XML:

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

GET /v1/sip/ - list of user's SIP-numbers.

read more

Example:
JSON:

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

XML:

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

where,

  • id – SIP-id;
  • display_name – displayed name;
  • lines – amount of lines;
  • left – amount of SIP which can be added (depends on user's balance and total amount of already added SIP).

GET /v1/sip/<SIP>/status/ - online-status of user SIP login.

details

Example of answer:
JSON:

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

    XML:

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

where,

  • id – SIP-id;
  • is_online – online-status (true|false);

PUT /v1/sip/callerid/ - changing of CallerID.

read more

Parameters:
  • id – SIP id, on which CallerID is changed;
  • number – phone number in international format to which is (from the list of confirmed or ordered user's).
Example:
JSON:

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

XML:

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

GET /v1/sip/redirection/ - displaying of current call forwarding on user's SIP-numbers.

read more

Parameters:
  • id – (optional) chooses definite SIP id.
Example:
JSON:
{
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"442037691880",
        },
        ...
    ]
}

XML:

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

where,

  • sip_id – user's SIP id;
  • status – current status: on or off;
  • condition – conditions of call forwarding: always – always (by default), unavailable – in case of absence of answer or SIP connection;
  • destination – to where is forwarded: phone – on phone number, pbx – on PBX;
  • destination_value – number on which to forward: phone number or PBX ID.

GET /v1/direct_numbers/ - information about phone numbers (DID) of user.

read more

Answer example:
JSON:

{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false"
            "type":"common"
        },
        ...
    ]
}

XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Great Britain</country>
            <description>London</description>
            <number_name>null</number_name>
            <sip>00001</sip>
            <sip_name>Example</sip_name>
            <start_date>2015-01-01 18:14:44</start_date>
            <stop_date>2016-02-11 18:14:40</stop_date>
            <monthly_fee>2</monthly_fee>
            <currency>USD</currency>
            <channels>2</channels>
            <autorenew>true</autorenew>
            <is_on_test>false</is_on_test>
            <type>common</type>
        </value>
        ...
    </info>
    </answer>

Depending on type of number, set of fields can vary.! Fields description:

  • number – connected by user phone number;
  • status – status of number;
  • country – country (for common and revenue);
  • description – description: city or type (for common and revenue);
  • number_name – "name" of phone number (set by user);
  • sip – SIP, connected to number;
  • sip_name – "name" of SIP, connected to number;
  • start_date – date when user connected number;
  • stop_date – date when user should pay for number;
  • monthly_fee – cost for number (for common);
  • currency – currency in which number is paid (for common);
  • channels – amount of channels on number (for common);
  • minutes – total duration of incoming calls for current month (for revenue);
  • autorenew – enabled or not autoprolongation for number (for common, revenue, rufree);
  • is_on_test – number is on test or not;
  • type – three numbers: common (phone number), inum (free international number), rufree (free Russian number), revenue (free Moscow number in code 495)

GET /v1/sim/ - information about SIM-cards of user.

read more

Example of answer:
JSON:

{
    "status":"success",
    "sims": [
        {
            "iccid":"8923416550000723980",
            "name":"My Sim",
            "sip":"00001",
            "phone_number":" 447978027321",
            "redirect_to":"simcard",
            "status":"enabled",
            "internet":"on"
        },
        ...
    ]
}

XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <sims>
        <value>
            <iccid>8923416550000723980</iccid>
            <name>My Sim</name>
            <sip>00001</sip>
            <phone_number> 447978027321</phone_number>
            <redirect_to>simcard</redirect_to>
            <status>enabled</status>
            <internet>on</internet>
        </value>
        ...
    </sims>
    </answer>

where,

  • iccid – SIM-card ID;
  • name – SIM-card "name";
  • sip – to which SIP login is connected card;
  • phone_number – card phone number;
  • redirect_to – to where incoming calls on card are forwarded (variant: simcard, phone number);
  • status – current status of SIM-card;
  • internet – enabled/disabled Internet connection.

PUT /v1/sip/redirection/ - able/disable of forwarding by sip.

read more

Parameters:
  • id – SIP id;
  • status – status: "on_email" - turn on the sending of the call recordings only to email, "off_email" - turn off the sending of the call recordings only to email, "on_store"- turn on the saving of the call recordings only to the cloud, "off_store" - turn off the saving of the call recordings only to the cloud;
Example:
JSON:

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

XML:

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

PUT /v1/sip/redirection/ - changing parameters of forwarding.

read more

Parameters:
  • id – SIP id;
  • type – type of forwarding: phone – on phone;
  • number – phone number.
Example:
JSON:

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

XML:

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

GET /v1/pbx/internal/ - map PBX extension numbers.

read more

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

XML:

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

where,

  • pbx_id – id PBX user;
  • numbers – a list of extension numbers.

GET /v1/pbx/internal/<PBXSIP>/status/ - PBX inner number online-status.

read more

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

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

де,

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

PUT /v1/pbx/internal/recording/ - the inclusion of call recording to an internal PBX.

read more

Options:
  • id – internal PBX number;
  • status – status: "on" - switch on, "off" - switch off;
  • email – (optional) change your email address, which will be sent to record conversations. You can specify up to 3 email addresses separated by comma.
Example:
JSON:

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

XML:

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

GET /v1/pbx/record/request/ - request on call recording file.

read more

Parameters:
  • call_id – unique id of the call, Id listed in the title of the call recording file (is unique for each of the records);
  • pbx_call_id – permanent ID for the external call through PBX (is not changing during the passage of scripts, IVR, transfer etc., displayed in statistics and notifications);
  • lifetime – (optional) lifetime of link in seconds (minimal - 180, maximal - 5184000, by default - 1800).

Note: it's enough to specify one of two parameters of identification (pbx_call_id or call_id), if pbx_call_id is specified then in response on request can be several links

Example of response when only call_id is specified, only one link:
JSON:

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

    XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
    </answer>
Example of response when only pbx_call_id is specified, might be several links:
	JSON:
    {
        "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"
    }

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

where,

  • link – link on file with call recording;
  • lifetime_till – time till which link will be active.

POST /v1/sms/send/ - SMS sending.

read more

Parameters:
  • number – phone number, on which to send SMS (can be listed several separated by a comma);
  • message – message (standard text limits in SMS, in case if limit is exceeded – splits on several SMS);
  • caller_id – (optional) phone number, from whom SMS is sent (can be sent only from list of user's confirmed numbers).

Note: SMS sending is not available to Russian Federation.

Example:
JSON:

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

XML:

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

GET /v1/statistics/ - get common statistics.

read more

Parameters:
  • start - start date to view (format - Y-m-d H:i:s);
  • end - end date to view (format - Y-m-d H:i:s);
  • sip (optional) - filter by specific SIP-number;
  • cost_only (optional) – review of only spent funds for period;
  • type (optional – only for common statistics) – type of request: common (not specified in request), toll and ru495. (for numbers 800 and free 495 statistics)

Maximum period of getting statistics is 30 days. In case limit is exceeded in request time period will be shortened to 30 days. If start date is not specified, beginning of current month will be chosen. If end date is not specified, request is limited by current date and time.

Example:
JSON:

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

XML:

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

where,

  • start – start date of statistics displaying;
  • end – end date of statistics displaying;
  • id – call id;
  • sip – SIP-number;
  • callstart – time of call start;
  • description – description of call destination;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • billseconds – amount of seconds;
  • cost – rate for one minute of call on this destination;
  • billcost – cost of paid minutes;
  • currency – cost currency;
  • from – from which number call was made;
  • to – to which number call was made.
?type=cost_only:
JSON:

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

XML:

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

where,

  • cost – cost of calls for chosen period;
  • currency – cost currency;
  • seconds – amount of seconds.

GET /v1/statistics/pbx/ - PBX statistics

read more

Parameters:
  • start - start date to view statistic (format - Y-m-d H:i:s);
  • end - end date to view statistic (format - Y-m-d H:i:s);
  • version - data format of statistics leading out (2 - new, 1 - old);
Example
JSON:

{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}

XML:

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

where,

  • start – start date of statistics displaying;
  • end – end date of statistics displaying;
  • version - data format of statistics leading out (2 - new, 1 - old);
  • call_id – call id;
  • sip – SIP-number;
  • callstart – time of call start;
  • clid – CallerID;
  • destination – call destination;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • seconds – number of seconds in call;
  • is_recorded – (true, false) recorded or not;
  • pbx_call_id – permanent ID for the external call through PBX (is not changing during the passage of scripts, IVR, transfer etc., displayed in statistics and notifications);

GET /v1/statistics/callback_widget/ - Callback widget statistics

read more

Parameters:
  • start - start date to view statistic (format - Y-m-d H:i:s);
  • end - end date to view statistic (format - Y-m-d H:i:s);
  • widget_id - (optional) - widget identificator, in case of absence of parameter is taken statistics for all widgets;

Maximal period of getting statistics is 30 days. In case limit is exceeded in request time period will be shortened to 30 days. If start date is not specified, beginning of current month will be chosen. If end date is not specified, request is limited by current date and time.

Example:
JSON:

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

    XML:

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

where,

  • start – start date of statistics displaying;
  • end – end date of statistics displaying;
  • id – session id;
  • widget_id – widget id;
  • sip – SIP-number;
  • ip – user IP-address;
  • kind – event type:
    • 'come' – user came on page with widget,
    • 'show' – shown widget form,
    • 'call' – callback request,
    • 'call_request' – delayed callback request,
    • 'rate' – user rated call,
    • 'fail' – user reported that callback failed,
    • 'close' – user closed widget form;
  • date – date and time of event;
  • referrer_url – URL, from which user came on page with wodget (only for event 'come');
  • url – URL of page with widget (only for event 'come');
  • rate – for event 'show' - amount of points, for event 'rate' - call rate;
  • request_call_date – date and time specified by user as convenient for callback (only for event 'call_request');
  • redial – (true, false) was there a callback for delayed callback request (only for event 'call_request');
  • number – number entered by user (for events 'call', 'call_request', 'rate', 'fail').

POST /v1/info/number_lookup/ - user database checks

details

Parameters:
  • numbers – the list of phone numbers for checking (in international format).

If the numbers parameter has 1 phone number, the result will be returned straight away. If several phone numbers have been specified in this parameter, the result will be sent to the URL address specified on the User Database Checks page, otherwise it will be sent to the email address.

Please note: the setup of this method is done on the User Database Checks page of your personal profile.

Response example for 1 phone number check:
JSON:
{
    "status":"success",
    "info":{
        'mcc' : '234',
        'mnc': '15',
        'mccName': 'United Kingdom',
        'mncName': 'Vodafone',
        'ported': false,
        'roaming': false,
        'errorDescription': 'No Error'
    }
}
Response example for several phone numbers check:
JSON:
{
    "status":"success"
}
Response example, sent to the URL address, specified on the User Database Checks page:
JSON:
{
    'success': true,
    'description': 'Checked sucessfully',
    'result': [
        {
            'mcc': '234',
            'mnc': '15',
            'ported': false,
            'roaming': false,
            'errorDescription': 'No Error',
            'mccName': 'United Kingdom',
            'mncName': 'Vodafone',
            'number': '4412345678910',
        }, ...
    ]
}

If the specified address has the format=xml parameter, the result will be sent in xml format, in other cases - json format will be used.

Call notification

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.

Existing types of notifications:

NOTIFY_START - start of incoming call in PBX.

details

Glossary of Parameters:

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

NOTIFY_INTERNAL - start of incoming call on extension number of PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_INTERNAL)
  • call_start – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • called_did – called party number;
  • internal – (optional) extension number.

NOTIFY_ANSWER - internal or external call answer.

details

Glossary of Parameters:

  • event – event (NOTIFY_INTERNAL)
  • call_start – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • destination – called party number;
  • internal – (optional) extension number.

NOTIFY_END - end of incoming call on extension number of PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_END)
  • call_start – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • called_did – called party number;
  • internal – (optional) extension number;
  • duration – duration in seconds;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • status_code – call status code Q.931;
  • is_recorded – 1 - call recording is available, 0 - no call recording;
  • call_id_with_rec – call id with recording (it will take up to 40 seconds for your file to be saved. We recommend you to wait for a minute before downloading it).

NOTIFY_OUT_START - start of outgoing call from PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_OUT_START)
  • call_start – call start time;
  • pbx_call_id – call id;
  • destination – number on which call was made;
  • internal – (optional) extension number.

NOTIFY_OUT_END - end of outgoing calla from PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_OUT_END)
  • call_start – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • destination – number on which call was made;
  • internal – (optional) extension number;
  • duration – duration in seconds;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • status_code – call status code Q.931;
  • is_recorded – 1 - call recording is available, 0 - no call recording;
  • call_id_with_rec – call id with recording (it will take up to 40 seconds for your file to be saved. We recommend you to wait for a minute before downloading it).

NOTIFY_RECORD - call recording is ready for download.

show more

Glossary of Parameters:

  • event – event (NOTIFY_RECORD)
  • call_id_with_rec – call unique ID with recording;
  • pbx_call_id – PBX outgoing call permanent ID (does not change with change of scenarios, voice menu, forwarding, etc., displayed in statistics and notifications).

Set the link for notifications, switch on/off each type of notification you can in personal account, section API.

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

Example on PHP:

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

For security reasons we recommend allowing access to your link only from IP 185.45.152.42.

Also if you issued keys for access to API, each request will receive an additional header "Signature", which can be used to compare data consistency and integrity.

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

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

For NOTIFY_OUT_START and NOTIFY_OUT_END:

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

For NOTIFY_RECORD:

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

For NOTIFY_ANSWER:

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

For NOTIFY_START request you can easily change the work scenario for the current call by sending in the response to the following information:

{
    "redirect": ID,
    "caller_name": NAME
}

where,

  • redirect - redirect scenario ID (in 0-1 format where 0 serves as the voice menu number and 1 is the number of the scenario) or internal PBX number, "blacklist" - in this case the call will be declined with a busy signal;
  • caller_name – name of incoming number can be set.

Maximum time of response with information about redirection and number's name is up to 2 seconds.

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