Reporting Events via Server-Side API – Dynamic Yield Knowledge Base

For the endpoints, request structure, and examples, see the API Reference: Reporting Events

Events are used to track meaningful user interactions (such as purchase, add to cart, form completion, or rating a product) and for behavioral targeting, building audiences, reporting, and recommendations.

There are predefined schemas for most common events, but you can also fire custom events as needed.

Predefined events

These events have a standard schema for their properties, and the properties passed with the event are used by our backend for various purposes. See the list of predefined events for all the available types and their properties.

Predefined event properties and structure

Events can be batched together, and therefore, the events object is always an array.

Each predefined event has a required name property, used for display purposes, and an optional properties object. All attributes are also included within the properties object. This includes the event type (schema name), which is set in properties.dyType, and depending on the schema, any other required properties. The list of predefined events includes tables with all the properties.

See these properties in the following examples of reporting the predefined Add to Cart event (e-commerce) and Application (financial institutions):

Add to Cart event example (e-commerce)


      curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": {
        "dyid": "-4350463893986789401",
        "dyid_server": "-4350463893986789401"
      },
      "session": { "dy": "ohyr6v42l9zd4bpinnvp7urjjx9lrssw" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Add to Cart",
          "properties": {
            "dyType": "add-to-cart-v1",
            "value": 39.95,
            "currency": "GBP",
            "productId": "item-34454ga",
            "quantity": 1
          }
        }
      ]
    }'

Add to Cart event example (e-commerce, API-only mode)


      curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "session": { "custom": "iquahngaishe2koh" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Add to Cart",
          "properties": {
            "dyType": "add-to-cart-v1",
            "value": 39.95,
            "currency": "GBP",
            "productId": "item-34454ga",
            "quantity": 1
          }
        }
      ]
    }'

Application event example (financial institutions)


      curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": {
        "dyid": "-4350463893986789401",
        "dyid_server": "-4350463893986789401"
      },
      "session": { "dy": "ohyr6v42l9zd4bpinnvp7urjjx9lrssw" },
     "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Application Started",
          "properties": {
            "dyType": "add-to-cart-v1",
            "value": 1,
            "currency": "GBP",
            "productId": "item-34454ga",
            "quantity": 1
          }
        }
      ]
    }'

Note that the predefined add-to-cart-v1 type in these examples requires two mandatory properties:

productId that must exactly match a SKU in the product feed.
quantity of the added product.

Notes:

Ensure that SKU formats do not vary at all between your feed, the events you report, and the context of pageviews you report. SKUs might seem simple, but they can include prefixes and suffixes that are used only in specific parts of your system. The component that generates the product feed is typically a completely different service than the code that reports client events, possibly written in a different language.
The value property can be passed in any event (including custom events) that has a monetary value. By default, this value is in your section's defined currency, though you can define any currency code in the currency attribute, and the value is then converted into the website's currency.

Events identifying users across channels

Some predefined events also serve to associate a given user ID to a customer ID (CUID). A user ID is unique to a device and might represent an anonymous user. It's the primary identifier in API endpoints. The optional CUID is a fixed identifier for a person that's the same across channels (web, mobile apps, email) and is usually assigned only to registered users. It enables linking the user's event history, affinity and audiences across multiple devices and channels.

The CUID can be any unique string. However, we recommend using the customer's email address as the unique identifier, to support email personalization features. Pass email addresses in hashed SHA256 format. While optional in some events, this ensures consistency between all identifying events for the same user reported from multiple sources, and with any first-party data that you upload. Note that hashed email addresses are then further encrypted when stored in our servers.

Dynamic Yield does not generally mandate that you pass a CUID, but it is required in some identifying events. See the list of predefined events for details.

The following are examples of identification events (Login and Identify user). With these event types, passing a CUID of any type (including hashed email) is mandatory. Without it, the event reports a login that might be a primary metric for a campaign, but does not tie the user ID to any CUID.

Login events

Login event for a known user, identified by a hashed e-mail address

  {
      "user": {
        "dyid": "7282320792394869879",
        "dyid_server": "7282320792394869879"
      },
      "session": { "dy": "e3xi77qrxbsxxxmi18d8kxek6tdd12qj" },
      "events": [
        {
          "name": "Login",
          "properties": {
            "dyType": "login-v1",
            "hashedEmail": "62eccc43b550b012b7ea7fb07e64baafb1508d8b715a55148ccf0f3322eab1a1"
          }
        }
      ]
    }'

