PivolioEvent Ingestion

Track an event

Records a single event from a browser or server SDK using the workspace write key, then queues it for enrichment and delivery.

Authentication

X-Write-Keystring
API Key authentication via header

Request

This endpoint expects an object.
event_idstringRequired

Unique event ID (ULID)

event_namestringRequired

Event name (page_view, order_completed, etc.)

event_timedoubleRequired

Event timestamp (Unix seconds)

identityobjectRequired
Who the event belongs to
schema_version"1"OptionalDefaults to 1
Schema version
test_modebooleanOptionalDefaults to false
Whether event is in test mode
traitsobject or nullOptional

User traits (email, phone, etc.)

pageobjectOptional
Page information.
utmobjectOptional
Campaign attribution parameters, as captured from the landing URL.
click_idsobjectOptional
Click IDs from ad platforms.
clientobjectOptional

The requesting client’s environment.

ip and user_agent are stamped server-side from the connection: a client-supplied address would defeat geo, velocity and bot scoring.

deviceobjectOptional
Device information.
consentobjectOptional

Google Consent Mode v2.

A category is granted, denied, or absent — and absent is a real third state that ConsentWhenAbsent decides, not a synonym for either answer. Semantics live in pivolio.consent.

signalsobjectOptional

Header-derived signals captured at the HTTP edge for bot scoring. None means the header was absent.

sourceobjectOptional

How this event reached us, and from which installation.

Replaces the free-form webhook_source: the kind is a closed vocabulary so ingestion can be reported on, and integration_id answers which store or receiver when a workspace has more than one.

sessionobjectOptional

Client-side session the event belongs to (rotated after inactivity).

Empty for server-side events, which have no session. A start time without an id is rejected — that would be a session that does not exist but began.

libraryobjectOptional

SDK library metadata. Empty when the event did not come from an SDK.

Half-filled is rejected rather than made unrepresentable: the group has to be constructible empty so it can always be present, so the “both or neither” invariant moves from the type to a validator instead of being lost.

appobjectOptional
Mobile app information.
propertiesmap from strings to any or nullOptional
Event properties

Response

Successful Response
okbooleanOptionalDefaults to true
event_idstring or nullOptional
duplicatebooleanOptionalDefaults to false

Errors

422
Unprocessable Entity Error