# paths./track.post.description
Track events from your server. Include at least one of userId, externalId, or email so the event can be associated with a visitor. Identity resolution runs in priority order: userId (direct, no lookup) → externalId (lookup by your ID) → email (fallback lookup). If you know both userId and externalId, send both. 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.

# paths./track.post.requestBody.content.application/json.schema.properties.event.description
The name of the event you're tracking. This must be whitelisted in the Ours dashboard.

# paths./track.post.requestBody.content.application/json.schema.properties.token.description
The token for your Source. You can find this in the dashboard.

# paths./track.post.requestBody.content.application/json.schema.properties.userId.description
The Ours Visitor ID stored in local storage and cookies on your web properties. When present, this is used directly — no lookup by externalId or email 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.

# paths./track.post.requestBody.content.application/json.schema.properties.externalId.description
Your system's unique identifier for this user. We search your account for an existing visitor with this externalId and attach the event to them (resolving to their Ours Visitor ID). If no match is found, a new visitor is created. When present, email lookup is skipped. If you also have the userId from cookies or local storage, send both — it removes the lookup round-trip.

# paths./track.post.requestBody.content.application/json.schema.properties.email.description
The email address of a user. Used as a fallback lookup when neither userId nor externalId is provided. We search your account for a visitor with this email and attach the event to them. If no match is found, a new visitor is created.

# paths./track.post.requestBody.content.application/json.schema.properties.time.description
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.

# paths./track.post.requestBody.content.application/json.schema.properties.distinctId.description
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).

# paths./track.post.requestBody.content.application/json.schema.properties.eventProperties.description
Any additional event properties you want to pass along.

# paths./track.post.requestBody.content.application/json.schema.properties.userProperties.description
Properties to set on the visitor. (optional) You can also update these properties via the identify endpoint.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.is_bot.description
Whether we have detected that the user is a bot. This is set automatically by the Ours server primarily for events tracked through the web SDK.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.ad_id.description
The ad id for detected in the session. This is set by the web sdk automatically.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.adset_id.description
The adset id for detected in the session. This is set by the web sdk automatically.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.campaign_id.description
The campaign id for detected in the session. This is set by the web sdk automatically.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.alart.description
The AppLovin alart query parameter. Ex: alart123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.aleid.description
The AppLovin aleid query parameter. Ex: aleid123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.axwrt.description
The AppLovin pixel cookie value (_axwrt). Web-only.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.device_type.description
The type of device the user is using. Ex: mobile

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.engine_name.description
The name of the browser engine. Ex: Blink

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.engine_version.description
The version of the browser engine. Ex: 114.0

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.os_name.description
The name of the operating system. Ex: Windows

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.os_version.description
The version of the operating system. Ex: 10.0

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.current_url.description
The full url (including query params) of the current page

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.webview.description
Whether the user is in a webview. Ex: true

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.iframe.description
Whether the user is in an iframe. Ex: true

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.sessionCount.description
The number of sessions the user has had. Ex: 3

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.activeDuration.description
The active time in milliseconds that the user had this tab active

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.duration.description
The time in milliseconds since the page was loaded // script was loaded

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.sacid.description
The StackAdapt Tracking ID. Ex: sacid123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.basis_cid.description
The Basis DSP Click ID. Ex: basis_cid123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.ob_click_id.description
The Outbrain click ID, captured from the `ob_click_id` URL parameter (Outbrain `{{ob_click_id}}` macro) on the landing page. Ex: ob_click_abc123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.beeswax_auction_id.description
The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.admitad_uid.description
The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties._ef_transaction_id.description
The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.viant_click_id.description
The Viant (Adelphic) Click ID, captured from the `viant_click_id` URL parameter (Viant `${ADELPHIC_CLICKID}` macro). Sent as `xid` on Viant postbacks. Ex: viant_click_abc123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.viant_impression_id.description
The Viant (Adelphic) Impression ID, captured from the `viant_impression_id` URL parameter (Viant `${ADELPHIC_IMPRESSIONID}` macro). Sent as `imp_id` on Viant postbacks for post-view attribution. Ex: viant_imp_abc123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.fbc.description
Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.fbclid.description
Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.fbp.description
Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.oppref.description
The OpenAI Ads privacy-preserving reference, captured from the `oppref` URL parameter on landing pages (the OpenAI Pixel also stores it in a `__oppref` cookie). Sent to OpenAI Ads on Conversions API events for attribution. Ex: oppref_abc

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.host.description
The host of the current page. Ex: example.com

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.ip.description
The IP address of the user. Ex: 127.0.0.1

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.pathname.description
The pathname of the current page. Ex: /home

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.referring_domain.description
The referring domain of the current page

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_campaign.description
The UTM Campaign. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_content.description
The UTM Content. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_medium.description
The UTM Medium. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_name.description
The UTM Name. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.im_ref.description
The Impact Click ID reference. Ex: im_ref123

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_source.description
The UTM Source. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_term.description
The UTM Term. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.version.description
The SDK version (e.g., web SDK or ingest-sdk-* via Stainless headers)

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.wbraid.description
The WBRAID Identifier. The web SDK automatically captures this from the query params.

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.page_hash.description
A random set of numbers for the page load

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.sid.description
The session ID as assigned automatically by the web SDK. This is required for session replay

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.received_at.description
The time the event was received by an Ours server in ISO format

