Skip to content

Data API

Agreements

The following agreements are accepted when using Data API:

  • Empty fields always returns with the value null. In case of a data bulk the an empty bulk returns. In case of an object, an empty object returns;
  • All the fields related to time and date are transferred in the format YYYY-MM-DD hh:mm:ss;
  • Requests to API are always made via the POST method;
  • All the parameters in requests/replies, as well as in JSON data structures and methods titles are named in the Snake Case style - words are divided by underscores;
  • Data returns only in the JSON format ass according to the specification RFC 7159. The title Accept should be ignored;
  • Data coding UTF-8;
  • Title Content-Type should be "application/json; charset=UTF-8";
  • Title Content-Length should have correct message length, in line with the specification HTTP/1.1

Adding IP-addresses to the whitelist

By default, access to API is denied for anyone. To make a request you need to add to the whitelist an IP-address used for the request. You can do this in your client area "Administrator -> Account -> Rules and security settings" tab "API".

If you need for all the IP-addresses to have access, add 0.0.0.0/0 to the whitelist.

If the request is made via agent, his or hers IP address should be added to the whitelist in a customer account.

API users and authentication

Access rules similar to the ones in the client area applies to users and access keys.

Access by key

Keys are generated on a user level in the client area "Account" → "Managing Users"
There are two types of keys:

  • permanent;
  • temporary;

Permanent keys have unlimited lifetime.
Temporary keys have specified expiration time.

Access by login and password

Authentication using sessions

Session lifetime is 1 hour.

Requests to API report

You can make reports about requests to API in the client area "Reports"->"Service reports"->"Requests to API"

Base URL to access API

Base URL to access API complies with the following template:

<protocol> :// <hostname> / <version>
  • <protocol> - https;
  • <hostname> - api.callgear.com;
  • <version> - API version (refer to Versioning)

https://dataapi.callgear.com/<version>

Versioning

Current version of Data API 2.0

Data API supports versioning. Version is specified in a base URL as vX.Y, where X - is a major version number, and Y is a minor version number

If a new version is released the previous one is considered outdated. Consequently, when referring to an old version of API in the meta parameters (refer to Meta-parameters) the parameter "current_version_deprecated" with value "true" will return.

Maximum number of supported versions is 2
Support period for old versions is 2 months

Limits and restrictions

Points are only written off after successful requests, i.e. the ones that are marked as successful in the requests to API report (refer to Report about requests to API).

Information about limits returns in all replies in the meta parameters (refer to Meta-Parameters) except when the limits are not applied;

Limits are based on points system, i.e. each method has its weight. Calling a method reduces available points per day/per minute by the weight of a called method.

Information about limits in the meta parameters:

Parameter title Description
day_limit Current limit points per day
day_remaining Points remaining until daily limit
day_reset Seconds left till the daily limit is reset
minute_limit Current limit points per minute
minute_remaining Points left till the limit per minute is reached
minute_reset Seconds left till the limit per minute is reset

Methods and their weight in points

Operation type Weight in points
All operations 1

Expanding limits

You can expand the limits in your client area "Account" -> "Rates and options".

Processing errors

Parameters of a message about error

Title Type Required Description
error object yes Object containing error
code number yes A non-unique error code (refer to Groups of errors codes )
message string yes Message about error
data object yes Object containing details of an error
mnemonic string yes Unique text code of an error. It is recommended to use this parameter when processing errors.
value string no Contains information transferred from a user without any changes
In certain cases it's absent. For example, a required parameter might not be filled in.
extended_helper string no Link to an extended description of an error and possible way to solve it.
params object no Map of the parameters' substitutes for templates with texts about errors. I.e. it contains dynamically varying values, such as limits. Values stated in this parameter can be used in messages about errors in a Data API based interface.
field string no Title of a parameter, associated with an error
Embedded parameters are displayed with dividing symbols "."
For example: "employee.phone_number"

JSON error structure

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": "number",
    "message": "string",
    "data": {
      "mnemonic": "string",
      "field": "string",
      "value": "string",
      "params": {
        "object": "string"
      },
      "extended_helper": "string",
      "metadata": {

      }
    }
  }
}

Errors codes groups

Error code Description
-32700 Errors associated with JSON validation
-32600 Errors associated with validation of request parameters id and jsonrpc
-32601 Errors associated with method
-32602 Errors associated with validation of parameters in a called method
-32603 Internal errors of a JSON RPC server
-32001 Authentication errors and errors associated with keys
-32003 Errors associated with access rights - ip address is not on the whitelist, user doesn't have access
-32004 Errors associated with the wrong order of called methods
-32007 Errors associated with virtual number
-32008 Errors associated with a component
-32009 Errors associated with account
-32029 Errors associated with limits
-32099 Errors associated with the support of various JSON RPC 2.0 specifications - Batch operations, Notifications

