--- title: "Track Events" method: POST path: "/track" tags: ["OursPrivacy"] --- # Track Events `POST /track` 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. ## Request body - object - `event` string, required — The name of the event you're tracking. This must be whitelisted in the Ours dashboard. - `token` string, required — The token for your Source. You can find this in the dashboard. - `userId` string, nullable — 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. - `externalId` string, nullable — 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. - `email` string, nullable — 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. - `time` number, nullable — 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` string, nullable — 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). - `eventProperties` object, nullable — Any additional event properties you want to pass along. - `userProperties` object, nullable — Properties to set on the visitor. (optional) You can also update these properties via the identify endpoint. - `email` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `gender` string, nullable - `date_of_birth` string, nullable - `phone_number` string, nullable - `city` string, nullable - `state` string, nullable - `zip` string, nullable - `country` string, nullable - `external_id` string, nullable - `company_name` string, nullable - `job_title` string, nullable - `ip` string, nullable — The IP address of the user - `custom_properties` object, nullable - `consent` object, nullable - `ad_id` string, nullable - `adset_id` string, nullable - `campaign_id` string, nullable - `alart` string, nullable - `aleid` string, nullable - `axwrt` string, nullable - `fbc` string, nullable - `fbp` string, nullable - `fbclid` string, nullable - `gad_source` string, nullable - `gbraid` string, nullable - `gclid` string, nullable - `ndclid` string, nullable - `oppref` string, nullable - `dclid` string, nullable - `qclid` string, nullable - `msclkid` string, nullable - `ttclid` string, nullable - `twclid` string, nullable - `clickid` string, nullable - `sccid` string, nullable - `irclickid` string, nullable - `im_ref` string, nullable - `clid` string, nullable - `sid` string, nullable - `li_fat_id` string, nullable - `referrer` string, nullable - `referring_domain` string, nullable - `user_agent` string, nullable - `user_agent_full_list` string, nullable - `utm_campaign` string, nullable - `utm_content` string, nullable - `utm_medium` string, nullable - `utm_name` string, nullable - `utm_source` string, nullable - `utm_term` string, nullable - `wbraid` string, nullable - `rdt_cid` string, nullable - `is_bot` string, nullable - `epik` string, nullable - `sacid` string, nullable - `basis_cid` string, nullable - `ob_click_id` string, nullable - `beeswax_auction_id` string, nullable - `admitad_uid` string, nullable - `_ef_transaction_id` string, nullable - `viant_click_id` string, nullable - `viant_impression_id` string, nullable - `defaultProperties` object, nullable — These properties are used throughout the Ours app to pass known values onto destinations - `is_bot` string, nullable — 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. - `ad_id` string, nullable — The ad id for detected in the session. This is set by the web sdk automatically. - `adset_id` string, nullable — The adset id for detected in the session. This is set by the web sdk automatically. - `campaign_id` string, nullable — The campaign id for detected in the session. This is set by the web sdk automatically. - `alart` string, nullable — The AppLovin alart query parameter. Ex: alart123 - `aleid` string, nullable — The AppLovin aleid query parameter. Ex: aleid123 - `axwrt` string, nullable — The AppLovin pixel cookie value (_axwrt). Web-only. - `encoding` string, nullable — The browsers encoding. Ex: UTF-8 - `browser_name` string, nullable — The name of the browser. Ex: Chrome - `browser_version` string, nullable — The version of the browser. Ex: 114.0 - `cpu_architecture` string, nullable — The architecture of the CPU. Ex: x64 - `device_type` string, nullable — The type of device the user is using. Ex: mobile - `device_model` string, nullable — The model of the device. Ex: iPhone 13 - `device_vendor` string, nullable — The vendor of the device. Ex: Apple - `engine_name` string, nullable — The name of the browser engine. Ex: Blink - `engine_version` string, nullable — The version of the browser engine. Ex: 114.0 - `os_name` string, nullable — The name of the operating system. Ex: Windows - `os_version` string, nullable — The version of the operating system. Ex: 10.0 - `browser_language` string, nullable — The language of the browser. Ex: en-US - `current_url` string, nullable — The full url (including query params) of the current page - `webview` boolean, nullable — Whether the user is in a webview. Ex: true - `iframe` boolean, nullable — Whether the user is in an iframe. Ex: true - `sessionCount` number, nullable — The number of sessions the user has had. Ex: 3 - `activeDuration` number, nullable — The active time in milliseconds that the user had this tab active - `duration` number, nullable — The time in milliseconds since the page was loaded // script was loaded - `epik` string, nullable — The Pinterest Click ID. Ex: epik456 - `sacid` string, nullable — The StackAdapt Tracking ID. Ex: sacid123 - `basis_cid` string, nullable — The Basis DSP Click ID. Ex: basis_cid123 - `ob_click_id` string, nullable — 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 - `beeswax_auction_id` string, nullable — The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123 - `admitad_uid` string, nullable — The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123 - `_ef_transaction_id` string, nullable — The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123 - `viant_click_id` string, nullable — 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 - `viant_impression_id` string, nullable — 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 - `fbc` string, nullable — Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 - `fbclid` string, nullable — Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 - `fbp` string, nullable — Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397 - `gad_source` string, nullable — The Google Ad Source. Ex: google - `gbraid` string, nullable — The Google Braid ID. Ex: gbraid123 - `gclid` string, nullable — The Google Click ID. Ex: gclid123 - `ndclid` string, nullable — The NextDoor Click ID. Ex: ndclid123 - `oppref` string, nullable — 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 - `dclid` string, nullable — The DoubleClick Click ID. Ex: dclid123 - `qclid` string, nullable — The Quora Click ID. Ex: qclid123 - `rdt_cid` string, nullable — The Reddit Click ID. Ex: rdt_cid123 - `host` string, nullable — The host of the current page. Ex: example.com - `ip` string, nullable — The IP address of the user. Ex: 127.0.0.1 - `msclkid` string, nullable — The Microsoft Click ID. Ex: msclkid123 - `li_fat_id` string, nullable — The LinkedIn Click ID. Ex: li_fat_id123 - `pathname` string, nullable — The pathname of the current page. Ex: /home - `referrer` string, nullable — The referrer URL of the current page - `referring_domain` string, nullable — The referring domain of the current page - `screen_height` number, nullable — The height of the screen. Ex: 1080 - `screen_width` number, nullable — The width of the screen. Ex: 1920 - `title` string, nullable — The title of the current page - `user_agent` string, nullable — The user agent of the browser - `utm_campaign` string, nullable — The UTM Campaign. The web SDK automatically captures this from the query params. - `utm_content` string, nullable — The UTM Content. The web SDK automatically captures this from the query params. - `utm_medium` string, nullable — The UTM Medium. The web SDK automatically captures this from the query params. - `utm_name` string, nullable — The UTM Name. The web SDK automatically captures this from the query params. - `ttclid` string, nullable — The TikTok Click ID. Ex: ttclid123 - `twclid` string, nullable — The Twitter Click ID. Ex: twclid123 - `clickid` string, nullable — The Click ID. Ex: clickid123 - `clid` string, nullable — The Generic Click ID. Ex: clid123 - `sccid` string, nullable — The SnapChat Click ID. Ex: sccid123 - `irclickid` string, nullable — The Impact Click ID. Ex: irclickid123 - `im_ref` string, nullable — The Impact Click ID reference. Ex: im_ref123 - `utm_source` string, nullable — The UTM Source. The web SDK automatically captures this from the query params. - `utm_term` string, nullable — The UTM Term. The web SDK automatically captures this from the query params. - `version` string, nullable — The SDK version (e.g., web SDK or ingest-sdk-* via Stainless headers) - `wbraid` string, nullable — The WBRAID Identifier. The web SDK automatically captures this from the query params. - `uafvl` string, nullable — User agent as a full list of strings. - `page_hash` number, nullable — A random set of numbers for the page load - `sid` string, nullable — The session ID as assigned automatically by the web SDK. This is required for session replay - `new_s` boolean, nullable — Deprecated - `fv` boolean, nullable — Deprecated - `sr` string, nullable - `received_at` string, nullable — The time the event was received by an Ours server in ISO format - `identityContext` object, nullable — 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. - `ip` string, required — The end-user IP address (not the server IP). - `userAgent` string, required — The end-user User-Agent string (not the server UA). ## Response `200` Success - your event was sent to our servers - object - `success` true, required ## Other responses - `400` — Bad Request - Something about the body of your request is invalid. Please update your payload and try again. - `401` — Unauthorized - you are not authorized to send events to Ours. Please contact support. - `500` — Internal Server Error. --- [API](https://skmtc.dev/oursprivacy/apis/ours.md) · [All operations](https://skmtc.dev/oursprivacy/apis/ours/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/oursprivacy/ours/revisions/dc169f9305c2/schema)