Events API overview

📘

Before you begin

Check out our general API overview to make sure you're ready to get started with specific endpoints.

Our Events API allows you to retrieve and create events, which are actions taken by Klaviyo profiles. Each event has exactly one metric (effectively the “event type”) associated with it and a timestamp for when it occurred. The metric and profile associated with an event are stored in the event’s relationships object. There are two types of endpoints within the Events API:

• Events endpoints for fetching or creating event data.
• Relationships endpoints for accessing a list of related metrics or profiles for a specific event.

Use cases

The Events API supports the following use cases:

• Creating custom events that can be used to trigger flows (e.g., a Reset Password event that triggers an email with a reset password URL).
• Getting Klaviyo events that can be used for data analysis (e.g., retrieving engagement events tracked by native Klaviyo metrics, such as Opened Email and Clicked SMS).
• Getting a specific profile’s events to power an activity feed.
• Getting related profile and/or metric data for a given event.

Data model

An event can have the following:

• properties (required)

  The properties of the event. Non-object properties can be used for creating segments. The $extra property records any non-segmentable values, e.g., HTML templates, that can be referenced later.

• time (optional)

  The timestamp of when the event occurred. By default, the value is the time the event was created. You should provide a time when creating a historical event for a profile.

• value (optional)

  The numeric value to associate with the event, e.g., a price.

• unique_id (optional)

  The unique identifier for an event.

• relationships

  • metric

    The metric associated with the event.

  • profile

    The profile associated with the event.

🚧

Note that if you do not provide a unique_id, multiple events sent at the same time will be assigned the same default unique_id and may be removed as duplicates. We recommend using uuidv4 or a similar method to create unique IDs for your events.

Events and metrics

Each event object is related to a metric object, per the data model above. A metric is what defines an event’s type. Think of a metric as a recipe name and its defined events as the instances in which the recipe was cooked. Each event includes the recipe name (metric), the chef (profile), the time the recipe was cooked, and details like ingredients (properties) and, optionally, value. When you create a custom event object via API, you’ll need to provide a metric name associated with the event, for example, Viewed Product. If the metric you provide does not match an existing one, a new metric will be created with its own metric_id. The metric_id connects the metric to an event. This ID, along with other fields like profile_id, can be used to query events.

Create Event

To create an event, you’ll need at least one profile identifier (e.g., id, email, or phone_number) and a metric name. [See our guide on profiles for more information on identifiers.] Your request payload for Create Event should be formatted like the example Reset Password event below:

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
     "action": "Reset Password" 
    },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Reset Password"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "[email protected]"
          },
          "properties":{
          "PasswordResetLink": "https://www.website.com/reset/1234567890987654321"
          }
        }
      },
    "unique_id": "4b5d3f33-2e21-4c1c-b392-2dae2a74a2ed"
    }
  }
}

In the example Create Event payload, an email, [email protected], and a metric name, Reset Password, are provided to associate the created event with a profile and a metric. The only optional field provided is the unique_id in UUID format for good practice. Once the event has been created, you should see the event logged in the profile’s activity feed in Klaviyo:

Using optional fields

When creating an event, you might want to use optional fields like time (for historical events) and/or value (e.g., price) to include relevant information. Ordered Product events are useful for creating flows based on product-specific information. They can also help with creating more personalized recommendations for your customers. In the example below, an Ordered Product event is created with the value field representing the product’s price:

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "OrderId": "cc50e5b3-059c-4f7d-9e26-821302b63235",
        "ProductId": "1111",
        "SKU": "WINNIEPOOH",
        "ProductName": "Winnie the Pooh",
        "Quantity": 1,
        "ProductURL": "http://www.example.com/path/to/product",
        "value": 9.99,
        "metric": {
            "data": {
            "type": "metric",
            "attributes": {
                "name": "Ordered Product"
            }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01H7FZEVECGN0MNQ8V417TPVP0",
          "attributes": {
            "email": "[email protected]",
            "phone_number": "+15005550006",
            ...
        }
      },
      "unique_id": "cc50e5b3-059c-4f7d-9e26-821302b63235"
   }
}

Get Event(s)

When making a Get Event or Get Events request, here’s an example of how the Reset Password event object from the example above might look in your response:

curl --request GET \
     --url https://a.klaviyo.com/api/events/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-10-15'