# paths./track.post.requestBody.content.application/json.schema.properties.defaultProperties.description
These properties are used throughout the Ours app to pass known values onto destinations

# paths./track.post.requestBody.content.application/json.schema.properties.identityContext.properties.ip.description
The end-user IP address (not the server IP).

# paths./track.post.requestBody.content.application/json.schema.properties.identityContext.properties.userAgent.description
The end-user User-Agent string (not the server UA).

# paths./track.post.requestBody.content.application/json.schema.properties.identityContext.description
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.

# paths./track.post.responses.200.description
Success - your event was sent to our servers

# paths./track.post.responses.400.description
Bad Request - Something about the body of your request is invalid. Please update your payload and try again.

# paths./track.post.responses.401.description
Unauthorized - you are not authorized to send events to Ours. Please contact support.

# paths./batch.post.description
Send multiple `/track`-shaped events in a single request. This endpoint is intended for replay, backfill, and asynchronous bulk delivery. The top-level token is authorized once for the full batch. Each batch row must include `distinctId`, and mixed validation or queue outcomes are reported per row.

# paths./batch.post.requestBody.description
A token plus an array of `/track`-compatible events.

# paths./batch.post.requestBody.content.application/json.schema.properties.token.description
The token for your Source. You can find this in the dashboard.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.event.description
The name of the event you're tracking. This must be whitelisted in the Ours dashboard.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.userId.description
The Ours Visitor ID stored in local storage and cookies on your web properties. When present, this is used directly — no lookup by externalId or email 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.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.externalId.description
Your system's unique identifier for this user. We search your account for an existing visitor with this externalId and attach the event to them (resolving to their Ours Visitor ID). If no match is found, a new visitor is created. When present, email lookup is skipped. If you also have the userId from cookies or local storage, send both — it removes the lookup round-trip.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.email.description
The email address of a user. Used as a fallback lookup when neither userId nor externalId is provided. We search your account for a visitor with this email and attach the event to them. If no match is found, a new visitor is created.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.time.description
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.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.eventProperties.description
Any additional event properties you want to pass along.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.userProperties.description
Properties to set on the visitor. (optional) You can also update these properties via the identify endpoint.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.is_bot.description
Whether we have detected that the user is a bot. This is set automatically by the Ours server primarily for events tracked through the web SDK.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.ad_id.description
The ad id for detected in the session. This is set by the web sdk automatically.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.adset_id.description
The adset id for detected in the session. This is set by the web sdk automatically.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.campaign_id.description
The campaign id for detected in the session. This is set by the web sdk automatically.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.alart.description
The AppLovin alart query parameter. Ex: alart123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.aleid.description
The AppLovin aleid query parameter. Ex: aleid123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.axwrt.description
The AppLovin pixel cookie value (_axwrt). Web-only.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.device_type.description
The type of device the user is using. Ex: mobile

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.engine_name.description
The name of the browser engine. Ex: Blink

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.engine_version.description
The version of the browser engine. Ex: 114.0

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.os_name.description
The name of the operating system. Ex: Windows

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.os_version.description
The version of the operating system. Ex: 10.0

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.current_url.description
The full url (including query params) of the current page

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.webview.description
Whether the user is in a webview. Ex: true

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.iframe.description
Whether the user is in an iframe. Ex: true

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.sessionCount.description
The number of sessions the user has had. Ex: 3

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.activeDuration.description
The active time in milliseconds that the user had this tab active

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.duration.description
The time in milliseconds since the page was loaded // script was loaded

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.sacid.description
The StackAdapt Tracking ID. Ex: sacid123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.basis_cid.description
The Basis DSP Click ID. Ex: basis_cid123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.ob_click_id.description
The Outbrain click ID, captured from the `ob_click_id` URL parameter (Outbrain `{{ob_click_id}}` macro) on the landing page. Ex: ob_click_abc123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.beeswax_auction_id.description
The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.admitad_uid.description
The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties._ef_transaction_id.description
The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.viant_click_id.description
The Viant (Adelphic) Click ID, captured from the `viant_click_id` URL parameter (Viant `${ADELPHIC_CLICKID}` macro). Sent as `xid` on Viant postbacks. Ex: viant_click_abc123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.viant_impression_id.description
The Viant (Adelphic) Impression ID, captured from the `viant_impression_id` URL parameter (Viant `${ADELPHIC_IMPRESSIONID}` macro). Sent as `imp_id` on Viant postbacks for post-view attribution. Ex: viant_imp_abc123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.fbc.description
Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.fbclid.description
Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.fbp.description
Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.oppref.description
The OpenAI Ads privacy-preserving reference, captured from the `oppref` URL parameter on landing pages (the OpenAI Pixel also stores it in a `__oppref` cookie). Sent to OpenAI Ads on Conversions API events for attribution. Ex: oppref_abc

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.host.description
The host of the current page. Ex: example.com

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.ip.description
The IP address of the user. Ex: 127.0.0.1

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.pathname.description
The pathname of the current page. Ex: /home

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.referring_domain.description
The referring domain of the current page

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.utm_campaign.description
The UTM Campaign. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.utm_content.description
The UTM Content. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.utm_medium.description
The UTM Medium. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.utm_name.description
The UTM Name. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.im_ref.description
The Impact Click ID reference. Ex: im_ref123

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.utm_source.description
The UTM Source. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.utm_term.description
The UTM Term. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.version.description
The SDK version (e.g., web SDK or ingest-sdk-* via Stainless headers)

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.wbraid.description
The WBRAID Identifier. The web SDK automatically captures this from the query params.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.page_hash.description
A random set of numbers for the page load

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.sid.description
The session ID as assigned automatically by the web SDK. This is required for session replay

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.properties.received_at.description
The time the event was received by an Ours server in ISO format

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.defaultProperties.description
These properties are used throughout the Ours app to pass known values onto destinations

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.identityContext.properties.ip.description
The end-user IP address (not the server IP).

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.identityContext.properties.userAgent.description
The end-user User-Agent string (not the server UA).

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.identityContext.description
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.

