Skip to content

Roistat REST API

Overview

What Is an API?

An application programming interface, or API, is a tool that assists users to manage some software (application, service, program etc.) by carrying out specific commands.

What Is the Scope of the Roistat API?

Roistat uses the API to accomplish a variety of business objectives. This documentation provides a set of API methods that you may employ to reach your own business goals. For example, you can update leads information or you can extract lists of calls from Calltracking and use them to accomplish your business objectives. Our clients utilize the API mostly to flexibly integrate Roistat with other systems.

Roistat API Features

Data Protocol

Our API supports both HTTP and HTTPS protocols.

Request Format

The API supports Cross-origin resource sharing (CORS).

POST request are used by default in the Roistat API. However, one may employ GET requests for the methods ending in /list.

Authorization

All API methods may be used only after authorization. Your API key and project number are required.

Project number can be passed in the request URL, for example: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?project=12345

API key can be passed in two ways:

  • By setting the Api-key HTTP header (recommended way):

    Api-key: 1234567890qwerty
    
  • By adding the key parameter to the request URL (unsafe way):

    https://cloud.roistat.com/api/v1/project/calltracking/phone/list?key=1234567890qwerty&project=12345
    

Where Can I Find My API Key?

A unique API key is generated for each user. It relates to all projects within one user's profile.

You can find your API key in the profile settings.

Request Structure

Both JSON and XML formats can be used to send data.

For further details see Requests.

Response Format

The default response format is JSON. If the format is XML, the response will be in XML.

You can forcibly set up the format by using the HTTP header Accept with one of the following values: application/json or application/xml.

Форматом ответа по умолчанию является JSON. Если передавать данные в формате XML, ответ будет представлен в виде XML.

Вы можете принудительно выставить формат, используя HTTP-заголовок Accept с одним из значений: application/json или application/xml.

For further details see Responses.

Requests

Request Format

The API supports Cross-origin resource sharing (CORS).

POST request are used by default in the Roistat API. However, one may employ GET requests for the methods ending in /list.

URL Structure

