HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
API Reference

Create Event

Create a new event to track a profile's activity.

Note that this endpoint allows you to create a new profile or update an existing profile's properties.

At a minimum, profile and metric objects should include at least one profile identifier (e.g., id, email, or phone_number) and the metric name, respectively.

Successful response indicates that the event was validated and submitted for processing, but does not guarantee that processing is complete.

Rate limits:
Burst: 350/s
Steady: 3500/m

Scopes:
events:write

Body Params
object
required
string
required
object
required
object
required

Properties of this event. Any top level property (that are not objects) can be
used to create segments. The $extra property is a special property. This records any
non-segmentable values that can be referenced later. For example, HTML templates are
useful on a segment but are not used to create a segment. There are limits
placed onto the size of the data present. This must not exceed 5 MB. This must not
exceed 300 event properties. A single string cannot be larger than 100 KB. Each array
must not exceed 4000 elements. The properties cannot contain more than 10 nested levels.

string
date-time

When this event occurred. By default, the time the request was received will be used.
The time is truncated to the second. The time must be after the year 2000 and can only
be up to 1 year in the future.

number

A numeric, monetary value to associate with this event. For example, the dollar amount of a purchase.

string

The ISO 4217 currency code of the value associated with the event.

string

A unique identifier for an event. If the unique_id is repeated for the same
profile and metric, only the first processed event will be recorded. If this is not
present, this will use the time to the second. Using the default, this limits only one
event per profile per second.

object
required
object
required
string
required
object
required
string
required

Name of the event. Must be less than 128 characters.

string

This is for advanced usage. For api requests, this should use the default, which is set to api.

object
required
object
required
string
required
string

Primary key that uniquely identifies this profile. Generated by Klaviyo.

object
required
string

Individual's email address

string

Individual's phone number in E.164 format

string

A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.

string
string

Also known as the exchange_id, this is an encrypted identifier used for identifying a
profile by Klaviyo's web tracking.

You can use this field as a filter when retrieving profiles via the Get Profiles endpoint.

string

Individual's first name

string

Individual's last name

string

Name of the company or organization within the company for whom the individual works

string

The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

string

Individual's job title

string

URL pointing to the location of a profile image

object
string

First line of street address

string

Second line of street address

string

City name

string

Country name

Latitude coordinate. We recommend providing a precision of four decimal places.

Longitude coordinate. We recommend providing a precision of four decimal places.

string

Region within a country, such as state or province

string

Zip code

string

Time zone name. We recommend using time zones from the IANA Time Zone Database.

string

IP Address

object

An object containing key/value pairs for any custom properties assigned to this profile

string
object
object

Specify one or more patch operations to apply to existing property data

object

Append a simple value or values to this property array

string
object

Remove a simple value or values from this property array

string
string

Remove a key or keys (and their values) completely from properties

Headers
string
required
Defaults to 2025-01-15

API endpoint revision (format: YYYY-MM-DD[.suffix])

Responses
202

Success

Language
Credentials