# paths./batch.post.requestBody.content.application/json.schema.properties.events.items.properties.distinctId.description
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).

# paths./batch.post.requestBody.content.application/json.schema.properties.events.description
A list of `/track`-shaped events to validate and enqueue together.

# paths./batch.post.responses.200.description
Every event in the batch was accepted onto the ingest queue.

# paths./batch.post.responses.207.description
At least one row was accepted and at least one row failed validation or queue transport. Correct and resubmit `invalid_event` rows. Retry only `queue_failed` rows with the same `distinctId` values.

# paths./batch.post.responses.400.description
Invalid JSON, missing `token`, missing or empty `events`, token mismatch, invalid gzip body, or every row failed validation.

# paths./batch.post.responses.401.description
The top-level token is invalid or is not allowed for the public HTTP API.

# paths./batch.post.responses.413.description
The request exceeded the configured body, batch-count, or per-event size limit.

# paths./batch.post.responses.415.description
The request used an unsupported content type or content encoding.

# paths./batch.post.responses.500.description
A transient source lookup failed or every accepted row failed queue transport. Retry the failed rows with the same `distinctId` values.

# paths./identify.post.description
Set or update properties on an existing visitor, or create a new visitor if no match is found. This fires a $identify event, making the call visible in the event stream. Identity resolution runs in priority order: userId (direct, no lookup) → externalId (lookup by your ID) → email (fallback lookup). When a visitor is found, their Ours Visitor ID is used going forward so all future events are attached to the same profile. 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.

# paths./identify.post.requestBody.content.application/json.schema.properties.token.description
The token for your Source. You can find this in the dashboard.

# paths./identify.post.requestBody.content.application/json.schema.properties.userId.description
The Ours Visitor ID stored in local storage and cookies on your web properties. When present, this is used directly — no lookup by externalId or email 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.

