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

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:

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:

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