Login event for a known user, identified by a hashed e-mail address (API-only mode)

     curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "session": { "custom": "iquahngaishe2koh" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Login",
          "properties": {
            "dyType": "login-v1",
            "hashedEmail": "43e62d636651bc44edcd528a510d57ce69126cd875c..."
          }
        }
      ]
    }'

Login event with a different identifier (not hashed email)

  {
      "user": {
        "dyid": "7282320792394869879",
        "dyid_server": "7282320792394869879"
      },
      "session": { "dy": "e3xi77qrxbsxxxmi18d8kxek6tdd12qj" },
      "events": [
        {
          "name": "Login",
          "properties": {
            "dyType": "login-v1",
            "cuidType": "clientId", //You can use any type you want to
            "cuid": "62eccc43b550b012b7ea7fb07e64baafb1508d8b715a55148ccf0f3322eab1a1"
          }
        }
      ]
    }'

Login event with a different identifier (not hashed email) (API-only mode)

     curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "session": { "custom": "iquahngaishe2koh" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Login",
          "properties": {
            "dyType": "login-v1",
            "cuidType": "clientId", //You can use any type you want to
            "cuid": "62eccc43b550b012b7ea7fb07e64baafb1508d8b715a55148ccf0f3322eab1a1"
          }
        }
      ]
    }'

Identify user events

Identify User event for a known user, identified by a hashed e-mail address

  {
      "user": {
        "dyid": "7282320792394869879",
        "dyid_server": "7282320792394869879"
      },
      "session": { "dy": "e3xi77qrxbsxxxmi18d8kxek6tdd12qj" },
      "events": [
        {
          "name": "Identify User",
          "properties": {
            "dyType": "identify-v1",
            "hashedEmail": "62eccc43b550b012b7ea7fb07e64baafb1508d8b715a55148ccf0f3322eab1a1"
          }
        }
      ]
    }'

Identify User event for a known user, identified by a hashed e-mail address (API-only mode)

     curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "session": { "custom": "iquahngaishe2koh" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Identify User",
          "properties": {
            "dyType": "identify-v1",
            "hashedEmail": "43e62d636651bc44edcd528a510d57ce69126cd875c..."
          }
        }
      ]
    }'

Identify User event with a different identifier (not hashed email)

  {
      "user": {
        "dyid": "7282320792394869879",
        "dyid_server": "7282320792394869879"
      },
      "session": { "dy": "e3xi77qrxbsxxxmi18d8kxek6tdd12qj" },
      "events": [
        {
          "name": "Identify User",
          "properties": {
            "dyType": "identify-v1",
            "cuidType": "clientId", //You can use any type you want to
            "cuid": "62eccc43b550b012b7ea7fb07e64baafb1508d8b715a55148ccf0f3322eab1a1"
          }
        }
      ]
    }'

Identify User event with a different identifier (not hashed email) (API-only mode)

     curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "session": { "custom": "iquahngaishe2koh" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Identify User",
          "properties": {
            "dyType": "identify-v1",
            "cuidType": "clientId", //You can use any type you want to
            "cuid": "62eccc43b550b012b7ea7fb07e64baafb1508d8b715a55148ccf0f3322eab1a1"
          }
        }
      ]
    }'

List of predefined events

Add to Cart (required for e-commerce)

Notes:

Make sure that productId matches a SKU in your product feed.
Optionally, you can pass the fully updated cart with the newly added product to ensure that the cart state as known to Dynamic Yield is fully in sync with your system. This is mainly needed for triggered email and push notifications.

Property	Description	Type
dyType	Must be "add-to-cart-v1".	String
value	Add to Cart events must always have the total value of the added product. Value must be non-negative.	Float
currency (optional)		String
productId	SKU as in the feed.	String
quantity	Product quantity added, must be non-negative.	Number
cart	New cart state, including newly added item.	Array of objects. Properties of each object: productId: string quantity: number itemPrice: float in dollars.cents format

Example of a JSON payload for an Add to Cart event

{
  name: "Add to Cart",
  properties: {
    dyType: "add-to-cart-v1",
    value: 198.00,
    productId: "p-tv78615a",
    quantity: 2,
    cart: [
      {
        productId: "p-cr91275g",
        quantity: 1,
        itemPrice: 49.95
      },
      {
        productId: "p-tv78615a",
        quantity: 2,
        itemPrice: 99.00,
      }
    ]
  }
}

Application (required for Financial Institutions)

Notes:

Make sure that productId matches a SKU in your product feed.
Optionally, you can pass the fully updated cart with the newly added product to ensure that the cart state as known to Dynamic Yield is fully in sync with your system. This is mainly needed for triggered email and push notifications.