# paths./identify.post.requestBody.content.application/json.schema.properties.externalId.description
Your system's unique identifier for this user. We search your account for an existing visitor with this externalId and attach the event to them (resolving to their Ours Visitor ID). If no match is found, a new visitor is created. When present, email lookup is skipped. If you also have the userId from cookies or local storage, send both — it removes the lookup round-trip.

# paths./identify.post.requestBody.content.application/json.schema.properties.email.description
The email address of a user. Used as a fallback lookup when neither userId nor externalId is provided. We search your account for a visitor with this email and attach the event to them. If no match is found, a new visitor is created.

# paths./identify.post.requestBody.content.application/json.schema.properties.userProperties.description
User properties to associate with this user. The existing user properties will be updated. And all future events will have these properties associated with them.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.is_bot.description
Whether we have detected that the user is a bot. This is set automatically by the Ours server primarily for events tracked through the web SDK.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.ad_id.description
The ad id for detected in the session. This is set by the web sdk automatically.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.adset_id.description
The adset id for detected in the session. This is set by the web sdk automatically.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.campaign_id.description
The campaign id for detected in the session. This is set by the web sdk automatically.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.alart.description
The AppLovin alart query parameter. Ex: alart123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.aleid.description
The AppLovin aleid query parameter. Ex: aleid123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.axwrt.description
The AppLovin pixel cookie value (_axwrt). Web-only.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.device_type.description
The type of device the user is using. Ex: mobile

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.engine_name.description
The name of the browser engine. Ex: Blink

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.engine_version.description
The version of the browser engine. Ex: 114.0

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.os_name.description
The name of the operating system. Ex: Windows

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.os_version.description
The version of the operating system. Ex: 10.0

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.current_url.description
The full url (including query params) of the current page

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.webview.description
Whether the user is in a webview. Ex: true

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.iframe.description
Whether the user is in an iframe. Ex: true

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.sessionCount.description
The number of sessions the user has had. Ex: 3

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.activeDuration.description
The active time in milliseconds that the user had this tab active

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.duration.description
The time in milliseconds since the page was loaded // script was loaded

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.sacid.description
The StackAdapt Tracking ID. Ex: sacid123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.basis_cid.description
The Basis DSP Click ID. Ex: basis_cid123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.ob_click_id.description
The Outbrain click ID, captured from the `ob_click_id` URL parameter (Outbrain `{{ob_click_id}}` macro) on the landing page. Ex: ob_click_abc123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.beeswax_auction_id.description
The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.admitad_uid.description
The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties._ef_transaction_id.description
The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.viant_click_id.description
The Viant (Adelphic) Click ID, captured from the `viant_click_id` URL parameter (Viant `${ADELPHIC_CLICKID}` macro). Sent as `xid` on Viant postbacks. Ex: viant_click_abc123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.viant_impression_id.description
The Viant (Adelphic) Impression ID, captured from the `viant_impression_id` URL parameter (Viant `${ADELPHIC_IMPRESSIONID}` macro). Sent as `imp_id` on Viant postbacks for post-view attribution. Ex: viant_imp_abc123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.fbc.description
Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.fbclid.description
Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.fbp.description
Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.oppref.description
The OpenAI Ads privacy-preserving reference, captured from the `oppref` URL parameter on landing pages (the OpenAI Pixel also stores it in a `__oppref` cookie). Sent to OpenAI Ads on Conversions API events for attribution. Ex: oppref_abc

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.host.description
The host of the current page. Ex: example.com

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.ip.description
The IP address of the user. Ex: 127.0.0.1

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.pathname.description
The pathname of the current page. Ex: /home

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.referring_domain.description
The referring domain of the current page

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_campaign.description
The UTM Campaign. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_content.description
The UTM Content. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_medium.description
The UTM Medium. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_name.description
The UTM Name. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.im_ref.description
The Impact Click ID reference. Ex: im_ref123

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_source.description
The UTM Source. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.utm_term.description
The UTM Term. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.version.description
The SDK version (e.g., web SDK or ingest-sdk-* via Stainless headers)

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.wbraid.description
The WBRAID Identifier. The web SDK automatically captures this from the query params.

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.page_hash.description
A random set of numbers for the page load

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.sid.description
The session ID as assigned automatically by the web SDK. This is required for session replay

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.properties.received_at.description
The time the event was received by an Ours server in ISO format

# paths./identify.post.requestBody.content.application/json.schema.properties.defaultProperties.description
These properties are used throughout the Ours app to pass known values onto destinations

# paths./identify.post.requestBody.content.application/json.schema.properties.identityContext.properties.ip.description
The end-user IP address (not the server IP).