List of errors common for all methods

Text message Code Mnemonics Description
Invalid Request The JSON sent is not a valid Request object -32600 invalid_request Errors associated with validation of request parameters id and jsonrpc
Access token has been expired -32001 access_token_expired Is only applied to a permanent token. If lifetime of a permanent token is up, this error returns
Access token has been blocked -32001 access_token_blocked If a permanent token is blocked, this error returns
Access token is invalid -32001 access_token_invalid This error returns if a permanent/temporary token is not found
Limit per {limit_type} has been exceeded. Value of current limit per {limit_type} is {limit_max_value} -32029 limit_exceeded Limit is exceeded
You need at least one of the following components to access this method: {components} -32008 method_component_disabled If a component, required for a method to work, is not switched on
You need at least on of the following components to access this parameter: {components} -32008 parameter_component_disabled If a component, required to fill in a parameter or to create an entity, is not switched on
Your IP {ip} is not whitelisted -32003 ip_not_whitelisted IP address, used to make a request, is not on the whitelist. If a request is made from an agent, your IP address should be in the whitelist in a client's account
Login or password is wrong -32001 auth_error Wrong login or password
Your account has been disabled, contact the support service -32009 account_inactive Account is blocked
Internal error, contact the support service -32603 internal_error Internal error, enquire with technical support
Data supplied is of wrong type -32602 data_type_error For example, if string is expected and int was
The method does not exist / is not available -32601 method_not_found Method not found
Permission denied -32003 forbidden No rights to access method or API, or denied permission to perform an activity
Invalid JSON was received by the server. -32700 parse_error JSON validation error
Batch operations not supported -32099 batch_opreations_not_supported Batch operations are not supported
Notifications not supported -32099 notifications_not_supported The parameter id is lost in request. refer to Parameters common for all methods"
The required parameter has been missed -32602 required_parameter_missed A required parameter is missed
Invalid parameter value -32602 invalid_parameter_value Always returns when an invalid parameter's value is transferred, or when the value does not comply with the required spelling standard
Unexpected method parameter(s) -32602 unexpected_parameters Used when the "params" has parameters not provided in JSON method structure , or when a filtering, sorting, selection parameter doesn't exist
The combination of parameters is not permitted -32602 invalid_parameters_combination Used when combination of parameters in a method is invalid, or when those parameters depend on each other. It is advised to consult documentation on the method and its parameters.
{error_message} -32602 error Dynamic errors

List of errors for methods with the verb get

Error text Code Mnemonics Description
Invalid parameter value -32602 invalid_parameter_value When the filters contain invalid value for regexp, jsquery or any other values that do not comply with the documentation
Sort by parameter is prohibited -32602 sort_prohibited Sorting by a parameter is prohibited or impossible, because a sorting parameter is not among the ones allowed for sorting
Filter by parameter is prohibited -32602 filter_prohibited Filtering by a parameter is prohibited or impossible, because a filtering parameter is not among the ones allowed for filtering
Max value of requested date interval is 3 months -32602 date_interval_limit_reached If the time period between date_from and date_till in a request exceeds 3 months. Usually this error only returns in the methods you use to get reports, but not in all of them.

List of errors common for methods with the verb delete

Error text Code Mnemonics Description
Entity not found -32602 entity_not_found If you receive an ID of an entity that's not found
You have interdependent entities -32602 dependency_error An entity to delete is used in another entities. To delete it, you need to exclude the entity, that's to be deleted, from all other fields it is used in
Permission denied -32602 forbidden You can not delete an entity as it belongs to the system, such as "Blacklist" in the address book

List or errors common for methods withe the verbs create and update, set, unset

Error text Code Mnemonics Description
Entity not found -32602 entity_not_found If you receive an ID of an entity that's not found
Duplicate entity -32602 duplicate_entity If an entity already excists
Campaign is inactive -32602 campaign_is_inactive Advertising campaign is inactive
Invalid date time -32602 invalid_date_time Invalid date or time, refer to a method's description
A new data limit has been exceeded -32602 data_limit_exceeded Error returns if you exceed the data limit.
Action is not allowed for your tariff plan. You need contact support service or change your tariff plan settings in your account -32602 tariff_restrictions Any service plan limits
This value is already used by another entity -32602 already_in_use The parameter's value is already in use in another entity. For example, a virtual number is already used in another advertising campaign.

Batch operations

Functionality is not supported

Principle of methods naming

Name of a JSON-RPC method consists of two parts divided by a dot: a verb and an object's name.

