Clients¶

Create or update clients¶

POST /project/clients/import

Description

This method allows to create or update clients.

Request Example

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

Request Body:

[
    {
        "id": "111",
        "name": "John",
        "phone": "78888888888",
        "email": "email1@mail.com",
        "company": "company1",
        "birth_date": "1980-01-01",
        "fields":
        {
            "segment": "1"
        }
    },
    {
        "id": "222",
        "name": "Aria",
        "phone": "79999999999",
        "email": "email2@mail.com",
        "company": "company2",
        "birth_date": "1990-01-01",
        "fields":
        {
            "segment": "2"
        }
    }
]

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	Client ID in CRM	yes
name	string	Client's name	yes
phone	null or string	Client's phone number (either phone or email can be specified)	no
email	null or string	Client's email (either phone or email can be specified)	no
company	null or string	Client's company name	no
birth_date	null or string	Client's birth date	no
fields	object	additional fileds and their values in the following format: `"field_name": "value"`	no

Response Parameters

Parameter	Type	Description
status	string

Get a list of customers from Client Management¶

POST /project/clients

Description

This method allows you to get a list of customers from customer management.

Request Example

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

Request Body:

{
    "filters": [
        [
            "phone",
            "=",
            "79880002233"
        ]
    ],
    "limit": 100,
    "offset": 0
}

Response Example