# paths./identify.post.requestBody.content.application/json.schema.properties.identityContext.properties.userAgent.description
The end-user User-Agent string (not the server UA).

# paths./identify.post.requestBody.content.application/json.schema.properties.identityContext.description
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.

# paths./identify.post.responses.200.description
Success - your event was sent to our servers

# paths./identify.post.responses.400.description
Bad Request - Something about the body of your request is invalid. Please update your payload and try again.

# paths./identify.post.responses.401.description
Unauthorized - you are not authorized to send events to Ours. Please contact support.

# paths./experiments/assignments/{experiment_key}.post.description
Return the server-side variant assignment for a visitor in a single A/B or multivariate experiment, identified by its experiment key. Bucketing is deterministic on `visitor_id` and is sticky across calls. Tracking an impression is the default — pass `track_impression: false` to read without recording. The browser SDK and this endpoint converge on the same variant for the same visitor.

# paths./experiments/assignments/{experiment_key}.post.parameters[].schema.description
The experiment's stable key. Surfaced in the dashboard under each experiment's setup tab.

# paths./experiments/assignments/{experiment_key}.post.parameters[].description
The experiment's stable key. Surfaced in the dashboard under each experiment's setup tab.

# paths./experiments/assignments/{experiment_key}.post.requestBody.description
Visitor + optional page context for eligibility.

# paths./experiments/assignments/{experiment_key}.post.requestBody.content.application/json.schema.properties.token.description
The experiment token (`exp_*`) for the experiment settings holding this experiment. Available from the dashboard.

# paths./experiments/assignments/{experiment_key}.post.requestBody.content.application/json.schema.properties.visitor_id.description
Stable identifier for the visitor — typically the Ours visitor id from your browser cookie, or your own server-side user id if you keep the same id consistent across browser and server.

# paths./experiments/assignments/{experiment_key}.post.requestBody.content.application/json.schema.properties.context.properties.url.description
The current page URL. When provided, the experiment's URL patterns are evaluated for eligibility — visitors on non-matching URLs are returned `in_experiment: false`. Omit when the caller is pre-gating the request.

# paths./experiments/assignments/{experiment_key}.post.requestBody.content.application/json.schema.properties.context.properties.search.description
The current query string (e.g. `?utm_source=meta`). When provided, the experiment's query-param conditions are evaluated for eligibility. If omitted, the query string is parsed from `url`.

# paths./experiments/assignments/{experiment_key}.post.requestBody.content.application/json.schema.properties.context.description
Optional page context for URL + query-param eligibility. Variant bucketing is deterministic on `visitor_id` regardless of context.

# paths./experiments/assignments/{experiment_key}.post.requestBody.content.application/json.schema.properties.track_impression.description
When true (default), an `$experiment_impression` event is enqueued and the visitor's `experiment_assignments` map is updated. Set to false to read the assignment without recording an impression — useful for in-test diagnostics.

# paths./experiments/assignments/{experiment_key}.post.responses.200.description
The assignment outcome — including out-of-experiment results.

# paths./experiments/assignments/{experiment_key}.post.responses.200.content.application/json.schema.anyOf[].properties.redirect.description
Redirect destination for redirect (split-URL) variants — a same-domain relative path or an absolute https:// URL. Present only when the assigned variant is a redirect; absent for on-page (DOM-modification) variants. Read it straight off the payload and issue the redirect server-side.

# paths./experiments/assignments/{experiment_key}.post.responses.400.description
Bad Request - Something about the body of your request is invalid. Please update your payload and try again.

# paths./experiments/assignments/{experiment_key}.post.responses.401.description
Unauthorized - you are not authorized to send events to Ours. Please contact support.

# paths./experiments/assignments/{experiment_key}.post.responses.404.description
The experiment key is unknown or not currently running.

# paths./experiments/personalization.post.description
Return the active personalization assignments for a visitor. Read-only and never records an impression. Personalizations are populated by the event-driven rule engine — until that ships, this endpoint returns an empty list for every visitor, which is the correct fail-closed behavior (no false positives).

# paths./experiments/personalization.post.responses.200.description
The visitor's active personalization assignments (possibly empty).

# paths./experiments/personalization.post.responses.400.description
Bad Request - Something about the body of your request is invalid. Please update your payload and try again.

# paths./experiments/personalization.post.responses.401.description
Unauthorized - you are not authorized to send events to Ours. Please contact support.