Transferring Website Behavior Data via REST API

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:

📘

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.yespo.io/api/v2

Content-type: application/json

Response status code is 200: 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

Name

Example

Description

GeneralInfo

Required
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 Yespo

cookies

"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required
Type: object, string

Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc”

datetime

1579622183208

Timestamp (millisecond)

ProductPage

Required
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.

Tags

Optional
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

Name

Example

Description

GeneralInfo

Required
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

datetime

1579622183208

Timestamp (millisecond)

GUID

“6F9619FF-8B86-D011-B42D-00CF4FC964FF”
Required
Type: string

• Displays the current composition of the shopping cart
• Can be generated from random numbers and Latin letters

StatusCart

Required
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.

Tags

Optional
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

Name

Example

Description

GeneralInfo

Required

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 Yespo

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."

datetime

1579622183208

Timestamp (millisecond)

AddToWishlist

Required
Type: object

Event description

productKey

“72354”
Required
Type: string

• Product ID.
• Should match the productKey on the product page.

price

“754 USD”
Required
Type: string

The price per item.

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.

Tags

Optional
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 that will indicate which product the user purchased.

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": {
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

Name

Example

Description

GeneralInfo

Required
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 Yespo

datetime

1579622183208

Timestamp (millisecond)

cookies

"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required
Type: object, string

Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc”

OrderNumber

“123/2017”
Required
Type: string

• Order number.
• Confirms purchase completion.

PurchasedItems

Type: array of strings

List 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

Tags

Optional
Type: object

Additional fields

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. If the script is not installed, transfer according to the format.

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

Name

Example

Description

GeneralInfo

Required
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

datetime

1579622183208

Timestamp (millisecond)

cookies

"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required
Type: object, string

Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc”

ProductImpressions

Required
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. You can get the container_type in response to a request for recommendations

Tags

Optional
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": "509876"
    },
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Parameters

Name

Example

Description

GeneralInfo

Required
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 Yespo

datetime

1579622183208

Timestamp (millisecond)

cookies

"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required
Type: object, string

Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc”

CategoryPage

Required
Type: object

Event description

categoryKey

“Babies”
Required
Type: string

ID of the product or category according to a product feed

Tags

Optional
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.

Email should be sent at least in the personal account, on the page "Thank you for the order" and during registration.

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

Name

Example

Description

GeneralInfo

Required
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

datetime

1579622183208

Timestamp (millisecond)

cookies

"CDA68358-94FB-4D83-9655-3FEB3C4114A3"
Required
Type: object, string

Cookie sc is a cookie generated by our script if it is installed on your site. Each cookie must be unique for each user. You can create your own cookies. Example of calling this cookie from javascript document.cookie, the cookie we need is named “sc”

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

{
    "GeneralInfo": {
        "eventName": "SearchRequest",
        "siteId": "CE460EC",
        "datetime": 1668792552000,
        "externalCustomerId": "1234509876",
        "user_phone": "1-541-754-3010",
        "user_email": "[email protected]",
        "user_name": "Gregori Boczynski",
        "user_es_contact_id": "",
        "cookies": {
            "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
        }
    },
    "SearchRequest": {
        "search": "input_value",
        "isFound": 1
    }
}

Parameters

Name

Example

Description

search

"Coffe"
Required
Type: String

Value from the search string. What we are looking for on the site.

isFound

1/0
Optional
Type: int

If the list is empty, it returns 0 otherwise 1

ProductUpdate

Description

ProductUpdate is an optional event that updates product data in Yespo in real-time, regardless of the scheduled feed update. Pass 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",
      "url": "https://domain.com/apple/product_page_example.html",
      "unit_price": "201.95",
      "isInStock": "1",
      "tag_discount": ["10"],
      "tag_oldprice": ["224.38"],
      "price_currency_code": "UAH",
      "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

Name

Example

Description

ProductUpdate

Required
Type: Object

An array of updated products and their parameters

siteId

site_id
Required
Type: String

Site name

product_id

430738
Required
Type: Int

Product ID

isInStock

1
Required, can be 0 or 1
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.

unit_price

201.95
Optional
Type: Int

Unit price

description

Some description
Optional
Type: String

Product description

name

iPhone 7
Optional
Type: String

Product name

imgurl

https://domain.com/apple/product_large.png
Optional
Type: String

Image URL

url

https://domain.com/apple/product_page_example.html
Optional
Type: String

Product page URL

brand

Apple
Optional
Type: String

Brand name

tag_discount

10
Optional, should be a relative figure (%)
Type: Int

Discount

price_currency_code

UAH
Optional
Type: Int

Price currency code

tag_oldprice

224.38
Optional
Type: Int

Old price

If the product 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"
}