The URL of a request starts with the API address (https://cloud.roistat.com/api/v1/), then the name of a resource or operation goes, following with the name of a method, and project ID. You can also pass an API key in the URL, but we recommend that you pass it in the HTTP header.

E.g., the URL for the request to obtain the list of phone numbers from Calltracking: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?project=12345

API address https://cloud.roistat.com/api/v1
Context project
Service name calltracking
Resource name phone
Method list
Project number project=12345

If you need to pass an API key in the URL, the link will look like this: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?key=1234567890qwerty&project=12345

Authorization

All API methods may be used only after authorization. Your API key and project number are required. The exceptions are methods /user/projects and /account/project/create, where only an API key is required.

Project number can be passed in the request URL, for example: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?project=12345

API key can be passed in two ways:

  • By setting the Api-key HTTP header (recommended way):

    Api-key: 1234567890qwerty
    
  • By adding the key parameter to the request URL (unsafe way):

    https://cloud.roistat.com/api/v1/project/calltracking/phone/list?key=1234567890qwerty&project=12345
    

Where Can I Find My API Key?

A unique API key is generated for each user. It relates to all projects within one user's profile.

You can find your API key in the profile settings.

Request structure

Both JSON and XML formats can be used to send data.

Timezone (timezone)

All API methods use the UTC+0 timezone by default.

Example:

2017-01-01 12:00:00 will be interpreted as 2017-01-01 12:00:00+00:00
2017-01-01 12:00:00+0300 will be interpreted as 2017-01-01 09:00:00+00:00

Data filtering (filters)

Include the filters parameter in the request body in order to filter the output data.

If you wish to filter by only one field:

{
    "filters": [
        ["id", ">=", "15774"]
    ]
}

The elements of the filters array:

  1. Field to be filtered by;
  2. Operator;
  3. Name of the field.

The 2nd element (operator) may be as follows:

Operator Description
<, <=, =, !=, >, >= Comparison operators
in The value of a parameter will be assessed whether it can be included in the array of parameters
null If you put 0, comparison operation will be IS NOT NULL. If you put 1, it will be IS NULL.
like Matching operation. Equivalent to %LIKE%

Below is an example of using the in operator (you will see only phone calls with the ANSWER or CANCELLED statuses in the response):

{
    "filters": [
        ["status", "in", ["ANSWER", "CANCELLED"]]
    ]
}

Several filters may be applied. In this case, the and (logical AND) or or (logical OR) operator will be used. Below is an example of the filter that selects records that fall with a date range between May 22 and May 23 (in UTC0):

{
    "filters": {
        "and": [
            ["date", ">", "2016-05-21T21:00:00+0000"],
            ["date", "<", "2016-05-22T21:00:00+0000"]
        ]
    }
}

And here is an example of the filter that selects records that fall with a date range between May 22 and May 23 or after May 31:

{
    "filters": {
        "or": [{
                "and": [
                    ["date", ">", "2016-05-21T21:00:00+0000"],
                    ["date", "<", "2016-05-22T21:00:00+0000"]
                ]
            },
            ["date", ">", "2016-05-30T21:00:00+0000"]
        ]
    }
}

Sorting (sort)

The fields of the resource requested can be sorted.

E.g., there is some resource for an order:

{
    "id": "12345",
    "url": "https:\/\/site.com\/crm\/account.php?account_id=12345",
    "source_type": "standard",
    "creation_date": "2016-06-19T07:33:46+0000",
    "update_date": "2016-06-19T09:00:27+0000",
    "revenue": 0,
    "cost": 0,
    "client_id": "12345",
    "visit_id": "67890",
    "custom_fields": {
        "name": "John Doe",
        "email": "email@mail.ru",
        "Zone": "Russia",
        "Tariff": "Trial",
        "Language": "English",
        "roistat": 67890,
        "status_name": "Existing"
    },
    "status": {
        "id": "0",
        "type": "progress",
        "name": "Existing"
    }
}

To sort the orders by the update date (recently updated orders on the top), add the sort array to the request body where:

  • 1st key: the field for sorting;
  • 2nd key: the type of sorting:
    • asc – in ascending order (the 1st element is the smallest or the earliest);
    • desc – in descending order (the 1st element is the largest or latest).
{
    "sort": ["creation_date","desc"]
}

Limiting the amount of data (limit and offset)

Employ commonly used parameters limit and offset to limit output data.

Below is an example how to obtain only the first 100 records:

{
    "limit": 100,
    "offset": 0
}

To get the next 100 records, the request body should be as follows:

{
    "limit": 100,
    "offset": 100
}

Requesting extra data (extend)

Objects can be linked together. E.g., the object order may have a dependent visit object, i.e. you can query visit data within the request for order data.

You may use the extend parameter that will contain the list of dependent objects, instead of sending two different requests for objects that are connected.

Below is an example how you can use the extend parameter for the /integration/order/list method in order to obtain information about visits, besides orders:

{
    "extend": ["visit"]
}

Combining various parameters

You can use several parameters to manage output data. All parameters should be included in one JSON object, separated by commas.

E.g.:

{
"extend": ["visit"],
"sort": ["creation_date","desc"],
"limit": 100,
"offset": 0,
"filters": {
        "and": [
            ["date", ">", "2016-05-21T21:00:00+0000"],
            ["date", "<", "2016-05-22T21:00:00+0000"]
        ]
    }
}

Request Limitations

There are some limitations that apply to all API methods and work within each project. They are as follows:

  • 10 requests per 1 second;
  • 5000 requests per 1 hour.

There are no general limitations other than those listed above. However, some methods have other limitations listed in the method's description.

Responses

JSON Specification

The Roistat API uses standard JSON format. Learn more about JSON specification here: http://www.json.org/.

XML specification

All requests and responses in XML format use a single specification.

  • The root elemts is always <data></data>.
  • To describe a property with the name 'propertyName' and the value of 'propertyValue', you need to wrap the 'propertyValue' in the 'propertyName' tag.

    Example:

    <!--?xml version='1.0' encoding='UTF-8'?-->
    <data>
      <id>123</id>
      <name>Eric</name>
      <email>eric@gmail.com</email>
    </data>
    
  • To pass lists (arrays without text keys, for example: [3, 7, 4]) you need to wrap each value in the <item> </item> tag.

    To send several groups of properties (for example, to create or modify several objects in one request), you need to wrap each group in a <item> </item> tag.

    In the example below, the <item> </item> tag is used to send information about two different people in the same request. Everyone has their own list of phone numbers.

     <!--?xml version='1.0' encoding='UTF-8'?-->
    <data>
    <item>
      <name>Eric</name>
      <phones>
          <item>8-999-123-45-67</item>
          <item>8-999-987-65-43</item>
      </phones>
    </item>
    <item>
      <name>Lisa</name>
      <phones>
          <item>8-999-999-99-99</item>
      </phones>
    </item>
    </data>
    

Response structure

Responses contain 3 parameters as follows:

Parameter Value
data data you requested (for further details see the corresponding section of our API documentation)
total total number of entries (total is used when data is an array with some data)
status request status

JSON format example:

{
    "data": [{
        "id": "12345",
        "name": "John Doe",
        "static_source": {
          "system_name": "yamarket6",
          "display_name": "yamarket",
          "icon_url": "https://favicon.yandex.net/favicon/market.yandex.ru",
          "utm_source": null,
          "utm_medium": null,
          "utm_campaign": null,
          "utm_term": null,
          "utm_content": null,
          "openstat": null
      },
      "visit": null,
      "order": null
    }, {
        "id": "67890",
        "name": "Jane Doe",
        "static_source": null
    }],
    "total": 2,
    "status": "success"
}

Errors

All errors are presented both as machine- and human-readable statuses. By default, all methods return the HTTP status 200 OK, including the error cases.

You can add Use-Http-Code with the value of 1 to the request header if you wish to see real HTTP error codes.

The list of errors

Error code HTTP code Error description
incorrect_request 400 Error in the request body.
unknown_error 400 An error occurred while processing the request in Roistat. Send the request again. If the error persists, contact Roistat support.
authentication_failed 401 The request contains an invalid API key and / or project number.
authorization_failed 401 No access to third-party data services (e.g. CRM).
insufficient_funds 402 The project balance has insufficient funds.
option_not_available 402 The requested option is not available (not enabled in the project or not supported by your current rate plan / language zone).
option_not_paid 402 The requested option has not been paid for.
project_frozen 402 The project has been frozen.
access_denied 403 You have no access to data in the Roistat project. Check the settings in the "Permissions" section.
resource_not_found 404 Error in the request URL.
resource_already_exists 409 You are trying to create an entity that already exists. For example, you added a number that already exists in the project when working with Calltracking.
request_data_validation_error 422 The request contains the wrong data types. Make sure the data types (string, integer, etc.) meet the requirements of the method.
request_limit_error 429 Request limit exceeded. See the Request limitations section.
internal_error 500 An error occurred while processing the request in Roistat. Send the request again. If the error persists, contact Roistat support.