--- title: "Identify Visitors" method: POST path: "/identify" tags: ["OursPrivacy"] --- # Identify Visitors `POST /identify` 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. ## Request body - object - `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. - `userProperties` object, required — 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. - `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)