Data API

Conventions

The following conventions apply when using the Data API:

Empty fields are always returned with the value null. For a data array, an empty array is returned; for an object, an empty object is returned.
All date and time fields are passed in the format YYYY-MM-DD hh:mm:ss.
Requests to the API are always made via the POST method.
All parameters in requests and responses, as well as in JSON data structures and method names, use snake_case — words separated by underscores.
Data is returned in JSON only, in accordance with RFC 7159. The Accept header is ignored.
Data is UTF-8 encoded.
The Content-Type header must be application/json; charset=UTF-8.
The Content-Length header must contain the correct message length, in accordance with the HTTP/1.1 specification.

Adding IP addresses to the whitelist

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

If you want to allow access from all IP addresses, add 0.0.0.0/0 to the whitelist.

If requests are made via an agent, the agent's IP address must be added to the whitelist in the customer's account.

API users and authentication

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

Access by key

Keys are generated at the user level in the client area. Go to Administrator → User management → click the user you want to grant Data API access to and enable the Data API Basic set component. There are two types of keys:

permanent;
temporary.

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

Session-based authentication.

The session lifetime is 1 hour.

API request report

You can view reports on API requests in the client area: "Reports" → "Service reports" → "Requests to API".

Base URL for accessing the API

The base URL for accessing the API follows this template:

<protocol>://<hostname>/<version>

<protocol> — https;
<hostname> — dataapi.callgear.com;
<version> — API version (refer to "Versioning").

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

Versioning

The current Data API version is 2.0.

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

When a new version is released, the previous one is considered deprecated. When you call a deprecated version, the meta parameters (refer to "Meta parameters") include the current_version_deprecated parameter set to true.

The maximum number of supported versions is 2. The support period for old versions is 2 months.

Limits and restrictions

Points are deducted only for successful requests — that is, the ones marked as successful in the API request report (refer to "API request report").

Information about limits is returned in all responses in the meta parameters (refer to "Meta parameters"), except when limits are not applied.

Limits are based on a points system: each method has a weight. Calling a method reduces the available daily/per-minute points by that method's weight.

Information about limits in the meta parameters:

Parameter name	Description
`day_limit`	Current limit in points per day
`day_remaining`	Points remaining until the daily limit is reached
`day_reset`	Seconds left until the daily limit is reset
`minute_limit`	Current limit in points per minute
`minute_remaining`	Points left until the per-minute limit is reached
`minute_reset`	Seconds left until the per-minute limit 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".

Error handling

Error message parameters

Name	Type	Required	Description
`error`	object	yes	Object containing the error
`code`	number	yes	A non-unique error code (refer to "Error code groups")
`message`	string	yes	Error message
`data`	object	yes	Object containing the details of the error
`mnemonic`	string	yes	Unique text code of the error. It is recommended to use this parameter when handling errors.
`value`	string	no	Contains the value passed by the user, unchanged. In certain cases it is absent — for example, when a required parameter was not filled in.
`extended_helper`	string	no	Link to an extended description of the error and possible ways to solve it.
`params`	object	no	Map of parameter substitutions for error message templates — that is, it contains dynamically varying values, such as limits. Values stated in this parameter can be used in error messages in a Data API based interface.
`field`	string	no	Name of the parameter associated with the error. Nested parameters are separated with "." 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": {}
        }
    }
}

Error code groups

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

List of errors common to all methods