{
    "clients": [
        {
            "id": 7,
            "first_visit_date": null,
            "external_id": "105",
            "name": "Client Name",
            "phone": "79880002233",
            "email": "test@roistat.test",
            "first_order_date": null,
            "last_order_date": null,
            "order_count": 0,
            "revenue": 0,
            "profit": 0,
            "birth_date": null,
            "company": "",
            "comment": null,
            "client_url": "http://example.crm.com/contacts/105",
            "first_visit_marker": null,
            "first_visit_marker_alias": "",
            "first_visit_marker_icon": "https://cloud.roistat.com/img/arrow-right.png",
            "first_visit_marker_alias_level_1": ""
        },
        {
            "id": 6,
            "first_visit_date": null,
            "external_id": "106",
            "name": "John",
            "phone": "79880002233",
            "email": "test@roistat.test",
            "first_order_date": null,
            "last_order_date": null,
            "order_count": 0,
            "revenue": 0,
            "profit": 0,
            "birth_date": null,
            "company": "",
            "comment": null,
            "client_url": "http://example.crm.com/contacts/106",
            "first_visit_marker": null,
            "first_visit_marker_alias": "",
            "first_visit_marker_icon": "https://cloud.roistat.com/img/arrow-right.png",
            "first_visit_marker_alias_level_1": ""
        }
    ],
    "total": 2,
    "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
limit	integer	no
offset	integer	no

Response Parameters

Parameter	Type	Description
clients	array[object]
>	object
>> id	integer	client ID in Roistat
>> first_visit_date	string or null	dare of first visit
>> external_id	string	client ID in CRM
>> name	string	client name
>> phone	string	client phone
>> email	string	client email
>> first_order_date	string or null	date of first order
>> last_order_date	string or null	date of last order
>> order_count	integer	number of orders
>> revenue	integer	revenue from orders
>> profit	integer	profit from orders
>> birth_date	string or null	birthday
>> company	string	client company name
>> comment	string or null
>> client_url	string	URL of client in the CRM
>> first_visit_marker	string or null
>> first_visit_marker_alias	string
>> first_visit_marker_icon	string
>> first_visit_marker_alias_level_1	string
total	integer
status	string

Get the client feed: visits, events, orders, calls, interaction with the Lead Hunter¶

GET /project/clients/detail/feed

Description

Use this method to get a specific client's feed: information on their visits, orders, order status changes, calls, triggered events, and interactions with the Lead Hunter.

Request Example

curl 'https://cloud.roistat.com/api/v1/project/clients/detail/feed?project=12345&client=123' \
    --request GET \
    --header 'Content-type: application/json' \ 
    --header 'Api-key: {KEY}'

Response Example

{
    "feed": [
        {
            "type": "visit",
            "visitId": "41028",
            "creationDate": "2021-11-10T14:05:12+0000",
            "sourceId": "instagram_stories",
            "device": {
                "os": "Mac 10.15 ",
                "os_icon": "https://cloud.roistat.com/img/os/macosx.png",
                "agent": "Chrome 90.0 browser Blink",
                "agent_icon": "https://cloud.roistat.com/img/browsers/chrome.png",
                "is_mobile": false
            },
            "sourceTitle": "instagram → stories",
            "sourceIcon": "https://cloud.roistat.com/img/instagram.png"
        },
        {
            "type": "order",
            "id": "order_41028",
            "name": "order_41028",
            "status": "0",
            "statusType": "progress",
            "statusTitle": "New",
            "revenue": 0,
            "formattedRevenue": "0 ₽",
            "cost": 0,
            "formattedCost": "0 ₽",
            "fields": {
                "status_name": "Pending payment",
                "Менеджер": "Jane Smith",
                "roistat": 41028
            },
            "creationDate": "2021-11-10T14:28:59+0000",
            "updateDate": null
        },
        {
            "type": "event",
            "metaId": "5",
            "creationDate": "2021-11-10T14:08:08+0000",
            "name": "Opening the cart page"
        },
        {
            "type": "lead_hunter_appearance",
            "date": "2021-11-08T16:53:16+0000",
            "page": "cozy.kitchen.com/catalog/accessories"
        },
        {
            "type": "lead_hunter_caught",
            "date": "2021-11-08T16:55:16+0000",
            "page": "cozy.kitchen.com/catalog/accessories"
            "name": "Jane"
            "field": "71234567890"
            "status": "1"
        },
        {
            "order_id": "order_41028",
            "order_title": "order_41028",
            "type": "orderStatusChange",
            "status": "1",
            "statusType": "progress",
            "statusTitle": "In Progress",
            "date": "2021-11-11T06:28:59+0000"
        },
        {
            "order_id": "order_41028",
            "order_title": "order_41028",
            "type": "orderStatusChange",
            "status": "2",
            "statusType": "progress",
            "statusTitle": "Pending payment",
            "date": "2021-11-11T07:28:59+0000"
        },
        {
            "order_id": "order_41028",
            "order_title": "order_41028",
            "type": "orderCostChange",
            "cost": 1000,
            "formattedCost": "1000 ₽",
            "date": "2021-11-11T07:28:59+0000"
        },
        {
            "order_id": "order_41028",
            "order_title": "order_41028",
            "type": "orderPriceChange",
            "price": 1000,
            "formattedPrice": "1000 ₽",
            "date": "2021-11-11T07:28:59+0000"
        }
    ],
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes
client	string	Client ID (you can get it by using /project/clients or find it in the list of clients)	yes

Response Body:

No parameters.

Response Parameters

Parameter	Type	Description
feed	array[object]
>	object
>> type	string	`visit` – if this type is specified, the array will contain visit data
>> visitId	string	Visit number
>> creationDate	string	Visit creation date in the following format: 2022-01-01T00:00:00+0300
>> sourceId	string	Visit marker
>> device	object	Information about the device from which the visit was made
>>> os	string	Операционная система
>>> os_icon	string	OS icon link
>>> agent	string	Browser
>>> agent_icon	string	Browser icon link
>>> is_mobile	boolean	Parameter indicating whether the device is mobile: true – yes, false – no
>> sourceTitle	string	Human-readable visit marker
>> sourceIcon	string	Link to the visit source icon
>	object
>> type	string	`order` – if this type is specified, the array will contain order data
>> id	string	Order ID
>> name	string	Order name
>> status	string	Status ID in Roistat (you can get in by using /project/integration/order/list](/API/methods/orders/#list))
>> statusType	string	The group to which the status is assigned in Roistat: unused – «Not included», progress – "In progress", paid – "Paid", canceled – "Rejected"
>> statusTitle	string	Status title
>> revenue	integer	Order revenue
>> formattedRevenue	string	Order revenue with currency
>> cost	integer	Order cost
>> formattedCost	string	Order cost with currency
>> fields	object	Additional order fields and their values
>> creationDate	string	Order creation date in the following format: 2022-01-01T00:00:00+0300
>> updateDate	string or null	Order update date
>	object
>> type	string	`event` – if this type is specified, the array will contain event data
>> metaId	string	Event ID in Roistat
>> creationDate	string	Event firing date in the following format: 2022-01-01T00:00:00+0300
>> name	string	Event name
>	object
>> type	string	`lead_hunter_appearance` – if this type is specified, the array will contain data on the client's interaction with the Lead Hunter
>> date	string	Date of interaction with the Lead Hunter in the following format: 2022-01-01T00:00:00+0300
>> page	string	The page where the client interacted with the Lead Hunter
>	object
>> type	string	`lead_hunter_caught` – if this type is specified, the array will contain data on caught leads
>> date	string	Lead creation date in the following format: 2022-01-01T00:00:00+0300
>> page	string	The page where the lead was caught
>> name	string	Lead name
>> field	string	Entered phone number
>> status	string	Lead status: 1 – sent, 0 – not sent
>	object
>> type	string	`orderStatusChange` – if this type is specified, the array will contain information about the order status change
>> order_id	string	Order ID
>> order_title	string	Order title
>> status	string	Status ID in Roistat (you can get in by using /project/integration/order/list](/API/methods/orders/#list))
>> statusType	string	The group to which the status is assigned in Roistat: unused – «Not included», progress – "In progress", paid – "Paid", canceled – "Rejected"
>> statusTitle	string	Status title
>> date	string	Status change date in the following format: 2022-01-01T00:00:00+0300
>	object
>> type	string	`orderCostChange` – if this type is specified, the array will contain information about the order cost change
>> order_id	string	Order ID
>> order_title	string	Order title
>> cost	integer	Changed order cost
>> formattedCost	string	Changed order cost with currency
>> date	string	Cost change date in the following format: 2022-01-01T00:00:00+0300
>	object
>> type	string	`orderPriceChange` – if this type is specified, the array will contain information about the order price change
>> order_id	string	Order ID
>> order_title	string	Order title
>> price	integer	Changed order price
>> formattedPrice	string	Changed order price with currency
>> date	string	Price change date in the following format: 2022-01-01T00:00:00+0300
>	object
>> type	string	`call` – if this type is specified, the array will contain data on client's calls
>> callee	string	Callee number
>> caller	string	Caller number
>> duration	string	Call duration in seconds
>> status	string	1 out of 9 call statuses: ACTIVE – the call is in progress; ANSWER – the call was accepted and processed by the employee; BUSY – there was an incoming call, but the line was busy; NOANSWER – there was an incoming call, but it was not accepted by the employee within the answer waiting time; CANCEL – there was an incoming call, but it was ended before the employee answered; CONGESTION – the call failed due to technical issues; CHANUNAVAIL – the called number was not available; DONTCALL – the incoming call was canceled; TORTURE – the incoming call was redirected to the answering machine.
>> date	string	Call date in the following format: 2022-01-01T00:00:00+0300
>> file_url	string	Call recording link
status	string	Request status

Get a list of emails in specific statuses¶

POST /project/clients/campaign/contact/list

Description

This method allows you to get a list of emails in specific statuses: Sent, Delivered, Opened, Clicked, Unsubscribed, Marked as spam. One or more statuses can be specified.

Request Example

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

Request Body:

{
    "metric_ids": ["sent"],
    "campaign_ids": [2]
}

Response Example

{
    "data": [
        {
            "contact": "john_smith@example.com",
            "metrics": {
                "sent": 1
            }
        },
        {
            "contact": "jack_peterson@example.com",
            "metrics": {
                "sent": 1
            }
        },
        {
            "contact": "jane_johnson@example.com",
            "metrics": {
                "sent": 1
            }
        }

    ],
    "count": 3,
    "total_count": 3,
    "status": "success"
}

Request Parameters

Query String:

Parameter	Type	Description	Required
project	string	Project number	yes

Request Body:

Parameter	Type	Description	Required
metric_ids	array[string]	Statuses for which you want to get emails: `"sent"` – Sent, `"delivered"` – Delivered, `"opened"` – Opened, `"click"` – Clicked, `"unsubscribe"` – Unsubscribed, `"spam"` – Marked as spam. One or more statuses can be specified.	yes
campaign_ids	array[integer]	Campaign IDs for which you want to get emails. Campaign IDs are displayed in the list of campaigns in the ID column. One or more IDs can be specified.	yes

Response Parameters

Parameter	Type	Description
data	array[object]
>	object
>> contact	string	Client's email
>> metrics	object	Object containing information about the selected statuses
>>> statusN	integer	Instead of `statusN`, the status specified in the `metric_ids` array is passed: `"sent"`, `"delivered"`, `"opened"`, `"click"`, `"unsubscribe"`, or `"spam"`. The value of the parameter is the number of emails in this status sent to the client.
count	integer	Number of query results within the limit
total_count	integer	Number of results regardless of the limit
status	string	Request status