An object's name is chosen as a noun in the plural, that expresses a business entity such as subscribers.

A method's name should begin with a verb, expressing an operation.

Verbs used in methods' names

Verb Description
create Creates an entity
get Returns a list of sorted and filtered data by using filtering criteria and sorting methods. When making a request you can set a limit or paging for the amount of the data you receive (refer to Paging). By applying filtering criteria you can also get the one entry you need. Use its unique ID (refer to Filters). General number of entries returns in a special meta parameter (refer to Meta parameters). By using a special parameter you van point on the fields that should be returned in a reply message (refer to Viewing returned data).
update Updates an entity with a certain ID.
Partial parameters update is possible
When you update a bulk of data, it is updated in a whole, i.e. all the elements, that were not transferred, are deleted.
To reset an additional parameter you need to transfer null
delete Deletes an entity with a certain ID.
add Connects an object with another one.
enable Enables an object
disable Disables an object
set Sets an aspect for another object, such as tagging an inquiry
unset Unsets an aspect for another object, such as deleting a tag of an inquiry

Filters

You can only filter data applicable to the verb "get" (refer to "Verbs used in methods' names". To do so you can use the unrequired primitive "filter", which may be an object containing:

  1. Simple filter;
  2. Filters tree with simple filters and conditions.

A simple filter is an object that contains the following required primitives:

  • field - field of an entity that's to be filtered (the list of such entities is pre determined for each method);
  • operator - filtering operator. You can access the list of all the operators in the section "Filter operators";
  • value - value for filter operator. Unrequired field. If it's absent, it shall be considered empty.

Filters tree contains a special primitive "filters", that may contain both simple filters and a filters tree.

Possible errors when filtering

Text Code Mnemonics Description
Filter by parameter is prohibited -32602 filter_prohibited Filtering by parameter is prohibited or impossible, as the filtering parameter is not on the filtering whitelist
Unexpected method parameter(s) -32602 unexpected_parameters A wrong parameter is transferred or the parameter doesn't exist

Example of a simple filter's JSON structure

Receiving a list of entries that have "Bob" in the field "name"

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"get.entity",
  "params":{
    "filter":{
      "field":"name",
      "operator":"=",
      "value":"Bob"
    }
  }
}

Example of a JSON structure of a filter tree with one nesting level

Receiving a list of entries that have "Bob" in the field "name" and the age - 25 years

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"get.entity",
  "params":{
    "filter":{
      "filters":[
        {
          "field":"name",
          "operator":"=",
          "value":"Bob"
        },
        {
          "field":"age",
          "operator":"=",
          "value":25
        }
      ],
      "condition":"and"
    }
  }
}

Example of a JSON structure of a filter tree with two nesting levels

Receiving a list of entries that have "Bob" in the field "name" and the age - 25 years, or a list of entries that have "Dexter" in the field "name" and the age - 2 years

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"get.entity",
  "params":{
    "filter":{
      "filters":[
        {
          "filters":[
            {
              "field":"name",
              "operator":"=",
              "value":"Bob"
            },
            {
              "field":"age",
              "operator":"=",
              "value":25
            }
          ],
          "condition":"and"
        },
        {
          "filters":[
            {
              "field":"name",
              "operator":"=",
              "value":"Dexter"
            },
            {
              "field":"age",
              "operator":"=",
              "value":2
            }
          ],
          "condition":"and"
        }
      ],
      "condition":"or"
    }
  }
}

Example of a JSON structure of a filter tree with three nesting levels

Request condition ((addv_comp_id = 10 or addv_comp_id = 12) and (tag_id = 1 or tag_id = 5)) or visitor_id = 14 or (date_from = 2015-12-14 and date_till = 2015-12-16)

{
  "filter":{
    "filters":[
      {
        "filters":[
          {
            "filters":[
              {
                "field":"addv_comp_id",
                "operator":"=",
                "value":10
              },
              {
                "field":"addv_comp_id",
                "operator":"=",
                "value":12
              }
            ],
            "condition":"or"
          },
          {
            "filters":[
              {
                "field":"tag_id",
                "operator":"=",
                "value":1
              },
              {
                "field":"tag_id",
                "operator":"=",
                "value":5
              }
            ],
            "condition":"or"
          }
        ],
        "condition":"and"
      },
      {
        "field":"visitor_id",
        "value":14,
        "operator":"="
      },
      {
        "filters":[
          {
            "field":"date_from",
            "value":"2015-12-14 12:00:00",
            "operator":"="
          },
          {
            "field":"date_till",
            "value":"2015-12-16 15:00:00",
            "operator":"="
          }
        ],
        "condition":"and"
      }
    ],
    "condition":"or"
  }
}

