Skip to main content
POST
/
events
curl --request POST \
  --url https://api.permutive.app/v2.0/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "Pageview",
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "view_id": "a55a9c8b-4a0b-4fe7-99a9-170624850501",
  "session_id": "1d145310-1338-4ff7-96dd-e6128f54cbe5",
  "properties": {
    "my_string": "hello, world!",
    "my_number": 42,
    "my_boolean": true,
    "my_object": {
      "inner_property_string": "nested value",
      "inner_property_integer": 69
    }
  }
}
'
{
  "name": "Pageview",
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "time": "2026-01-01T12:00:00.000Z",
  "view_id": "a55a9c8b-4a0b-4fe7-99a9-170624850501",
  "session_id": "1d145310-1338-4ff7-96dd-e6128f54cbe5",
  "properties": {
    "my_string": "hello, world!",
    "my_number": 42,
    "my_boolean": true,
    "my_object": {
      "inner_property_string": "nested value",
      "inner_property_integer": 69
    }
  }
}

​
Event schema

It’s important to note that Permutive enforces event schemas to ensure data consistency and validity. If an event is tracked that does not match the expected schema for the event type, it will be rejected and a 400 error will be returned. Where Permutive hasn’t received an event type before, it will infer the event’s schema. Event schemas are viewable in the Permutive Dashboard. To migrate an event schema, please email support.

​
Event size limit

The size of an event’s properties JSON object is limited to 950 KB to ensure platform performance. If an event exceeds this size limit, it will be rejected and a 400 error will be returned.

​
Time attributes

When streaming in data in real-time (e.g. from within an app), Permutive sets a time attribute for events to the current time in UTC.

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
enrich
boolean

This boolean parameter determines whether to enrich the event with geo, ISP, and natural language processing data. By default, this is set to true.

​
sdkp
boolean

This boolean parameter is used to describe whether the event originated from a Permutive SDK on a client's device, where true denotes the event was from an SDK and false denotes an out-of-SDK event.

By default, this parameter is set to true. If you are interacting with this endpoint directly, rather than through a Permutive SDK, please set this parameter to false.

Body

application/json

You must provide either a user_id or a non-empty list aliases of prioritized aliases to specify the user that the event belongs to.

If a user_id is provided, it will be used directly to identify the user, ignoring any aliases provided. If only aliases are provided and none match, a new user ID is generated and the aliases are synced to it.

​
name
string
required

The name of the event collection this event belongs to. The name is case-insensitive and must only contain characters in [a-zA-Z0-9_].

​
user_id
string<uuid>

The Permutive user ID of the user that the event belongs to.

If you do not provide a user ID, you must provide a non-empty list of aliases in the aliases field.

​
aliases
PrioritizedAlias · object[]

A non-empty list of prioritized aliases that the user is associated with. If you do not provide a list of aliases, you must provide a user ID in the user_id field.

Prioritized aliases allow customers to express which identifiers they consider most reliable or authoritative for resolving user identities.

When multiple aliases are provided, priorities are used to determine the order in which aliases are attempted for resolution to a Permutive user ID, where priority 0 has the highest priority.

Minimum array length: 1
​
view_id
string<uuid>

The identifier for the view in which the event is taking place. This is used to group events within a single page or screen view.

​
session_id
string<uuid>

The identifier for the session in which the event is taking place. This is used to group events within a user session.

​
segments
integer[]

The list of segment codes that the user belonged to at the time of the event.

​
cohorts
string[]

The list of cohort IDs that the user belonged to at the time of the event.

​
properties
JSON · object

The properties that belong to this event. These properties must adhere to the specific schema configured for this event collection.

Response

Event created successfully

​
user_id
string<uuid>
required

The Permutive user ID of the user that the tracked event belongs to.

​
name
string

The name of the event collection the tracked event belongs to. The name is case-insensitive and must only contain characters in [a-zA-Z0-9_].

​
time
string<date-time>

The ISO 8601 timestamp of the event.

​
view_id
string<uuid>

The identifier for the view in which the tracked event took place.

​
session_id
string<uuid>

The identifier for the session in which the tracked event took place.

​
segments
integer[]

The list of segment codes that the user belonged to at the time the event was tracked.

​
cohorts
string[]

The list of cohort IDs that the user belonged to at the time the event was tracked.

​
properties
JSON · object

The properties that belong to the tracked event. These properties adhere to the specific schema configured for this event collection.