Error text	Code	Mnemonic	Description
Invalid Request The JSON sent is not a valid Request object	-32600	`invalid_request`	Errors associated with validation of the request parameters `id` and `jsonrpc`
Access token has been expired	-32001	`access_token_expired`	Applies only to permanent tokens. Returned when the token's lifetime has expired
Access token has been blocked	-32001	`access_token_blocked`	Returned if a permanent token is blocked
Access token is invalid	-32001	`access_token_invalid`	Returned 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`	The limit has been exceeded
You need at least one of the following components to access this method: {components}	-32008	`method_component_disabled`	Returned if a component required for the method to work is not enabled
You need at least one of the following components to access this parameter: {components}	-32008	`parameter_component_disabled`	Returned if a component required to fill in a parameter or create an entity is not enabled
Your IP {ip} is not whitelisted	-32003	`ip_not_whitelisted`	The IP address used to make the request is not on the whitelist. If the request is made via an agent, the agent's IP address must be on the whitelist in the 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`	The account is blocked
Internal error, contact the support service	-32603	`internal_error`	Internal error — contact technical support
Data supplied is of wrong type	-32602	`data_type_error`	For example, a string was expected but an int was passed
The method does not exist / is not available	-32601	`method_not_found`	The method was not found
Permission denied	-32003	`forbidden`	No rights to access the method or the API, or permission to perform the action was denied
Invalid JSON was received by the server.	-32700	`parse_error`	JSON validation error
Batch operations not supported	-32099	`batch_operations_not_supported`	Batch operations are not supported
Notifications not supported	-32099	`notifications_not_supported`	The `id` parameter is missing from the request. Refer to "Fields common to all methods"
The required parameter has been missed	-32602	`required_parameter_missed`	A required parameter is missing
Invalid parameter value	-32602	`invalid_parameter_value`	Always returned when an invalid parameter value is passed, or when the value does not comply with the required format
Unexpected method parameter(s)	-32602	`unexpected_parameters`	Returned when `params` contains parameters not provided in the method's JSON structure, or when a filtering, sorting, or selection parameter does not exist
The combination of parameters is not permitted	-32602	`invalid_parameters_combination`	Returned when a combination of parameters in a method is invalid, or when the parameters depend on each other. It is advised to consult the documentation on the method and its parameters.
{error_message}	-32602	`error`	Dynamic errors

List of errors for methods with the get method

Error text	Code	Mnemonic	Description
Invalid parameter value	-32602	`invalid_parameter_value`	Returned when a filter contains an invalid value for `regexp`, `jsquery`, or any other value that does not comply with the documentation
Sort by parameter is prohibited	-32602	`sort_prohibited`	Sorting by the parameter is prohibited or impossible, because the sorting parameter is not among the ones allowed for sorting
Filter by parameter is prohibited	-32602	`filter_prohibited`	Filtering by the parameter is prohibited or impossible, because the filtering parameter is not among the ones allowed for filtering
Max value of requested date interval is 3 months	-32602	`date_interval_limit_reached`	Returned if the time period between `date_from` and `date_till` in a request exceeds 3 months. Usually returned only by report methods, and not by all of them.

List of errors common to methods with the delete method

Error text	Code	Mnemonic	Description
Entity not found	-32602	`entity_not_found`	Returned when the specified entity ID is not found
You have interdependent entities	-32602	`dependency_error`	The entity to be deleted is used by other entities. To delete it, you first need to remove it from all fields where it is used
Permission denied	-32602	`forbidden`	You cannot delete the entity, as it belongs to the system — such as "Blacklist" in the address book

List of errors common to the create, update, set, and unset methods

Error text	Code	Mnemonic	Description
Entity not found	-32602	`entity_not_found`	Returned when the specified entity ID is not found
Duplicate entity	-32602	`duplicate_entity`	Returned if the entity already exists
Campaign is inactive	-32602	`campaign_is_inactive`	The advertising campaign is inactive
Invalid date time	-32602	`invalid_date_time`	Invalid date or time — refer to the method's description
A new data limit has been exceeded	-32602	`data_limit_exceeded`	Returned if you exceed the data limit.
Action is not allowed for your tariff plan. You need to contact the 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 by another entity. For example, the virtual number is already used in another advertising campaign.

Batch operations

This functionality is not supported.

Method naming principles

The name of a JSON-RPC method consists of two parts separated by a dot: a verb and an object name.

The object name is a plural noun expressing a business entity, such as subscribers.

The method name begins with a verb expressing an operation.

Verbs used in method names

Verb	Description
`create`	Creates an entity
`get`	Returns a list of sorted and filtered data, using filtering criteria and sorting methods. When making a request, you can set a limit or paging for the amount of data you receive (refer to "Paging"). By applying filtering criteria you can also get a single entry you need, using its unique ID (refer to "Filters"). The total number of entries is returned in a special meta parameter (refer to "Meta parameters"). A special parameter lets you specify which fields should be returned in the response (refer to "Viewing returned data").
`update`	Updates an entity with the given ID. Partial parameter updates are possible. When you update an array, it is replaced as a whole — all elements that were not passed are deleted. To reset an optional parameter, pass `null`.
`delete`	Deletes an entity with the given ID.
`add`	Connects an object with another one.
`enable`	Enables an object
`disable`	Disables an object
`set`	Sets an aspect on another object, such as tagging an inquiry
`unset`	Removes an aspect from another object, such as removing a tag from an inquiry

