Transferring Website Behavior Data via REST API

To transfer website data to our system, you need to install the web tracking script on your site. After, you’ll be able to send the user behavior data and use it to create personalized product recommendations for the site and for your emails.

You can send events through one of the methods:

  • Using eS.JS;
  • Using REST API. To transfer website data to our system, you need to install the web tracking script on your site. After, you’ll be able to send the user behavior data and use it to create personalized product recommendations for the site and for your emails.

📘

Important

When setting up tracking via the REST API, the recommendations functionality on the site will not be available, in this case, you need to use the option of calling eS.JS functions

In this article, we will explain how to use the second method.

Request headers

POST / HTTP/1.1

Host: https://tracker.esputnik.com/api/v2

Content-type: application/json

Response status code is 204: No authorization is required.

ProductPage

Description

To display correct recommended products or product categories or send triggers for abandoned browses, send a request with data on:

  • Product card the user is currently viewing;
  • Product price and availability.

Example

{
  "GeneralInfo": {
    "eventName": "ProductPage",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "ProductPage": {
    "Product": {
      "productKey": "72354",
      "price": "754 USD",
      "isInStock": "1",
      "tag_something": [
        "abc",
        "bca"
      ]
    },
    "Tags": {
      "some_tags": [
        "some_tag1",
        "some_tag2"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object
General information
eventName“ProductPage”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support team.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
user_es_contact_id"255830499"
Optional

type: string
User ID in the Reteno
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script. You can get on the site.
The required cookie is titled "sc."
datetime1579622183208Timestamp (millisecond)
ProductPageRequired

Type: object
Event description
productKey“72354”
Required

Type: string
Product ID.
Should match the productKey on pagesStatusCart and PurchasedItems.
price“754 USD”
Required

Type: string
The price per item can be sent with the currency value.

If the price has changed on the site but hasn’t changed in the feed, the sent value will be the value from the site.
isinStock“1”
Optional

Type: int
Indicates if items are in stock.
Can have two values:
"0" – items are out of stock;

"1" – items are in stock.

* If the availability has changed on the site but hasn’t changed in the feed, the sent value will be the value from the site.
tag_[something]["abc","bca"]
Optional

Type: array of strings
All additional fields can be transferred in this parameter. The prefix tag is required. After it, you can enter any name.
_ There can be several such parameters.
* The value of this parameter is transferred as a data array which can be entered separated by commas.
TagsOptional

Type: object
Additional fields

StatusCart

Description

An event is sent after the cart status (with a new GUID) is changed, for example, after clicking a Buy button on the category page. The cart status should be updated from all pages. If the cart is empty, then you need to send an empty cart event (empty array without products).

Example

{
  "GeneralInfo": {
    "eventName": "StatusCart",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "StatusCart": {
    "GUID": "6F9619FF-8B86-D011-B42D-00CF4FC964FF",
    "Products": [
      {
        "productKey": "430738",
        "price": 201.95,
        "discount": 180,
        "quantity": 1,
        "price_currency_code": "USD",
        "tag_something": [
          "aaa",
          "bbb"
        ]
      },
      {
        "productKey": "902339",
        "price": 596,
        "discount": 590,
        "quantity": 1,
        "price_currency_code": "USD",
        "tag_something": [
          "aaa",
          "bbb"
        ]
      }
    ],
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object, string
General information
eventName“StatusCart”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
user_es_contact_id"255830499"
Optional

Type: string
User ID in the platform
datetime1579622183208Timestamp (millisecond)
GUID“6F9619FF-8B86-D011-B42D-00CF4FC964FF”
Required

Type: string
Unique ID that connects two events – StatusCart and PurchasedItems.
Should be identical to the GUID of the PurchasedItems event.
* Can be generated from random numbers and Latin characters.
StatusCartRequired

Type: object, string
Event description.
Transferred as an array of strings with products added to the cart.
productKey“430738”
Required

Type: string
Product ID.
Should match the productKey on the ProductPage page.
price“201.95”
Required

Type: string
Price per item
discount“180”
Optional

Type: string
Discount per item
quantity“1”
Required

Type: Int
Quantity of items
price_currency_code“USD”
Optional

Type: string
Currency
tag_[something]["abc","bca"]
Optional

Type: array of strings
All additional fields can be transferred in this parameter. The prefix tag is required. After it, you can enter any name.
_ There can be several such parameters,
* The value of this parameter is transferred as a data array which can be entered separated by commas.
TagsOptional

Type: object
Additional fields

Wishlist

Description

Sending the AddToWishlist event - at the time of adding a product to the wish list (favorites).

Necessary for calculating and displaying recommendations and sending triggers related to the wish list.

Example

{
  "GeneralInfo": {
    "eventName": "AddToWishlist",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "AddToWishlist": {
    "Product": {
      "productKey": "72354",
      "price": "754",
      "isInStock": "1",
      "tag_something": [
        "abc",
        "bca"
      ]
    },
    "Tags": {
      "some_tags": [
        "some_tag1",
        "some_tag2"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object
General information
eventName“AddToWishlist”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support team.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
user_es_contact_id"255830499"
Optional

type: string
User ID in the Reteno
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script. You can get on the site.
The required cookie is titled "sc."
datetime1579622183208Timestamp (millisecond)
AddToWishlistRequired

Type: object
Event description
productKey“72354”
Required

Type: string
Product ID.
Should match the productKey on pagesStatusCart and PurchasedItems.
price“754 USD”
Required

Type: string
The price per item can be sent with the currency value.

If the price has changed on the site but hasn’t changed in the feed, the sent value will be the value from the site.
isinStock“1”
Optional

Type: int
Indicates if items are in stock.
Can have two values:
_ "0" – items are out of stock;

"1" – items are in stock.

_ If the availability has changed on the site but hasn’t changed in the feed, the sent value will be the value from the site.
tag_[something]["abc","bca"]
Optional

Type: array of strings
All additional fields can be transferred in this parameter. The prefix tag is required. After it, you can enter any name.
_ There can be several such parameters.
* The value of this parameter is transferred as a data array which can be entered separated by commas.
TagsOptional

Type: object
Additional fields

PurchasedItems

Description

To display recommendations on the order confirmation page or to send triggers for abandoned carts, you need to send a request with the data on the purchased products.

Example

{
  "GeneralInfo": {
    "eventName": "PurchasedItems",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "PurchasedItems": {
    "GUID": "6F9619FF-8B86-D011-B42D-00CF4FC964FF",
    "OrderNumber": "123/2017",
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object, string
General information
eventName“StatusCart”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User’s name and surname
user_es_contact_id"255830499"
Optional

Type: string
User ID in our platform
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script that you can get on the site.
The required cookie is titled "sc."
GUID“6F9619FF-8B86-D011-B42D-00CF4FC964FF”
Required

Type: string
Unique ID that connects two events – StatusCart and PurchasedItems.
Should be identical to the GUID of the StatusCart event.
* Can be generated from random numbers and Latin characters.
OrderNumber“123/2017”
Required

Type: string
Order number.
Confirms purchase completion
TagsOptional

Type: object
Additional fields

PurchasedItems (One Click)

Description

The event is optionally sent after a purchase with one click or a purchase with afterpay.

Example

{
  "GeneralInfo": {
    "eventName": "PurchasedItems",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "PurchasedItems": {
    "Products": [
      {
        "product_id": "430738",
        "unit_price": "201.95",
        "quantity": 1
      },
      {
        "product_id": "211452",
        "unit_price": "341.80",
        "quantity": 2
      }
    ],
    "OrderNumber": "123/2017",
    "Tags": {
      "block_id": [
        "21246_r335v507"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object, string
General information
eventName“StatusCart”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
user_es_contact_id"255830499"
Optional

Type: string
User ID in the Reteno
datetime1579622183208Timestamp (millisecond)
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script that you can get on the site.
The required cookie is titled "sc."
OrderNumber“123/2017”
Required

Type: string
Order number.
Confirms purchase completion.
PurchasedItemsType: array of stringsList of items
product_id“430738”
Required

Type: string
Product ID.
Should match productKey on the ProductPage page.
unit_price“201.95”
Required

Type: string
Price per item
quantity“1”
Required

Type: Integer
Quantity of items
block_id“21246_r335v507”
Required

Type: string
Recommendation block ID. To get it, contact support.

ProductImpressions

Description

The event that transfers data on the block display. It’s sent by default through JS API. You don’t need to send it additionally.

Example

{
  "GeneralInfo": {
    "eventName": "ProductImpressions",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "ProductImpression": {
    "Products": [
      {
        "product_id": "430968",
        "container_type": "1253"
      },
      {
        "product_id": "430738",
        "container_type": "1254"
      },
      {
        "product_id": "429983",
        "container_type": "1255"
      }
    ],
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object
General information
eventName“ProductImpressions”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
user_es_contact_id"255830499"
Optional

Type: string
User ID in our platform
datetime1579622183208Timestamp (millisecond)
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script that you can get on the site.
The required cookie is titled "sc."
ProductImpressionsRequired

Type: array of objects
Description of impressions
Transferred as an array of objects.
product_id“430738”
Required

Type: string
ID of the product or category that is in the feed
container_type“1253”
Required

Type: string
Recommendation block number
TagsOptional

Type: object
Additional fields

CategoryPage

Description

Can be used to send data on:

  • Triggers;
  • Category browses without product card viewing;
  • Site browses without category or product card viewing.

You need to send a request with the data on the category the user is currently browsing.

Example

{
  "GeneralInfo": {
    "eventName": "CategoryPage",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "externalCustomerId": "1234509876",
    "user_phone": "1-541-754-3010",
    "user_email": "[email protected]",
    "user_name": "Gregori Boczynski",
    "user_es_contact_id": "255830499",
    "cookies": {
      "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
    }
  },
  "CategoryPage": {
    "Category": {
      "categoryKey": "Babies"
    },
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: object
General information
eventName“ProductPage”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User’s name and surname
user_es_contact_id"255830499"
Optional

Type: string
User ID in the Reteno
datetime1579622183208Timestamp (millisecond)
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script that you can get on the site.
The required cookie is titled "sc."
CategoryPageRequired

Type: object
Event description
categoryKey“Babies”
Required

Type: string
ID of the product or category
TagsOptional

Type: object
Additional fields

CustomerData

Description

To send triggers for abandoned browses or abandoned carts, you need to send a request with the data on the user.

Example

{
 "GeneralInfo": {
   "eventName": "CustomerData",
   "siteId": "8D3869C",
   "datetime":1579622183208,
   "externalCustomerId": "1234509876",
   "user_phone": "3801111111111",
   "user_email": "[email protected]",
   "user_es_contact_id": "255830499",
   "user_name": "Johny",
   "cookies": {
     "sc": "CDA68358-94FB-4D83-9655-3FEB3CGGG1"
   }
 }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: array of objects
General information
eventName“StatusCart”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"

Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
user_es_contact_id"255830499"

Optional

Type: string
User ID in the platform
datetime1579622183208Timestamp (millisecond)
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script that you can get on the site.
The required cookie is titled "sc."

CustomEvent

Description

CustomEvent is a custom event. You can give it a custom header depending on the action.

Example

{
    "GeneralInfo": {
        "eventName": "CustomEvent",
        "datetime":1579622183208,
        "externalCustomerId": "1234509876",
        "screendim": {
            "h": 1200,
            "w": 2304
        },
        "adblockEnabled": true,
        "device": "Desktop",
        "browser": {
            "name": "Chrome",
            "chrome": true,
            "version": "74.0",
            "webkit": true,
            "a": true
        },
        "siteId": "8A412DC",
        "cookies": {
            "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
        },
        "s_location": "https://example.com/product_id.html",
        "referrer": "https://example.com",
        "user_client_id": "",
        "user_city": "",
        "user_card_id": "",
        "user_name": "Gregori Boczynski",
        "user_phone": "1-541-754-3010",
        "user_email": "[email protected]",
        "user_es_contact_id": "255830499"
    },
    "CustomEvent": {
     "EventName":"my_event",
     "Tags": {
     "some_tags": [
         "1",
         "a2"
     ],
     "some_tags1": [
       "4",
     "gg"
     ]
}
    }
}

Parameters

NameExampleDescription
GeneralInfoRequired

Type: array of objects
General information
eventName“CustomEvent”
Required

Type: string
Event name
siteId“8A412DC”
Required

Type: string
To get your site ID, please contact our support.
Static parameter.
externalCustomerId"1234509876"
Optional

Type: string
External identifier generated in your system
user_phone"1-541-754-3010"
Optional

Type: string
Phone number in the international format
user_email"[email protected]"
Optional

Type: string
User email
user_name"Gregori Boczynski"
Optional

Type: string
User name and surname
datetime1579622183208Timestamp (millisecond)
cookies"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required

Type: object, string
Cookie sc is a cookie generated by our script that you can get on the site.
The required cookie is titled "sc."
CustomEventRequired

Type: array of objects
Event description
EventName“my_event”
Required

Type: string
Custom event name
TagsOptional

Type: array of objects
Additional fields where some_tags is the field name and “1” and “2” are its values (always transferred as array of strings)

SearchRequest

Description

To collect statistics on search queries, you need to send the value from the search line.

Use this event for triggers. Send it only if the search returned no results. In the trigger, such contacts will receive personal recommendations (at the moment, recommendations don’t depend on the value entered in the search, we will support this feature in the nearest future).

Example

eS('sendEvent', 'SearchRequest', {
    "SearchRequest": {"search":"input_value"}
});

Parameters

NameExampleDescription
input_value"Coffe"
Required
Type: String
Value from the search string. What we are looking for on the site.

ProductUpdate

Description

ProductUpdate is an optional event that updates product data in Reteno in real-time, regardless of the scheduled feed update. Send product properties that need constant updating — price, discount, availability, etc.

Example

{
  "GeneralInfo": {
    "eventName": "ProductUpdate",
    "siteId": "site_id",
  },
  "ProductUpdate": [
    {
      "brand": "Apple",
      "name": "iPhone 7",
      "description": "Some description",
      "product_id": "430738",
      "imgurl": "https://domain.com/apple/product_large.png",
      "unit_price": "201.95",
      "isInStock": "1",
      "tag_discount": ["10"],
      "tag_oldprice": ["224.38"],
      "price_currency_code": "UAH",
      "category": "level3",
      "category_id": ["3"],
      "tag_something": [
        "aaa",
        "bbb"
      ]
    },
    {
      "brand": "Apple",
      "name": "iPhone 7",
      "description": "Some description",
      "product_id": "430738",
      "imgurl": "https://domain.com/apple/product_large.png",
      "unit_price": "201.95",
      "isInStock": "1",
      "tag_discount": ["10"],
      "tag_oldprice": ["224.38"],
      "price_currency_code": "UAH",
      "category": "level1 > level2 > level3",
      "category_id": ["1", "2", "3"],
      "tag_something": [
        "aaa",
        "bbb"
      ]
    }
  ]
}

Parameters

NameExampleDescription
ProductUpdaterequiredrequired
siteIdsite_idrequired
product_id430738required
isInStock1required, could be 0 or 1
unit_price201.95optional field
descriptionSome descriptionoptional field
nameiPhone 7optional field
imgurlhttps://domain.com/apple/product_large.pngoptional field
brandAppleoptional field
tag_discount10optional field, should be a relative figure (%)
price_currency_codeUAHoptional field
tag_oldprice224.38optional field

If the item has a discount, you can pass the next parameters:

{
 "product_id": "1111",
 "unit_price": "270",
 "isInStock": 1,
 "price_currency_code": "UAH",
 "tag_oldprice": [
   "300"
 ],
 "tag_discount": [
   "10"
 ]
}

And if the product has not a discount, than:

{
 "product_id": "1111",
 "unit_price": "270",
 "isInStock": 1,
 "price_currency_code": "UAH"
}