1. Using the Events API to track events

Events API reference and data model

When you work with the Events API, refer to the API reference for the detailed data model and descriptions of all objects and keys.

For details about which keys and objects are required for specific events, refer to those events. For example, see Creating a bookmark add event, Creating a widget view event, or Creating a widget click event for their corresponding required keys.

The following is a sample data model of the API request:

Note

Not all keys shown in this sample are required for all event objects. Refer to each event for more information about which keys are required for that event.

{
  "action": "<event action>",
  "action_sub_type": "<event action subtype>",
  "client_time_ms": 1660088972963,
  "interaction_id": "<identifier to group visitor's interactions>",
  "name": "<event name>",
  "page_load_time_ms": 1660088972963,
  "request_id": "<identifier of search request>",
  "user_id": "<unique ID of visitor>",
  "uuid": "<unique ID of visitor>",
  "value": {
    "context": {
      "browser": {
        "app_type": "browser",
        "device": "mobile",
        "user_agent": "Mozilla/5.0 (iPhone14,6; U; CPU iPhone OS 15_4 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19E241 Safari/602.1"
        },
      "geo": {
        "city": "San Francisco",
        "country": "us",
        "ip": "207.242.49.4",
        "state": "CA",
        "zip": "94403"
        },
      "page": {
        "locale_country": "us",
        "locale_currency": "usd",
        "locale_language": "en",
        "referrer": "<URL of the referring page>",
        "title": "<Title of the current page>",
        "uri": "<URL of the current page>"
        },
      "user": {
        "addn_attributes": "<Custom map of user attributes>",
        "address": {
          "address_line_1": "9090 Main Street",
          "address_line_2": "Unit 204",
          "country": "US",
          "state": "CA",
          "zip": "94403"
          },
        "cuid": "<Permanent user ID in your system>",
        "eid": "<Opaque ID that represents the user's email ID>",
        "email": "[email protected]",
        "fbid": "<Facebook ID of the user>",
        "gender": "male",
        "segments": ["user_group_1", "user_group_2"...]
        }
      },
    "entities": [
        {
          "attributes": {
            "author": "<Author of entity>"
            },
          "entity_subtype": "article/blog",
          "entity_type": "content, product",
          "id": "<External unique identifier for the entity>",
          "uri": "<URI of the entity>"
          }
      ],
    "filters": [
      {
        "display_name": [
          "<Display name>"
          ],
        "end_value": "<string>",
        "facet_position": "<string>",
        "field": "<string>",
        "name": "<string>",
        "start_value": "<string>",
        "title": "<string>",
        "value": [
          "<string>"
          ],
        "value_position": [
          0
          ]
        }
      ],
    "index": 0,
    "request": {
      "advanced_query_text": "<Query text>",
      "keyword": "<Keyword>",
      "modified_keyword": "<Modified keyword>",
      "num_requested": 0,
      "num_results": 0,
      "page_number": 0,
      "page_size": 0,
      "redirect_url": "<Redirect URL>",
      "total_results": 0,
      }
    "review": {
      "comment": "<Comment text>",
      "id": "<Review ID>",
      "rating": 1
      },
    "rfkid": "<widget ID>",
    "transaction": {
      "coupon": "string",
      "order_id": "string",
      "order_subtotal": 0,
      "order_total": 0
      }
    }
  }
If you have suggestions for improving this article, let us know!