Property	Description	Type
dyType	Must be "add-to-cart-v1".	String
value	Add to Cart events must always have the total value of the added product. Value must be non-negative.	Float
currency (optional)		String
productId	SKU as in the feed.	String
quantity	Product quantity added, must be non-negative.	Number
cart	New cart state, including newly added item.	Array of objects. Properties of each object: productId: string quantity: number itemPrice: float in dollars.cents format

Example of a JSON payload for an Application event

{
  name: "Application Started",
  properties: {
    dyType: "add-to-cart-v1",
    value: 1,
    productId: "p-tv78615a",
    quantity: 1,
    cart: [
      {
        productId: "p-tv78615a",
        quantity: 1,
        itemPrice: 1
      }
    ]
  }
}

Remove from Cart

The Remove from Cart event uses the same schema as Add to Cart, except for its dyType property value. Unlike Add to Cart, it isn't mandatory to implement this event unless you're using features that rely on Dynamic Yield holding the most up-to-date cart state (currently only triggered emails and push notifications).

Property	Description	Type
dyType	Must be "remove-from-cart-v1".	String
value	Remove from Cart events must always include the total value of the removed product. Value must be non-negative.	Float
currency (optional)		String
productId	SKU as in the feed.	String
quantity	Product quantity removed, must be non-negative.	Number
cart	New cart state, after the item is removed.	Array of objects. Properties of each object: productId: string quantity: number itemPrice: float in dollars.cents format

Sync Cart

This optional event can be fired upon any change to the cart that isn't adding or removing a specific product from cart, and updates the current cart state. It's mandatory for the Exclude items currently in cart filter; for this filter, it must be implemented on every page load.

Property

Description

Type

dyType

Must be "sync-cart-v1".

String

cart

New cart state, including adjusted items.

Array of objects.

Properties of each object:

productId: string
quantity: number
itemPrice: float in dollars.cents format

Purchase (required for e-commerce)

Notes:

Make sure that the productId property of each product matches a SKU in your product feed.
In this event, unlike adding/removing from cart, the cart parameter is mandatory and describes all products purchased, rather than the new cart state post-purchase (which is usually empty).
The value parameter should be the total value of the cart purchased.
The uniqueTransactionId property is optional but strongly recommended, for data validation / de-duping any duplicate events over the same purchase.

Property	Description	Type
dyType	Must be "purchase-v1".	String
value	Purchase events should always have the total value of the whole cart.	Float
currency (optional)		String
uniqueTransactionId	If you pass this value, Dynamic Yield ensures that only one purchase is recorded for that transaction ID, even if duplicate events are reported.	String, maximum 64 characters
cart	The products purchased.	Array of objects. Properties of each object: productId: string quantity: number itemPrice: float in dollars.cents format

Example of a JSON payload for a Purchase event

{
  name: "Purchase",
  properties: {
    dyType: "purchase-v1",
    value: 349.80,
    uniqueTransactionId: "exampleTransactionId",
    cart: [
      {
        productId: "p-tv78615a",
        quantity: 1,
        itemPrice: 249.90,
      },
      {
        productId: "p-cr91275g",
        quantity: 2,
        itemPrice: 49.95
      }
    ]
  }
}

Submission (required for Financial Institutions)

Notes:

Make sure that the productId property of each product matches a SKU in the product feed.
In this event, unlike adding/removing from cart, the cart parameter is mandatory and describes all products submitted.
The value parameter should be the total value of the application.
The uniqueTransactionId property is optional but strongly recommended, for data validation/de-duping any duplicate events over the same purchase.

Property	Description	Type
dyType	Must be "purchase-v1".	String
value	Purchase events should always have the total value of the whole cart.	Float
currency (optional)		String
uniqueTransactionId	If you pass this value, Dynamic Yield ensures that only one purchase is recorded for that transaction ID, even if duplicate events are reported.	String, maximum 64 characters
cart	The products purchased.	Array of objects. Properties of each object: productId: string quantity: number itemPrice: float in dollars.cents format

Example of a JSON payload for a Submission event

{
  name: "Submission",
  properties: {
    dyType: "purchase-v1",
    value: 349.80,
    uniqueTransactionId: "exampleTransactionId",
    cart: [
      {
        productId: "p-tv78615a",
        quantity: 1,
        itemPrice: 249.90,
      }
     ]
  }
}

Login

Identifies a user (optional).

Use this event type to report a login by an existing registered user. For new account sign-up, use the Sign Up event instead.

Make sure to read the section Events Identifying a Customer Across Channels. This event can be used with or without passing any registered customer ID (CUID). The CUID can be either a hashed email or any custom type.

