# Identify Visitors

Source: https://docs.oursprivacy.com/docs/reference/identify

Define visitor properties on an existing visitor or create a new visitor. This fires a $identify event, making the call visible in the event stream. 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](https://docs.oursprivacy.com/docs/data-types) for details and common pitfalls.

## POST /identify

Identify Visitors

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: visitorId (direct, no lookup) → externalId → email → userProperties.phone_number. Each lookup runs only if earlier identifiers did not resolve a visitor. Phone matching ignores common formatting and an international + or 00 prefix, but does not infer a country code. 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 URL: `POST https://api.oursprivacy.com/api/v1/identify`

### Request body (`application/json`, required)

The payload to identify a visitor The schema describes canonical JSON inputs. The server also accepts values normalized by the preprocessing described on individual fields.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Yes | The token for your Source. You can find this in the dashboard. Leading and trailing whitespace is removed before validation. |
| `visitorId` | string \| null | No | 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 visitorId and an externalId, send both so the event is attached to the right visitor without any lookup overhead. visitorId takes precedence over the deprecated userId alias. Leading and trailing whitespace is removed before validation. |
| `userId` | string \| null | No | 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 visitorId and an externalId, send both so the event is attached to the right visitor without any lookup overhead. visitorId takes precedence over the deprecated userId alias. Leading and trailing whitespace is removed before validation. |
| `externalId` | string \| null | No | Your system's unique identifier for this user. When visitorId 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 visitorId 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. |
| `email` | string \| null | No | The email address of a user. When visitorId 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. |
| `userProperties` | object | Yes | 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. |
| `userProperties.email` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.first_name` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.last_name` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.gender` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.date_of_birth` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.phone_number` | string \| null \| number \| boolean \| JsonValue[] \| object | No |  |
| `userProperties.city` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.state` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.zip` | string \| null \| number \| boolean \| JsonValue[] \| object | No |  |
| `userProperties.country` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.external_id` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `userProperties.company_name` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.job_title` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.ip` | string \| null | No | The IP address of the user Leading and trailing whitespace is removed before validation. |
| `userProperties.custom_properties` | object \| null | No | 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. |
| `userProperties.consent` | object \| null | No | 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. |
| `userProperties.ad_id` | string \| null | No |  |
| `userProperties.adset_id` | string \| null | No |  |
| `userProperties.campaign_id` | string \| null | No |  |
| `userProperties.alart` | string \| null | No |  |
| `userProperties.aleid` | string \| null | No |  |
| `userProperties.axwrt` | string \| null | No |  |
| `userProperties.affiliatly_v3` | string \| null | No |  |
| `userProperties.fbc` | string \| null | No |  |
| `userProperties.fbp` | string \| null | No |  |
| `userProperties.fbclid` | string \| null | No |  |
| `userProperties.gad_source` | string \| null | No |  |
| `userProperties.gbraid` | string \| null | No |  |
| `userProperties.gclid` | string \| null | No |  |
| `userProperties.ndclid` | string \| null | No |  |
| `userProperties.oppref` | string \| null | No |  |
| `userProperties.dclid` | string \| null | No |  |
| `userProperties.qclid` | string \| null | No |  |
| `userProperties.msclkid` | string \| null | No |  |
| `userProperties.ttclid` | string \| null | No |  |
| `userProperties.twclid` | string \| null | No |  |
| `userProperties.clickid` | string \| null | No |  |
| `userProperties.sccid` | string \| null | No |  |
| `userProperties.irclickid` | string \| null | No |  |
| `userProperties.im_ref` | string \| null | No |  |
| `userProperties.clid` | string \| null | No |  |
| `userProperties.sid` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.li_fat_id` | string \| null | No |  |
| `userProperties.referrer` | string \| null | No |  |
| `userProperties.referring_domain` | string \| null | No |  |
| `userProperties.user_agent` | string \| null | No |  |
| `userProperties.user_agent_full_list` | string \| null | No |  |
| `userProperties.utm_campaign` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.utm_content` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.utm_medium` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.utm_name` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.utm_source` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.utm_term` | string \| null | No | Non-string input is converted to text before validation; clients should send a string. |
| `userProperties.wbraid` | string \| null | No |  |
| `userProperties.rdt_cid` | string \| null | No |  |
| `userProperties.is_bot` | string \| null \| number \| boolean \| JsonValue[] \| object | No |  |
| `userProperties.epik` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.sacid` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.ylpcid` | string \| null | No |  |
| `userProperties.adct` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.basis_cid` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.ob_click_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.grclid` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.graid` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.beeswax_auction_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.admitad_uid` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties._ef_transaction_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.viant_click_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.ttd_impression_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.viant_impression_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.katalys_transaction_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.katalys_offer_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.katalys_publisher_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `userProperties.gc_ref_id` | string \| null | No | Leading and trailing whitespace is removed before validation. |
| `defaultProperties` | object \| null | No | These properties are used throughout the Ours app to pass known values onto destinations |
| `defaultProperties.is_bot` | string \| null \| number \| boolean \| JsonValue[] \| object | No | 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. |
| `defaultProperties.ad_id` | string \| null | No | The ad id detected in the session. This is set by the web sdk automatically. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.adset_id` | string \| null | No | The adset id detected in the session. This is set by the web sdk automatically. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.campaign_id` | string \| null | No | The campaign id detected in the session. This is set by the web sdk automatically. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ours_ad` | string \| null | No | The Ours ad tag from the ours_ad query parameter, as platform.campaign.adset.ad. Ex: meta.120210.120211.120212 Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ad_touch_platform` | string \| null | No | The ad platform resolved by the Ours server from the ad tag, ad ids, and click ids on this event. Ex: meta, google Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ad_touch_campaign_id` | string \| null | No | The platform campaign id resolved by the Ours server for this event. Ex: 120210 Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ad_touch_adset_id` | string \| null | No | The platform ad set or ad group id resolved by the Ours server for this event. Ex: 120211 Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ad_touch_ad_id` | string \| null | No | The platform ad id resolved by the Ours server for this event. Ex: 120212 Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ad_touch_source` | string \| null | No | Which signal the Ours server used to resolve the ad touch: ours_ad, url_ids, gad_campaignid, utm_id, or click_id. Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.alart` | string \| null | No | The AppLovin alart query parameter. Ex: alart123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.aleid` | string \| null | No | The AppLovin aleid query parameter. Ex: aleid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.axwrt` | string \| null | No | The AppLovin pixel cookie value (_axwrt). Web-only. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.affiliatly_v3` | string \| null | No | The raw Affiliatly tracking cookie value (affiliatly_v3), set by the Affiliatly script when a visitor lands from an affiliate link. Web-only. Ex: id_hash=abc&id_user=123&aff_uid=45 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.encoding` | string \| null | No | The browser's encoding. Ex: UTF-8 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.browser_name` | string \| null | No | The name of the browser. Ex: Chrome Leading and trailing whitespace is removed before validation. |
| `defaultProperties.browser_version` | string \| null | No | The version of the browser. Ex: 114.0 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.cpu_architecture` | string \| null | No | The architecture of the CPU. Ex: amd64 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.device_type` | string \| null | No | The type of device the user is using. Ex: mobile Leading and trailing whitespace is removed before validation. |
| `defaultProperties.device_model` | string \| null | No | The model of the device. Ex: iPhone Leading and trailing whitespace is removed before validation. |
| `defaultProperties.device_vendor` | string \| null | No | The vendor of the device. Ex: Apple Leading and trailing whitespace is removed before validation. |
| `defaultProperties.engine_name` | string \| null | No | The name of the browser engine. Ex: Blink Leading and trailing whitespace is removed before validation. |
| `defaultProperties.engine_version` | string \| null | No | The version of the browser engine. Ex: 114.0 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.os_name` | string \| null | No | The name of the operating system. Ex: Windows Leading and trailing whitespace is removed before validation. |
| `defaultProperties.os_version` | string \| null | No | The version of the operating system. Ex: 10.0 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.browser_language` | string \| null | No | The language of the browser, lowercased. Ex: en-us Leading and trailing whitespace is removed before validation. |
| `defaultProperties.current_url` | string \| null | No | The full url (including query params) of the current page Leading and trailing whitespace is removed before validation. |
| `defaultProperties.webview` | boolean \| null | No | Whether the user is in a webview. Ex: true |
| `defaultProperties.iframe` | boolean \| null | No | Whether the user is in an iframe. Ex: true |
| `defaultProperties.sessionCount` | number \| null | No | The number of sessions the user has had. Ex: 3 |
| `defaultProperties.activeDuration` | number \| null | No | The total time in milliseconds this tab has been visible since the page loaded |
| `defaultProperties.duration` | number \| null | No | The time in milliseconds since the previous event on this page, or since the web SDK loaded for the first event. Restarts when a hidden tab becomes visible again. |
| `defaultProperties.epik` | string \| null | No | The Pinterest Click ID. Ex: epik456 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.sacid` | string \| null | No | The StackAdapt Tracking ID. Ex: sacid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ylpcid` | string \| null | No | The Yelp Click ID from the landing URL, sent unchanged and unhashed. |
| `defaultProperties.adct` | string \| null | No | The AdRoll Click ID (adct) from the landing URL. Ex: adct123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.basis_cid` | string \| null | No | The Basis DSP Click ID. Ex: basis_cid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ob_click_id` | string \| null | No | 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 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.grclid` | string \| null | No | The Gravity click ID, captured from the `grclid` URL parameter that Gravity (trygravity.com) appends to ad click-through URLs on the landing page. Ex: grclid-abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.graid` | string \| null | No | The Gravity attribution ID, captured from the `graid` URL parameter on the landing page. Gravity resolves it to the campaign, publisher, and ad IDs server-side. Ex: graid-abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.beeswax_auction_id` | string \| null | No | The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.admitad_uid` | string \| null | No | The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties._ef_transaction_id` | string \| null | No | The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.viant_click_id` | string \| null | No | 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 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ttd_impression_id` | string \| null | No | The Trade Desk impression ID, captured from a configured ttd_impression_id URL parameter using the %%TTD_IMPRESSIONID%% creative macro. Sent as imp on conversions. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.katalys_transaction_id` | string \| null | No | The Katalys click (transaction) ID. The Web SDK stores the `transaction_id` landing-page parameter under this name only when the link also carries `publisher_id`, so another network's `transaction_id` is not captured. Ex: ka_tx_abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.katalys_offer_id` | string \| null | No | The Katalys offer ID. The Web SDK stores the `offer_id` landing-page parameter under this name only when the link also carries `publisher_id`. Ex: 1001 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.katalys_publisher_id` | string \| null | No | The Katalys publisher (affiliate) ID, captured from the `publisher_id` landing-page parameter on Katalys links. Sent to Katalys as `aff_id`. Ex: 2002 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.gc_ref_id` | string \| null | No | The Growth Channel tracking ID, captured from the `gc_ref_id` URL parameter. Advertisers add `?gc_ref_id={TRACKING_ID}` to their Growth Channel landing URLs. Sent as `ref_id` on Growth Channel postbacks. Ex: gc_ref_abc123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.viant_impression_id` | string \| null | No | 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 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.fbc` | string \| null | No | Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.fbclid` | string \| null | No | Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.fbp` | string \| null | No | Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.gad_source` | string \| null | No | The Google Ad Source. Ex: google Leading and trailing whitespace is removed before validation. |
| `defaultProperties.gad_campaignid` | string \| null | No | The Google Ads campaign id that Google auto-tagging appends to ad clicks. Ex: 21780011223 Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.gbraid` | string \| null | No | The Google Braid ID. Ex: gbraid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.gclid` | string \| null | No | The Google Click ID. Ex: gclid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ndclid` | string \| null | No | The NextDoor Click ID. Ex: ndclid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.oppref` | string \| null | No | 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 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.dclid` | string \| null | No | The DoubleClick Click ID. Ex: dclid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.qclid` | string \| null | No | The Quora Click ID. Ex: qclid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.rdt_cid` | string \| null | No | The Reddit Click ID. Ex: rdt_cid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.host` | string \| null | No | The host of the current page. Ex: example.com Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ip` | string \| null | No | The IP address of the user. Ex: 127.0.0.1 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.msclkid` | string \| null | No | The Microsoft Click ID. Ex: msclkid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.li_fat_id` | string \| null | No | The LinkedIn Click ID. Ex: li_fat_id123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.pathname` | string \| null | No | The pathname of the current page. Ex: /home Leading and trailing whitespace is removed before validation. |
| `defaultProperties.referrer` | string \| null | No | The referrer URL of the current page Leading and trailing whitespace is removed before validation. |
| `defaultProperties.referring_domain` | string \| null | No | The referring domain of the current page Leading and trailing whitespace is removed before validation. |
| `defaultProperties.screen_height` | number \| null | No | The height of the screen. Ex: 1080 |
| `defaultProperties.screen_width` | number \| null | No | The width of the screen. Ex: 1920 |
| `defaultProperties.title` | string \| null | No | The title of the current page Leading and trailing whitespace is removed before validation. |
| `defaultProperties.user_agent` | string \| null | No | The user agent of the browser Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_campaign` | string \| null | No | The UTM Campaign. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_content` | string \| null | No | The UTM Content. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_medium` | string \| null | No | The UTM Medium. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_name` | string \| null | No | The UTM Name. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.ttclid` | string \| null | No | The TikTok Click ID. Ex: ttclid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.twclid` | string \| null | No | The Twitter Click ID. Ex: twclid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.clickid` | string \| null | No | The Click ID. Ex: clickid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.clid` | string \| null | No | The Generic Click ID. Ex: clid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.sccid` | string \| null | No | The Snapchat Click ID. Ex: sccid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.irclickid` | string \| null | No | The Impact Click ID. Ex: irclickid123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.im_ref` | string \| null | No | The Impact Click ID reference. Ex: im_ref123 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_source` | string \| null | No | The UTM Source. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_term` | string \| null | No | The UTM Term. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.utm_id` | string \| null | No | The UTM ID. The web SDK automatically captures this from the query params. Non-string input is converted to text before validation; clients should send a string. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.version` | string \| null | No | The SDK version (e.g., web SDK or ingest-sdk-* via generated SDK headers) Leading and trailing whitespace is removed before validation. |
| `defaultProperties.wbraid` | string \| null | No | The WBRAID Identifier. The web SDK automatically captures this from the query params. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.uafvl` | string \| null | No | The browser brands and full versions from User-Agent Client Hints, as brand;version pairs separated by \|. Leading and trailing whitespace is removed before validation. |
| `defaultProperties.page_hash` | number \| null | No | A random set of numbers for the page load |
| `defaultProperties.sid` | string \| null | No | The session ID as assigned automatically by the web SDK. This is required for session replay Leading and trailing whitespace is removed before validation. |
| `defaultProperties.new_s` | boolean \| null | No | Deprecated |
| `defaultProperties.fv` | boolean \| null | No | Deprecated |
| `defaultProperties.sr` | string \| null | No | The screen resolution as width x height in pixels. Ex: 1920x1080 Leading and trailing whitespace is removed before validation. |
| `defaultProperties.received_at` | string \| null | No | The time an Ours server received the event, in ISO 8601 UTC |
| `identityContext` | object \| null | No | Deprecated and ignored. Accepted so existing clients keep working. |
| `identityContext.ip` | string | Yes | The end-user IP address (not the server IP). |
| `identityContext.userAgent` | string | Yes | The end-user User-Agent string (not the server UA). |

### Responses

- `200`: Success - your event was sent to our servers
- `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.

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Yes | One of: `true`. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi.json).