Filter operators

Filters null or not null is =null, !=null

Operator Description Case sensitivity of lines Data type
= Equal yes number, string, null, boolean, iso8601, enum
!= Not equal yes number, string, null, boolean, iso8601, enum
< Less than - number, iso8601
> More than - number, iso8601
<= Less than or equal - number, iso8601
>= More than or equal - number, iso8601
like Begins with, Ends with, Contains
Use "%"
yes string
regexp Posix yes string
jsquery PostgreSQL jsquery yes object, array
in Data bulk relating to "or" yes number, string, enum

Data sorting

You can only sort data applicable to the verb "get" (refer to "Verbs used in methods' names"). To do so you need to use a v bulk of sorting objects with the following primitives:

  • field - field used for sorting;
  • order - sorting order. Possible values are "asc"/"desc". "asc" - in ascending order, "desc" - in descending order. An unrequired parameter. Default value is "asc".

List of fields that can be used for sorting is defined for each method separately.

Possible errors when sorting

Error text Code Mnemonics Description
Sort by parameter is prohibited -32602 sort_prohibited Sorting by parameter is prohibited or impossible, as the sorting parameter is not on the sorting whitelist
Unexpected method parameter(s) -32602 unexpected_parameters A wrong parameter is transferred or the parameter doesn't exist

JSON structure:

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"string",
  "params":{
    "sort":[
      {
        "field":"string",
        "order":"string"
      }
    ]
  }
}

Paging

Paging can only be applied to the verb "get" (refer to "Verbs used in methods' names"). When paging data, you can use the following parameters:

Parameter Default value Possible value description
offset 0 100 000 Offset that defines from which entry number to return the entries' "limit"
limit 1000 10 000 Returning data size (number of entries)

JSON structure:

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"string",
  "params":{
    "offset":"number",
    "limit":"number"
  }
}

Meta parameters

Return when using the verb "get" (refer to "Verbs used in methods' names").

Appear both in a wrong and a right replies

Parameter "api_version" returns only in versions that are deprecated.

JSON structure:

{
  "metadata":{
    "api_version":{
      "current_version_deprecated":"boolean",
      "current_version":"string",
      "latest_version":"string"
    },
    "limits":{
      "day_limit":"number",
      "day_remaining":"number",
      "day_reset":"number",
      "minute_limit":"number",
      "minute_remaining":"number",
      "minute_reset":"number"
    },
    "total_items":"number"
  }
}

Viewing returning data

A separate list of the returning columns

A special unrequired primitive "fields" of a bulk type, containing a list of fields to be used in the output, may be stated in the data returning verb "get" (refer to "Verbs used in methods' names"). If the primitive "fields" is not in use, all the method's default fields are displayed in the output.

Each method has its own list of fields.

JSON structure:

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"string",
  "params":{
    "fields":[
      "string"
    ]
  }
}

Possible errors in displaying the returning data

Text Code Mnemonics Description
Unexpected method parameter(s) -32602 unexpected_parameters A wrong parameter is transferred or the parameter doesn't exist

Common fields for all methods

Title Type Required Valid value Description
id string or number yes Unique request to API ID, which is used to connect a request with the reply. It is recommended to use unique hash or an accidental number.
method string yes Called method
jsonrpc string yes 2.0 JSON-RPC specification number
params object yes Contains request to API body. Depending on the method the request's body changes.

Authentication

Login

Method login.user
Description Login and receiving authentication session key
Who has access Partner, Customer

Parameters of a request

Title Type Required Valid value Description
login string yes User login
password string yes User password

Parameters of a reply

Title Type Required Description
access_token string yes Authentication session key
expire_at number yes Timestamp when a given token is not valid anymore
app_id number yes Customer unique ID

Lifespan of an authentication session key after calling the method "login.user" is 1 hour. After that you need to request an authentication session key again, i.e. call the method "login.user".

To make a request to API, you can use a permanent authentication key that you can access in your client area at a user's level.

JSON request structure

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"login.user",
  "params":{
    "login":"string",
    "password":"string"
  }
}

JSON reply structure

{
  "jsonrpc":"2.0",
  "id":"number",
  "result":{
    "data":{
      "access_token":"string",
      "expire":"number",
      "app_id":"number"
    }
  }
}

Logout

Method logout.user
Description Logout and deleting an authentication session key
Who has access Partner, Customer

Method parameters

Name Type Required Description
access_token string yes Authentication session key

JSON request structure

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"logout.user",
  "params":{
    "access_token":"string"
  }
}

JSON reply structure

{
  "jsonrpc":"2.0",
  "id":"number",
  "result":{
    "data":{
    }
  }
}