Orders¶

Get order lists from a Roistat project¶

POST /project/integration/order/list

Description

This method is used to get order lists from a Roistat project.

Add "extend": ["visit"] to the request body in order to obtain detailed information about relevant visits.

Apply the standard filters in the request body by using the filters array. You cannot filter data by visit properties, additional order fields and the "source_type" field.

You can also filter data by the deal status funnel using the "status" parameter and the following values: "0" – the In work funnel statuses, "1" – the Paid funnel statuses, "2" – the Cancelled funnel statuses.

Request limitations:

When adding "extend":["visit"]:

If the limit is more than 1000: 1 request per 1 minute.
If the limit is more than 100: 5 requests per 1 minute.
If the limit is less than 100: 10 requests per 1 minute.

Without adding "extend":["visit"]:

20 requests per 1 minute.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/integration/order/list?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}' \ 
    --data Request body - see below

Request Body:

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

Response Example

{
    "data": [
        {
            "id": "95101",
            "url": "http://roistat.com/index.php?order/info&order_id=95101",
            "source_type": "standard",
            "creation_date": "2016-06-19T00:32:12+0000",
            "update_date": "2016-06-19T02:00:07+0000",
            "revenue": 0,
            "cost": 0,
            "client_id": "78173",
            "visit_id": "4336465",
            "custom_fields": {
                "Менеджер": "John Doe",
                "roistat": 4336465,
                "status_name": "0. Created"
            },
            "status": {
                "id": "1",
                "type": "progress",
                "name": "0. Created"
            },
            "visit": null
        }
    ],
    "total": 1,
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

Parameter	Type	Required
filters	object	no
> and	array[string]	no
extend	array[string]	no
limit	integer	no
offset	integer	no

Response Parameters

Parameter	Type	Description
data	array[object]
> id	string	Deal ID in a CRM system
> url	string	Deal's URL in a CRM system
> source_type	string	Type of created lead
> creation_date	string	Date and time when the deal was created; in UTC0 format
> update_date	null or string	Date and time of the last modification of the deal; in UTC0 format
> revenue	null or integer	Revenue for the deal
> cost	null or integer	First cost
> visit_id	null or string	Client's visit ID
> custom_fields	object	Custom fields
>> Manager	null or string
>> roistat	null or integer
>> status_name	string
> status	object	Deal's status data
>> id	string	A unique status number in Roistat
>> type	string	Status type in Roistat. It can be one of the groups that you use to classify your CRM statuses: - unused - the "Not registered" group; - in progress - the "Processing" group; - paid - the "Paid" group; - canceled - the "Rejected" group.
>> name	string	A human-readable status name from the CRM system
> visit	null or object	Detailed information about relevant visit. Displayed only if the "extend": ["visit"] parameter was sent. Otherwise, you'll see `null`. Read more about visit data in the `/project/site/visit/list` method.
> client_id	null or string	Client ID
total	integer
status	string

Upload data about deals to a project¶

POST /project/add-orders

Description

A method to upload data about deals to a project.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/add-orders?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}' \ 
    --data Request body - see below

Request Body:

[
    {
        "id": "1",
        "name": "New order",
        "date_create": "1393673200",
        "status": "0",
        "roistat": "12345",
        "price": "222",
        "cost": "111",
        "fields": {
            "Manager": "John Doe"
        }
    },
    {
        "id": "2",
        "name": "New order",
        "date_create": "1393673200",
        "status": "0",
        "roistat": "67890",
        "price": "333",
        "cost": "222",
        "fields": {
            "Manager": "John Doe"
        }
    }
]

Response Example