Filters

You can only filter data for the get methods (refer to "Verbs used in method names"). To do so, use the optional primitive filter, which may be an object containing:

a simple filter;
a filter tree with simple filters and conditions.

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

field — field of the entity to be filtered (the list of such fields is predetermined for each method);
operator — filtering operator. The list of all operators is in the section "Filter operators";
value — value for the filter operator. Optional field. If absent, it is considered empty.

A filter tree contains a special primitive filters that may contain both simple filters and nested filter trees.

Possible errors when filtering

Error text	Code	Mnemonic	Description
Filter by parameter is prohibited	-32602	`filter_prohibited`	Filtering by the 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 was passed, or the parameter does not exist

Example of a simple filter's JSON structure

Getting a list of entries whose name field is "Bob"

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

Example of a filter tree with one nesting level

Getting a list of entries whose name field is "Bob" and whose age is 25

{
    "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 filter tree with two nesting levels

Getting a list of entries whose name is "Bob" and age is 25, or whose name is "Dexter" and age is 2

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

To filter by null / not null, use =null / !=null.

Operator	Description	Case sensitivity (strings)	Data type
`=`	Equal	yes	number, string, null, boolean, iso8601, enum
`!=`	Not equal	yes	number, string, null, boolean, iso8601, enum
`<`	Less than	—	number, iso8601
`>`	Greater than	—	number, iso8601
`<=`	Less than or equal	—	number, iso8601
`>=`	Greater 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`	Matches any value in the array (OR logic)	yes	number, string, enum

Data sorting

You can only sort data for the get methods (refer to "Verbs used in method names"). To do so, use an array of sorting objects with the following primitives:

field — field used for sorting;
order — sorting order. Possible values are asc/desc: asc — ascending, desc — descending. An optional parameter. The default value is asc.

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

Possible errors when sorting

Error text	Code	Mnemonic	Description
Sort by parameter is prohibited	-32602	`sort_prohibited`	Sorting by the 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 was passed, or the parameter does not exist

JSON structure:

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

Paging

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

Parameter	Default value	Maximum value	Description
`offset`	0	100 000	Offset defining the record number from which to return `limit` records
`limit`	1000	10 000	Number of records returned

JSON structure:

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

Meta parameters

Returned when using the get method (refer to "Verbs used in method names").

Returned in both successful and error responses.

The api_version parameter is returned only for deprecated versions.

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 returned data

Selecting the returned columns

For methods with the data-returning verb get (refer to "Verbs used in method names"), you can specify the optional primitive fields — an array containing the list of fields to include in the output. If fields is not used, all the method's default fields are returned.

Each method has its own list of fields.

JSON structure:

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

Possible errors when selecting returned data

Error text	Code	Mnemonic	Description
Unexpected method parameter(s)	-32602	`unexpected_parameters`	A wrong parameter was passed, or the parameter does not exist

Fields common to all methods

Name	Type	Required	Valid value	Description
`id`	string or number	yes		Unique ID of the API request, used to match the request with its response. It is recommended to use a unique hash or a random number.
`method`	string	yes		The called method
`jsonrpc`	string	yes	2.0	JSON-RPC specification number
`params`	object	yes		Contains the body of the API request. The request body varies depending on the method.

Authentication

Full documentation for both methods below is provided in the "Authentication Methods" section of this document.

Method	Description
"login.user"	Logging in and receiving an authentication session key
"logout.user"	Logging out and deleting the authentication session key

Data API

Conventions

Adding IP addresses to the whitelist

API users and authentication

Access by key

Access by login and password

API request report

Base URL for accessing the API

Versioning

Limits and restrictions

Methods and their weight in points

Expanding limits

Error handling

Error message parameters

JSON error structure

Error code groups

List of errors common to all methods

List of errors for methods with the get method

List of errors common to methods with the delete method

List of errors common to the create, update, set, and unset methods

Batch operations

Method naming principles

Verbs used in method names

Filters

Possible errors when filtering

Example of a simple filter's JSON structure

Example of a filter tree with one nesting level

Example of a filter tree with two nesting levels

Example of a filter tree with three nesting levels

Filter operators

Data sorting

Possible errors when sorting

Paging

Meta parameters

Viewing returned data

Selecting the returned columns

Possible errors when selecting returned data

Fields common to all methods

Authentication