You have several choices of what to include when sending this event:

Report the event without any extra identifier to only track the action of the login itself.
Report the event with a hashed email, enabling you to use email features (and onboarding of first-party data, for which the primary key is typically hashed email).
Report the event with a non-email CUID type. In this case, you can specify the type by also setting the cuidType property. For example, pass crmId to designate identifiers created internally in your CRM. If cuidType is not set, a default type named id is used.

Property

Description

Type

dyType

Must be "login-v1".

String

hashedEmail (optional)

SKU as in the feed.

String

cuidType (optional)
cuid (optional)

Instead of a hashed email, you can pass a custom-type name into cuidType, and the actual ID in cuid.

If only cuid is set, the type is set by default to id.

String

Example of a JSON payload for a Login event, with a hashed email

{           
  "name": "Login",           
  "properties": {
    "dyType": "login-v1",
    "hashedEmail": "43e62d636651bc44edcd528a510d57ce69126cd875c..."           
  }
}

Add to Wishlist

Optional. Use if your users can add items to a wish list, and you want to track this behavior.

Property	Description	Type
dyType	Must be "add-to-wishlist-v1".	String
productId	SKU as in the feed.	String

Sign Up

Identifies a user (optional).

Report this event when a user has completed the sign-up process and has become a registered user. Optionally, you can also pass a hashed email or another customer ID (CUID) type to associate the user ID with that CUID.
Use this event the same way as the Login Event, with the dyType of "signup-v1".

Newsletter Subscription

Identifies a user.

Report this event to track subscriptions (regardless of whether the user has an account) and associate the anonymous user ID with the hashed email entered by the user. This event does not accept custom user ID types, and its main use is for enabling personalized email features.

Property	Description	Type
dyType	Must be "newsletter-subscription-v1".	String
hashedEmail	SHA-256 encoding of the lowercase email.	String

Keyword Search

The user runs a free-style keyword search.

Property	Description	Type
dyType	Must be "keyword-search-v1".	String
keywords	The search string, as is.	String

Video Watch

Report this event to track a video watch in media sites and applications.

Property	Description	Type
dyType	Must be "video-watch-v1".	String
itemId	Mandatory string ID matching an identified present in the Content Feed.	String
autoPlay (optional)	Indicates whether video played automatically or because of an explicit user action.	Boolean, false by default
progress (optional)	One of the following values: VIDEO_STARTED (default): The video started playing. This does not indicate whether it was watched in full. PREROLL_FINISHED: The pre-roll was watched in full. VIDEO_FINISHED: The content was watched in full. VIDEO_PROGRESS: If the client can periodically report fine-grained progress as a percentage, use this value in conjunction with progressPercent.	String
progressPercent	Only relevant if the progress value is VIDEO_PROGRESS.	Number

Example of a JSON payload for a Video Watch event

{
"name": "Video Pre-roll Ended",
"properties": {
"dyType": "video-watch-v1",
"itemId":v-g67811a-people-watching-got-finale",
"autoplay": true,
"progress": "PREROLL_FINISHED"
}
}

Custom events

Use custom events to report any event that isn't already defined for use in Experience OS, but is significant to your business.

A custom event:

Must have a name for display, but does not have a dyType as part of the properties.
Can have a monetary value, with or without the optional currency designation.
Can have zero or more extra properties: Strings, numbers, and Boolean values. Note that we don't support nested properties when creating targeting rules over custom events.

Here's an example:

Event for a known user, identified by a hashed e-mail address

  {
      "user": {
        "dyid": "7282320792394869879",
        "dyid_server": "7282320792394869879"
      },
      "session": { "dy": "e3xi77qrxbsxxxmi18d8kxek6tdd12qj" },
      "events": [
        {
          "name": "ExampleEvent1",
          "properties": {
            "isVIP": "true"
          }
        },
        {
            "name": "exampleEvent2"
        }
      ]
    }'

Event for a known user, identified by a hashed e-mail address (API-only mode)

  
  curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "sessionId": "iquahngaishe2koh",
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Filled Post-Purchase Survey",
          "properties": {
            "customerRole": "VP of Staplers",
            "experienceRating": 4,
            "likesSpecialOffers": true
          }
        }
      ]
    }'

HTTP response codes

Code	Meaning
204	Request succeeded. No body is returned
400	Error parsing request
401	Invalid or missing API key
403	Access denied for a valid API key
405	Wrong HTTP method (not POST, in this case)
422	Request body did not match schema
429	Too many requests received
451	Wrong key type was used (server-side key used from client-side or client-side key used from server-side)
500	Unspecified internal error