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.

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> - dataapi.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:

Simple filter;
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

Method	Description
"login.user"	Login and receiving authentication session key.
"logout.user"	Logout and deleting an authentication session key.

Data API

Agreements

Adding IP-addresses to the whitelist

API users and authentication

Access by key

Access by login and password

Requests to API report

Base URL to access API

Versioning

Limits and restrictions

Methods and their weight in points

Expanding limits

Processing errors

Parameters of a message about error

JSON error structure

Errors codes groups

List of errors common for all methods

List of errors for methods with the verb get

List of errors common for methods with the verb delete

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

Batch operations

Principle of methods naming

Verbs used in methods' names

Filters

Possible errors when filtering

Example of a simple filter's JSON structure

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

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

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

Filter operators

Data sorting

Possible errors when sorting

Paging

Meta parameters

Viewing returning data

A separate list of the returning columns

Possible errors in displaying the returning data

Common fields for all methods

Authentication