{
  "type": "event",
  "id": "4KAmvjsbt9F",
  "attributes": {
      "timestamp": 1700241683,
      "event_properties": {
          "action": "Reset Password",
          "$event_id": "4b5d3f33-2e21-4c1c-b392-2dae2a74a2ed"
      },
      "datetime": "2023-11-17 17:21:23+00:00",
      "uuid": "bafaeb80-856d-11ee-8001-47fc5d8979c5"
  },
  "relationships": {
      "profile": {
          "data": {
              "type": "profile",
              "id": "01H7FZEVECGN0MNQ8V417TPVP0"
          },
          "links": {
              "self": "https://a.klaviyo.com/api/events/4KAmvjsbt9F/relationships/profile/",
              "related": "https://a.klaviyo.com/api/events/4KAmvjsbt9F/profile/"
          }
      },
      "metric": {
          "data": {
              "type": "metric",
              "id": "WvcZZE"
          },
          "links": {
              "self": "https://a.klaviyo.com/api/events/4KAmvjsbt9F/relationships/metric/",
              "related": "https://a.klaviyo.com/api/events/4KAmvjsbt9F/metric/"
          }
      }
  },
  "links": {
      "self": "https://a.klaviyo.com/api/events/4KAmvjsbt9F/"
  }
}

Note that there are id values for the profile and metric associated with the event in the relationships object. The following example is a call to Get Profile using the profile id returned in the response:

curl --request GET \
     --url https://a.klaviyo.com/api/profile/01H7FZEVECGN0MNQ8V417TPVP0/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-10-15'

{
  "data": {
      "type": "profile",
      "id": "01H7FZEVECGN0MNQ8V417TPVP0",
      "attributes": {
          "email": "[email protected]",
          "phone_number": null,
          "external_id": null,
          "anonymous_id": null,
          "first_name": "Sarah",
          "last_name": "Mason",
          ...

The response contains the profile object with the same identifier used to create the Reset Password event, [email protected].

The following example is a call to Get Metric with the metric id value from the Reset Password response:

curl --request GET \
     --url https://a.klaviyo.com/api/metrics/WvcZZE/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-10-15'

{
  "data": {
      "type": "metric",
      "id": "WvcZZE",
      "attributes": {
          "name": "Reset Password",
          "created": "2023-10-31T18:42:12+00:00",
          "updated": "2023-10-31T18:42:12+00:00",
          "integration": {
              "object": "integration",
              "id": "7FtS4J",
              "name": "API",
              "category": "API"
          }
      },
      "links": {
          "self": "https://a.klaviyo.com/api/metrics/WvcZZE/"
      }
   }
}

The API-created metric object with the name Reset Password is returned in the response.

Querying events

Querying events with the Events API can help you achieve many use cases, such as populating a list with events that match a specific profile_id. Check out the supported query parameters below and test them out with our latest Postman collection. Note that support for given operators and fields is endpoint-specific. Review the API reference documentation for more information on allowed fields and query operators.

Query example

To filter events by profile ID profile_id, you can first use a Get Profiles query to obtain a profile’s id by email or phone number, like this call to Get Events:

GET /api/events?filter=equals(email,"[email protected]")

The following example is a request to Get Events and uses the id value obtained from the Get Profiles query above as the profile_id to filter events:

curl --request GET \
     --url https://a.klaviyo.com/api/events/?filter=equals(profile_id,"01H7FZEVECGN0MNQ8V417TPVP0") \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-10-15'

{
  "data": [
    {
      "type": "event",
      "id": "4KAmvjsbt9F",
      "attributes": {
          "timestamp": 1700241683,
          "event_properties": {
              "Action": "Reset Password",
                    "$event_id": "4b5d3f33-2e21-4c1c-b392-2dae2a74a2ed"
                },
          "datetime": "2023-11-17 17:21:23+00:00",
          "uuid": "bafaeb80-856d-11ee-8001-47fc5d8979c5"
      },
      "relationships": {
          "profile": {
              "data": {
                  "type": "profile",
                  "id": "01H7FZEVECGN0MNQ8V417TPVP0"
              },
              ...
          },
          "metric": {
              "data": {
                  "type": "metric",
                  "id": "WvcZZE"
              },
              ...
          }
      },
      "links": {
          "self": "https://a.klaviyo.com/api/events/4KAmvjsbt9F/"
      }
    }
  ],
  ...
}

Next steps

• Create an event in Postman for an existing profile in your Klaviyo test account.
• Check for the created event under the specific profile’s activity feed in Klaviyo.
• Make a call to Get Events to retrieve your new event.
• Try out some of the query parameters above to customize your response.

Additional resources

• Set up API-based transactional events
• Integrate an ecommerce platform without a pre-built Klaviyo integration
• JSON:API feature guides