{
    "uploaded": 0,
    "processed": 0,
    "skipped_by_status": 0,
    "skipped_by_waiting_visit_info": 0,
    "skipped_by_internal_error": 0,
    "skipped_because_not_changed": 0,
    "skipped_fields_by_invalid_format": 0,
    "saved": 0,
    "comment": "",
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

Parameter	Type	Description	Required
id	string	Deal ID in a CRM system	no
name	string	A human-readable deal name in the CRM system	no
date_create	string	Date when the deal was created; in UNIX-time or YYYY-MM-DD HH:MM format	no
status	string	Status ID статуса from the `statuses` array	no
roistat	null or string	Visit ID	no
price	null or string	Deal value; used to calculate "Revenue" in Roistat	no
cost	null or string	First cost of the deal	no
fields	object	Custom fields. - maximum 1000 symbols for a field.	no

Response Parameters

Parameter	Type	Description
uploaded	integer	The number of imported deals
processed	integer
skipped_by_status	integer
skipped_by_waiting_visit_info	integer
skipped_by_internal_error	integer
skipped_because_not_changed	integer
saved	integer

Get all information about the deal¶

GET /project/orders/{orderId}/info

Description

Use this method to get complete information about a deal, including products and all visits from the visit chain. orderId can be obtained using the following method: /project/integration/order/list.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/orders/order_12345/info?project=12345' \
    --request GET \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}'

Response Example

{
    "order": {
        "id": "order_12345",
        "title": "order_12345",
        "url": "https://example.com/order/order_12345",
        "source": {
            "type": "phone",
            "icon_url": "https://cloud.roistat.com/img/order_source/calltracking.png",
            "title": "Call tracking"
        },
        "creation_date": "2022-04-12T04:34:02+0000",
        "update_date": null,
        "paid_date": null,
        "status": "canceled",
        "status_name": "Rejected",
        "status_original": "4",
        "price": 9989.7279999999992,
        "cost": 0,
        "visit_id": "12345",
        "visit": {
            "id": "12345",
            "date": "2022-04-12T03:53:31+0000",
            "city": "Berlin",
            "country": "Germany",
            "country_icon": "https://cloud.roistat.com/img/country/de.png",
            "is_first_visit": 0,
            "is_order_visit": 1,
            "marker": "VK → Products of the month - Kitchen → Product of the month - Decor set",
            "marker_info": [
                {
                    "marker": "vk4",
                    "alias": "VK"
                },
                {
                    "marker": "35",
                    "alias": "Products of the month - Kitchen"
                },
                {
                    "marker": "31902633",
                    "alias": "Product of the month - Decor set"
                }
            ],
            "marker_icon": "https://favicon.yandex.net/favicon/vk.com",
            "referrer": "http://avito.ru/some-adv",
            "landing_page": "http://cozy.home.ru/catalog/lights",
            "host": "cozy.home.ru",
            "os_name": "Windows 8.1",
            "os_icon": "https://cloud.roistat.com/img/os/win81.png",
            "browser_name": "Firefox",
            "browser_icon": "https://cloud.roistat.com/img/browsers/firefox.png"
        },
        "fields_data": {
            "status_name": "Rejected",
            "Rejection reason": "Chose competitors",
            "Manager": "Jack Smith",
            "roistat": 32446
        },
        "is_multichannel": 1,
        "visits_count": 2,
        "client_phones": [
            "+70005746130"
        ],
        "client_emails": [
            "John_Smith_19701028@example.com"
        ],
        "client_name": "John Smith",
        "client_id": "817",
        "client_external_id": "817",
        "is_first": true,
        "is_first_sale": false
    },
    "visits": [
        {
            "id": "6724",
            "date": "2022-03-24T14:52:28+0000",
            "city": "Berlin",
            "country": "Germany",
            "country_icon": "https://cloud.roistat.com/img/country/de.png",
            "is_first_visit": 1,
            "is_order_visit": 0,
            "marker": "SEO → Google",
            "marker_info": [
                {
                    "marker": "seo",
                    "alias": "SEO"
                },
                {
                    "marker": "google",
                    "alias": "Google"
                }
            ],
            "marker_icon": "https://cloud.roistat.com/img/MagnifyingGlass.png",
            "referrer": "http://fb.com",
            "landing_page": "http://cozy.kitchen.ru/catalog/techniques",
            "host": "cozy.kitchen.ru",
            "os_name": "Windows 8.1",
            "os_icon": "https://cloud.roistat.com/img/os/win81.png",
            "browser_name": "Chrome",
            "browser_icon": "https://cloud.roistat.com/img/browsers/chrome.png"
        },
        {
            "id": "12345",
            "date": "2022-04-12T03:53:31+0000",
            "city": "Berlin",
            "country": "Germany",
            "country_icon": "https://cloud.roistat.com/img/country/ru.png",
            "is_first_visit": 0,
            "is_order_visit": 1,
            "marker": "VK → Products of the month - Kitchen → Product of the month - Decor set",
            "marker_info": [
                {
                    "marker": "vk4",
                    "alias": "VK"
                },
                {
                    "marker": "35",
                    "alias": "Products of the month - Kitchen"
                },
                {
                    "marker": "31902633",
                    "alias": "Product of the month - Decor set"
                }
            ],
            "marker_icon": "https://favicon.yandex.net/favicon/vk.com",
            "referrer": "http://avito.ru/some-adv",
            "landing_page": "http://cozy.home.ru/catalog/lights",
            "host": "cozy.home.ru",
            "os_name": "Windows 8.1",
            "os_icon": "https://cloud.roistat.com/img/os/win81.png",
            "browser_name": "Firefox",
            "browser_icon": "https://cloud.roistat.com/img/browsers/firefox.png"
        }
    ],
    "products": [
        {
            "id": "product_0",
            "name": "W-1",
            "price": 3320.0999999999999,
            "cost": 2213.4000000000001,
            "brand": "Windows for Everyone",
            "variant": null,
            "categories": [
                {
                    "level": "1",
                    "value": "Economy"
                },
                {
                    "level": "2",
                    "value": "Plastic"
                }
            ],
            "quantity": 1,
            "fields": []
        },
        {
            "id": "product_15",
            "name": "W-2",
            "price": 5630.3999999999996,
            "cost": 3753.5999999999999,
            "brand": "Country House Windows",
            "variant": null,
            "categories": [
                {
                    "level": "1",
                    "value": "Standard"
                },
                {
                    "level": "2",
                    "value": "Wooden"
                }
            ],
            "quantity": 1,
            "fields": []
        }
    ],
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

No parameters.

Response Parameters

Parameter	Type	Description
order	object	Order information
> id	string	Order ID
> title	string	Order title
> url	string	Order external URL from CRM
> source	object	Information about the deal source
>> type	string	Source type: `proxyform` – lead from the form, `phone` – Call Tracking, `lead_hunter` – Lead Hunter
>> icon_url	string	Source icon link
>> title	string	Source type title
> creation_date	string	Date and time of the deal creation in UTC0 format
> update_date	null or string	Date and time of the last change of the deal data in UTC0 format
> paid_date	null or string	Date and time of the last change of the deal payment data in UTC0 format
> status	string	Status group to which the current deal status belongs: `progress` – In work, `paid` – Paid, `canceled` – Canceled
> status_name	string	Status name
> status_original	string	Status ID
> price	number	Deal price
> cost	number	Deal cost
> visit_id	string	The number of the visit on which the deal was created
> visit	object	Information about the visit on which the deal was created
>> id	string	Visit number
>> date	string	Date and time of visit
>> city	string	Client city
>> country	string	Client country
>> country_icon	string	Country icon link
>> is_first_visit	number	Is this visit the first: 0 – no, 1 – yes
>> is_order_visit	number	Is the deal created on this visit: 0 – no, 1 – yes
>> marker	string	Visit source (all levels)
>> marker_info	array[object]	Information about each visit source level
>>> marker	string	Level marker
>>> alias	string	Human-readable level name
>> marker_icon	string	Channel icon link
>> referrer	string	The page the client came from
>> landing_page	string	The page the client visited
>> host	string	Domain
>> os_name	string	Client OS
>> os_icon	string	OS icon link
>> browser_name	string	Client browser
>> browser_icon	string	Browser icon link
> fields_data	object	Additional fields data
>> [Название поля]	string	Additional field value
> is_multichannel	number	Is this lead multi-channel: 0 – no, 1 – yes
> visits_count	number	Number of visits in the chain
> client_phones	array[string]	Client phone numbers
> client_emails	array[string]	Client email addresses
> client_name	string	Client name
> client_id	string	Client ID
> client_external_id	string	Client ID in CRM
> is_first	boolean	Is this deal a first for the client
> is_first_sale	boolean	Is this sale a first for the client
visits	array[object]	Information about each visit in the chain
> id	string	Visit number
> date	string	Date and time of visit
> city	string	Client city
> country	string	Client country
> country_icon	string	Country icon link
> is_first_visit	number	Is this visit the first: 0 – no, 1 – yes
> is_order_visit	number	Is the deal created on this visit: 0 – no, 1 – yes
> marker	string	Visit source (all levels)
> marker_info	array[object]	Information about each visit source level
>> marker	string	Level marker
>> alias	string	Human-readable level name
> marker_icon	string	Channel icon link
> referrer	string	The page the client came from
> landing_page	string	The page the client visited
> host	string	Domain
> os_name	string	Client OS
> os_icon	string	OS icon link
> browser_name	string	Client browser
> browser_icon	string	Browser icon link
products	array[object]	Information about the products in the deal
> id	string	Product ID
> name	string	Product name
> price	number	Product price
> cost	number	Product cost
> brand	string	Product brand
> variant	string	Product variant
> category	array[object]	Product category (nesting up to 5 levels)
>> level	string	Nesting level
>> value	string	Level title
> quantity	integer	Products quantity
> fields	array	Additional fields
status	string	Request status

Get the external URL of a deal (from your CRM system)¶

GET /project/orders/{orderId}/external-url

Description

Use this method to get the external URL of a deal (from your CRM system).

Request Example

curl 'https://cloud.roistat.com/api/v1/project/orders/123/external-url?project=12345' \
    --request GET \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}'

Response Example

{
    "externalUrl": "http://new123qwerty.amocrm.ru/leads/detail/123",
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

No parameters.

Response Parameters

Parameter	Type	Description
externalUrl	string	URL of the deal in the CRM system
status	string

Get deal status IDs in integrated CRM¶

POST /project/integration/status/list

Description

Using this method, you can find out the IDs of all deal statuses in the integrated CRM.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/integration/status/list?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}'

Response Example

{
    "data": [
        {
            "id": "deal_WON",
            "name": "Successful deal (Main) (Deals)",
            "type": "paid"
        },
        {
            "id": "deal_PREPAYMENT_INVOICE",
            "name": "Prepayment invoice (Main) (Deals)",
            "type": "progress"
        },
        {
            "id": "deal_NEW",
            "name": "New (Main) (Deals)",
            "type": "progress"
        },
        {
            "id": "deal_PREPARATION",
            "name": "Preparing documents (Main) (Deals)",
            "type": "progress"
        },
        {
            "id": "deal_EXECUTING",
            "name": "In progress (Main) (Deals)",
            "type": "progress"
        },
        {
            "id": "lead_NEW",
            "name": "Unsorted (Leads)",
            "type": "progress"
        },
        {
            "id": "lead_IN_PROCESS",
            "name": "In progress (Leads)",
            "type": "progress"
        },
        {
            "id": "lead_PROCESSED",
            "name": "Processed (Leads)",
            "type": "progress"
        },
        {
            "id": "lead_CONVERTED",
            "name": "Quality lead (Leads)",
            "type": "progress"
        },
        {
            "id": "deal_1",
            "name": "Name (Main) (Deals)",
            "type": "progress"
        },
        {
            "id": "deal_FINAL_INVOICE",
            "name": "Final invoice (Main) (Deals)",
            "type": "paid"
        },
        {
            "id": "lead_JUNK",
            "name": "Poor quality lead (Leads)",
            "type": "canceled"
        },
        {
            "id": "deal_LOSE",
            "name": "Deal failed (Main) (Deals)",
            "type": "canceled"
        },
        {
            "id": "deal_APOLOGY",
            "name": "Failure Cause Analysis (Main) (Deals)",
            "type": "canceled"
        }
    ],
    "total": 14,
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

No parameters.

Response Parameters

Parameter	Type	Description
data	array[object]
> id	string	A unique status identifier (ID) in Roistat
> name	string	A human-readable status name in a CRM system
> type	string	Status type in Roistat. It can be one of the groups that you use to classify your CRM statuses: `unused` - the "Not registered" group; `in progress` - the "Processing" group; `paid` - the "Paid" group; `canceled` - the "Rejected" group.
total	string	Total number of statuses
status	string

Upload statuses¶

POST /project/set-statuses

Description

This method is employed to upload statuses.

All statuses that you use must be sent in one array, not separately. If you wish to add new statuses, it is necessary to list both existing and new statuses in the request body.

If the ID of a new status coincides with the one already existing, a new status name will be uploaded.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/set-statuses?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}' \ 
    --data Request body - see below

Request Body:

[
    {
        "id": "1",
        "name": "New",
        "type": "progress"
    },
    {
        "id": "2",
        "name": "inProgress",
        "type": "progress"
    }
]

Response Example

{
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

Parameter	Type	Description	Required
id	string	A unique status identifier (ID) in Roistat	no
name	string	A human-readable status name in a CRM system	no
type	string	Status type in Roistat. It can be one of the groups that you use to classify your CRM statuses: `unused` - the "Not registered" group; `in progress` - the "Processing" group; `paid` - the "Paid" group; `canceled` - the "Rejected" group.	no

Response Parameters

Parameter	Type	Description
status	string

Get a list of additional transaction fields from your CRM¶

POST /project/analytics/order-custom-fields

Description

A method for obtaining a list of deal custom fields from your CRM.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/analytics/order-custom-fields?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}'

Response Example

{
    "fields": [
        "City",
        "Cashier",
        "Manager"
    ],
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

No parameters.

Response Parameters

Parameter	Type	Description
fields	object	Human-readable names of deal fields from a CRM system
> field1	string
> field2	string
> field3	string
status	string

Update the status of the deal¶

POST /project/integration/order/{orderId}/status/update

Description

Method to update the status of the deal.

Available only when integrating with goals or integrating via API.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/integration/order/123/status/update?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}' \ 
    --data Request body - see below

Request Body:

{
    "status_id": "1"
}

Response Example

{
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

Parameter	Type	Description	Required
status_id	string	ID of status in Roistat	no

Response Parameters

Parameter	Type	Description
status	string

Delete a deal¶

POST /project/integration/order/{orderId}/delete

Description

Method to delete a deal.

Available only with integration via API.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/integration/order/{orderId}/delete?project=12345' \
    --request POST \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}'

Response Example

No parameters.

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

No parameters.

Response Parameters

Parameter	Type	Description
status	string