Track Events

Track events from your server. Please include at least one of: userId, externalId, or email. These properties help us associate events with existing users. For top-level visitor properties: null clears the existing value, while undefined, omitted fields, and empty strings are ignored. For entries inside custom_properties: null, undefined, and empty strings are all ignored (custom_properties use merge semantics). See https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.

Request Body

application/json

The payload to track an event The schema describes canonical JSON inputs. The server also accepts values normalized by the preprocessing described on individual fields.

TypeScript Definitions

Use the request body type in TypeScript.

event*string

The name of the event you're tracking. This must be whitelisted in the Ours dashboard. Leading and trailing whitespace is removed before validation.

Match\S

Length1 <= length <= 1000

token*string

The token for your Source. You can find this in the dashboard. Leading and trailing whitespace is removed before validation.

Match\S

Length1 <= length <= 250

userId?|

The Ours Visitor ID stored in local storage and cookies on your web properties. When present, this is used directly — no lookup by externalId, email, or phone is performed. If you have both a userId and an externalId, send both so the event is attached to the right visitor without any lookup overhead. Leading and trailing whitespace is removed before validation.

Match\S

Length1 <= length <= 400

externalId?|

Your system's unique identifier for this user. When userId is absent, we search your account for an existing visitor with this externalId. If no match is found, we try email and then userProperties.phone_number before creating a new visitor. If you also have the userId from cookies or local storage, send both — it removes the lookup round-trip. Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation.

Match\S

Length1 <= length <= 400

email?|

The email address of a user. When userId is absent and externalId does not resolve a visitor, we search your account for a visitor with this email. If no match is found, we try userProperties.phone_number before creating a new visitor. Leading and trailing whitespace is removed before validation.

Match\S

Length1 <= length <= 1000

time?|

The time at which the event occurred in milliseconds since UTC epoch. The time must be in the past and within the last 7 days.

distinctId?|

A unique identifier for this event used for deduplication. Highly recommended — if omitted, Ours will generate one for you, but supplying your own gives you stronger idempotency guarantees (e.g. a Stripe payment intent ID or your internal order ID). Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation.

Match\S

Length1 <= length <= 400

eventProperties?|

Any additional event properties you want to pass along. Use at most 200 nonempty property keys and five object levels. Array contents do not count toward the object-depth limit. Empty keys are removed recursively, arrays are truncated to 250 entries, and top-level numbers outside the safe integer range become strings. After normalization, the serialized JSON must be shorter than 1,048,576 UTF-16 code units.

Propertiesproperties <= 200

userProperties?|

Properties to set on the visitor. (optional) You can also update these properties via the identify endpoint.

defaultProperties?|

These properties are used throughout the Ours app to pass known values onto destinations

identityContext?|

End-user network context for server-side calls. Required for probabilistic identity resolution when the caller is a backend server rather than an end-user browser.

Response Body

`application/json`

curl -X POST "https://example.com/track" \  -H "Content-Type: application/json" \  -d '{    "event": "string",    "token": "string"  }'

{  "success": true}

Track Events

Request Body

Response Body

200application/json

400application/json

401application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`