oursprivacy-ingest 1.19.0 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5d65392b8fbf4e765f78ac8e7f4e1ed0006e99c3519c4e4b6fe60e041d5c92
-  data.tar.gz: 8c7da5bcf8ff87ba352e7d13b563945bafcff7b6263fc1abfc2e13996c6b2982
+  metadata.gz: 339521757ce7143715d8ba15b4bd6ca9e58b4af951d2093b0b069ee0f28aee31
+  data.tar.gz: 56b08685191af7d24663f35cf4769d5bc1910ef7eabd98b88e6d7340d126d159
 SHA512:
-  metadata.gz: 8a97c7b21f0e6c935bfca56da5a3018cb7c75308819952a97c0e0809185d155f46385fec28ca097bd38db2f0104214d65714cbc72c4ce1432dcacb28fc6cfafe
-  data.tar.gz: 168f6ea5f416348947c5f909a315cd4328d11231cc929478fdeac1dfbdf2c80ee789e2437811ef05c19677e67090a7d0753dbd00545579c324e36c9c6665d247
+  metadata.gz: d5d59c9d1ff7a93201ad6e1afb93ee9f12e008803887d4b7988077ce57c58a2f8c7ffea47839469e57c77f0a81bbafcc68150818da3c37687db6f8118d26b206
+  data.tar.gz: e22017a3346aab0c6b497b93cc3e1da611d2f23134f9367cdbdeb235c30ae610d6b8626d3ad13bcf1f1ecf6fe46287af4962cae46baa3ddfab7190807b080e26

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.20.0 (2026-09-23)
+
+Full Changelog: [v1.19.0...v1.20.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.19.0...v1.20.0)
+
+### Features
+
+* **api:** API update.
 ## 1.19.0 (2026-09-14)
 
 Full Changelog: [v1.18.0...v1.19.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.18.0...v1.19.0)

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "oursprivacy-ingest", "~> 1.19.0"
+gem "oursprivacy-ingest", "~> 1.20.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/oursprivacy_ingest/models/batch_create_params.rb

@@ -55,9 +55,10 @@ module OursprivacyIngest
                  nil?: true
 
         # @!attribute email
-        #   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.
+        #   The email address of a user. When userId is absent and externalId does not
+        #   resolve a visitor, we search your account for a visitor with this email. If no
+        #   match is found, we try userProperties.phone_number before creating a new
+        #   visitor.
         #
         #   @return [String, nil]
         optional :email, String, nil?: true
@@ -72,11 +73,11 @@ module OursprivacyIngest
                  nil?: true
 
         # @!attribute external_id
-        #   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.
+        #   Your system's unique identifier for this user. When userId is absent, we search
+        #   your account for an existing visitor with this externalId. If no match is found,
+        #   we try email and then userProperties.phone_number before creating a new visitor.
+        #   If you also have the userId from cookies or local storage, send both — it
+        #   removes the lookup round-trip.
         #
         #   @return [String, nil]
         optional :external_id, String, api_name: :externalId, nil?: true
@@ -101,9 +102,9 @@ module OursprivacyIngest
 
         # @!attribute user_id
         #   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.
+        #   When present, this is used directly — no lookup by externalId, email, or phone
+        #   is performed. If you have both a userId and an externalId, send both so the
+        #   event is attached to the right visitor without any lookup overhead.
         #
         #   @return [String, nil]
         optional :user_id, String, api_name: :userId, nil?: true
@@ -128,11 +129,11 @@ module OursprivacyIngest
         #
         #   @param default_properties [OursprivacyIngest::Models::BatchCreateParams::Event::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
         #
-        #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
+        #   @param email [String, nil] The email address of a user. When userId is absent and externalId does not resol
         #
         #   @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
         #
-        #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
+        #   @param external_id [String, nil] Your system's unique identifier for this user. When userId is absent, we search
         #
         #   @param identity_context [OursprivacyIngest::Models::BatchCreateParams::Event::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
         #

data/lib/oursprivacy_ingest/models/track_event_params.rb

@@ -40,9 +40,10 @@ module OursprivacyIngest
       optional :distinct_id, String, api_name: :distinctId, nil?: true
 
       # @!attribute email
-      #   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.
+      #   The email address of a user. When userId is absent and externalId does not
+      #   resolve a visitor, we search your account for a visitor with this email. If no
+      #   match is found, we try userProperties.phone_number before creating a new
+      #   visitor.
       #
       #   @return [String, nil]
       optional :email, String, nil?: true
@@ -57,11 +58,11 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute external_id
-      #   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.
+      #   Your system's unique identifier for this user. When userId is absent, we search
+      #   your account for an existing visitor with this externalId. If no match is found,
+      #   we try email and then userProperties.phone_number before creating a new visitor.
+      #   If you also have the userId from cookies or local storage, send both — it
+      #   removes the lookup round-trip.
       #
       #   @return [String, nil]
       optional :external_id, String, api_name: :externalId, nil?: true
@@ -86,9 +87,9 @@ module OursprivacyIngest
 
       # @!attribute user_id
       #   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.
+      #   When present, this is used directly — no lookup by externalId, email, or phone
+      #   is performed. If you have both a userId and an externalId, send both so the
+      #   event is attached to the right visitor without any lookup overhead.
       #
       #   @return [String, nil]
       optional :user_id, String, api_name: :userId, nil?: true
@@ -115,11 +116,11 @@ module OursprivacyIngest
       #
       #   @param distinct_id [String, nil] A unique identifier for this event used for deduplication. Highly recommended —
       #
-      #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
+      #   @param email [String, nil] The email address of a user. When userId is absent and externalId does not resol
       #
       #   @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
       #
-      #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
+      #   @param external_id [String, nil] Your system's unique identifier for this user. When userId is absent, we search
       #
       #   @param identity_context [OursprivacyIngest::Models::TrackEventParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #

data/lib/oursprivacy_ingest/models/visitor_upsert_params.rb

@@ -34,19 +34,20 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute email
-      #   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.
+      #   The email address of a user. When userId is absent and externalId does not
+      #   resolve a visitor, we search your account for a visitor with this email. If no
+      #   match is found, we try userProperties.phone_number before creating a new
+      #   visitor.
       #
       #   @return [String, nil]
       optional :email, String, nil?: true
 
       # @!attribute external_id
-      #   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.
+      #   Your system's unique identifier for this user. When userId is absent, we search
+      #   your account for an existing visitor with this externalId. If no match is found,
+      #   we try email and then userProperties.phone_number before creating a new visitor.
+      #   If you also have the userId from cookies or local storage, send both — it
+      #   removes the lookup round-trip.
       #
       #   @return [String, nil]
       optional :external_id, String, api_name: :externalId, nil?: true
@@ -64,9 +65,9 @@ module OursprivacyIngest
 
       # @!attribute user_id
       #   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.
+      #   When present, this is used directly — no lookup by externalId, email, or phone
+      #   is performed. If you have both a userId and an externalId, send both so the
+      #   event is attached to the right visitor without any lookup overhead.
       #
       #   @return [String, nil]
       optional :user_id, String, api_name: :userId, nil?: true
@@ -81,9 +82,9 @@ module OursprivacyIngest
       #
       #   @param default_properties [OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
+      #   @param email [String, nil] The email address of a user. When userId is absent and externalId does not resol
       #
-      #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
+      #   @param external_id [String, nil] Your system's unique identifier for this user. When userId is absent, we search
       #
       #   @param identity_context [OursprivacyIngest::Models::VisitorUpsertParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #

data/lib/oursprivacy_ingest/resources/track.rb

@@ -6,15 +6,18 @@ module OursprivacyIngest
       # Some parameter documentations has been truncated, see
       # {OursprivacyIngest::Models::TrackEventParams} for more details.
       #
-      # 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.
+      # Track events from your server. Include userId, externalId, email, or
+      # userProperties.phone_number to associate the event with an existing visitor.
+      # Identity resolution runs in priority order: userId (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. 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.
       #
       # @overload event(token:, event:, default_properties: nil, distinct_id: nil, email: nil, event_properties: nil, external_id: nil, identity_context: nil, time: nil, user_id: nil, user_properties: nil, request_options: {})
       #
@@ -26,11 +29,11 @@ module OursprivacyIngest
       #
       # @param distinct_id [String, nil] A unique identifier for this event used for deduplication. Highly recommended —
       #
-      # @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
+      # @param email [String, nil] The email address of a user. When userId is absent and externalId does not resol
       #
       # @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
       #
-      # @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
+      # @param external_id [String, nil] Your system's unique identifier for this user. When userId is absent, we search
       #
       # @param identity_context [OursprivacyIngest::Models::TrackEventParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #

data/lib/oursprivacy_ingest/resources/visitor.rb

@@ -9,13 +9,16 @@ module OursprivacyIngest
       # 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.
+      # 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.
       #
       # @overload upsert(token:, user_properties:, default_properties: nil, email: nil, external_id: nil, identity_context: nil, user_id: nil, request_options: {})
       #
@@ -25,9 +28,9 @@ module OursprivacyIngest
       #
       # @param default_properties [OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      # @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
+      # @param email [String, nil] The email address of a user. When userId is absent and externalId does not resol
       #
-      # @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
+      # @param external_id [String, nil] Your system's unique identifier for this user. When userId is absent, we search
       #
       # @param identity_context [OursprivacyIngest::Models::VisitorUpsertParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #

data/lib/oursprivacy_ingest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OursprivacyIngest
-  VERSION = "1.19.0"
+  VERSION = "1.20.0"
 end

data/rbi/oursprivacy_ingest/models/batch_create_params.rbi

@@ -92,9 +92,10 @@ module OursprivacyIngest
         end
         attr_writer :default_properties
 
-        # 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.
+        # The email address of a user. When userId is absent and externalId does not
+        # resolve a visitor, we search your account for a visitor with this email. If no
+        # match is found, we try userProperties.phone_number before creating a new
+        # visitor.
         sig { returns(T.nilable(String)) }
         attr_accessor :email
 
@@ -102,11 +103,11 @@ module OursprivacyIngest
         sig { returns(T.nilable(T::Hash[Symbol, T.nilable(String)])) }
         attr_accessor :event_properties
 
-        # 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.
+        # Your system's unique identifier for this user. When userId is absent, we search
+        # your account for an existing visitor with this externalId. If no match is found,
+        # we try email and then userProperties.phone_number before creating a new visitor.
+        # If you also have the userId from cookies or local storage, send both — it
+        # removes the lookup round-trip.
         sig { returns(T.nilable(String)) }
         attr_accessor :external_id
 
@@ -138,9 +139,9 @@ module OursprivacyIngest
         attr_accessor :time
 
         # 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.
+        # When present, this is used directly — no lookup by externalId, email, or phone
+        # is performed. If you have both a userId and an externalId, send both so the
+        # event is attached to the right visitor without any lookup overhead.
         sig { returns(T.nilable(String)) }
         attr_accessor :user_id
 
@@ -200,17 +201,18 @@ module OursprivacyIngest
           # These properties are used throughout the Ours app to pass known values onto
           # destinations
           default_properties: nil,
-          # 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.
+          # The email address of a user. When userId is absent and externalId does not
+          # resolve a visitor, we search your account for a visitor with this email. If no
+          # match is found, we try userProperties.phone_number before creating a new
+          # visitor.
           email: nil,
           # Any additional event properties you want to pass along.
           event_properties: nil,
-          # 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.
+          # Your system's unique identifier for this user. When userId is absent, we search
+          # your account for an existing visitor with this externalId. If no match is found,
+          # we try email and then userProperties.phone_number before creating a new visitor.
+          # If you also have the userId from cookies or local storage, send both — it
+          # removes the lookup round-trip.
           external_id: nil,
           # 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
@@ -220,9 +222,9 @@ module OursprivacyIngest
           # must be in the past and within the last 7 days.
           time: nil,
           # 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.
+          # When present, this is used directly — no lookup by externalId, email, or phone
+          # is performed. If you have both a userId and an externalId, send both so the
+          # event is attached to the right visitor without any lookup overhead.
           user_id: nil,
           # Properties to set on the visitor. (optional) You can also update these
           # properties via the identify endpoint.

data/rbi/oursprivacy_ingest/models/track_event_params.rbi

@@ -49,9 +49,10 @@ module OursprivacyIngest
       sig { returns(T.nilable(String)) }
       attr_accessor :distinct_id
 
-      # 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.
+      # The email address of a user. When userId is absent and externalId does not
+      # resolve a visitor, we search your account for a visitor with this email. If no
+      # match is found, we try userProperties.phone_number before creating a new
+      # visitor.
       sig { returns(T.nilable(String)) }
       attr_accessor :email
 
@@ -59,11 +60,11 @@ module OursprivacyIngest
       sig { returns(T.nilable(T::Hash[Symbol, T.nilable(String)])) }
       attr_accessor :event_properties
 
-      # 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.
+      # Your system's unique identifier for this user. When userId is absent, we search
+      # your account for an existing visitor with this externalId. If no match is found,
+      # we try email and then userProperties.phone_number before creating a new visitor.
+      # If you also have the userId from cookies or local storage, send both — it
+      # removes the lookup round-trip.
       sig { returns(T.nilable(String)) }
       attr_accessor :external_id
 
@@ -91,9 +92,9 @@ module OursprivacyIngest
       attr_accessor :time
 
       # 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.
+      # When present, this is used directly — no lookup by externalId, email, or phone
+      # is performed. If you have both a userId and an externalId, send both so the
+      # event is attached to the right visitor without any lookup overhead.
       sig { returns(T.nilable(String)) }
       attr_accessor :user_id
 
@@ -153,17 +154,18 @@ module OursprivacyIngest
         # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
         # internal order ID).
         distinct_id: nil,
-        # 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.
+        # The email address of a user. When userId is absent and externalId does not
+        # resolve a visitor, we search your account for a visitor with this email. If no
+        # match is found, we try userProperties.phone_number before creating a new
+        # visitor.
         email: nil,
         # Any additional event properties you want to pass along.
         event_properties: nil,
-        # 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.
+        # Your system's unique identifier for this user. When userId is absent, we search
+        # your account for an existing visitor with this externalId. If no match is found,
+        # we try email and then userProperties.phone_number before creating a new visitor.
+        # If you also have the userId from cookies or local storage, send both — it
+        # removes the lookup round-trip.
         external_id: nil,
         # 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
@@ -173,9 +175,9 @@ module OursprivacyIngest
         # must be in the past and within the last 7 days.
         time: nil,
         # 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.
+        # When present, this is used directly — no lookup by externalId, email, or phone
+        # is performed. If you have both a userId and an externalId, send both so the
+        # event is attached to the right visitor without any lookup overhead.
         user_id: nil,
         # Properties to set on the visitor. (optional) You can also update these
         # properties via the identify endpoint.

data/rbi/oursprivacy_ingest/models/visitor_upsert_params.rbi

@@ -51,17 +51,18 @@ module OursprivacyIngest
       end
       attr_writer :default_properties
 
-      # 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.
+      # The email address of a user. When userId is absent and externalId does not
+      # resolve a visitor, we search your account for a visitor with this email. If no
+      # match is found, we try userProperties.phone_number before creating a new
+      # visitor.
       sig { returns(T.nilable(String)) }
       attr_accessor :email
 
-      # 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.
+      # Your system's unique identifier for this user. When userId is absent, we search
+      # your account for an existing visitor with this externalId. If no match is found,
+      # we try email and then userProperties.phone_number before creating a new visitor.
+      # If you also have the userId from cookies or local storage, send both — it
+      # removes the lookup round-trip.
       sig { returns(T.nilable(String)) }
       attr_accessor :external_id
 
@@ -86,9 +87,9 @@ module OursprivacyIngest
       attr_writer :identity_context
 
       # 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.
+      # When present, this is used directly — no lookup by externalId, email, or phone
+      # is performed. If you have both a userId and an externalId, send both so the
+      # event is attached to the right visitor without any lookup overhead.
       sig { returns(T.nilable(String)) }
       attr_accessor :user_id
 
@@ -121,24 +122,25 @@ module OursprivacyIngest
         # These properties are used throughout the Ours app to pass known values onto
         # destinations
         default_properties: nil,
-        # 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.
+        # The email address of a user. When userId is absent and externalId does not
+        # resolve a visitor, we search your account for a visitor with this email. If no
+        # match is found, we try userProperties.phone_number before creating a new
+        # visitor.
         email: nil,
-        # 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.
+        # Your system's unique identifier for this user. When userId is absent, we search
+        # your account for an existing visitor with this externalId. If no match is found,
+        # we try email and then userProperties.phone_number before creating a new visitor.
+        # If you also have the userId from cookies or local storage, send both — it
+        # removes the lookup round-trip.
         external_id: nil,
         # 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.
         identity_context: nil,
         # 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.
+        # When present, this is used directly — no lookup by externalId, email, or phone
+        # is performed. If you have both a userId and an externalId, send both so the
+        # event is attached to the right visitor without any lookup overhead.
         user_id: nil,
         request_options: {}
       )

data/rbi/oursprivacy_ingest/resources/track.rbi

@@ -3,15 +3,18 @@
 module OursprivacyIngest
   module Resources
     class 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.
+      # Track events from your server. Include userId, externalId, email, or
+      # userProperties.phone_number to associate the event with an existing visitor.
+      # Identity resolution runs in priority order: userId (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. 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.
       sig do
         params(
           token: String,
@@ -51,17 +54,18 @@ module OursprivacyIngest
         # stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
         # internal order ID).
         distinct_id: nil,
-        # 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.
+        # The email address of a user. When userId is absent and externalId does not
+        # resolve a visitor, we search your account for a visitor with this email. If no
+        # match is found, we try userProperties.phone_number before creating a new
+        # visitor.
         email: nil,
         # Any additional event properties you want to pass along.
         event_properties: nil,
-        # 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.
+        # Your system's unique identifier for this user. When userId is absent, we search
+        # your account for an existing visitor with this externalId. If no match is found,
+        # we try email and then userProperties.phone_number before creating a new visitor.
+        # If you also have the userId from cookies or local storage, send both — it
+        # removes the lookup round-trip.
         external_id: nil,
         # 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
@@ -71,9 +75,9 @@ module OursprivacyIngest
         # must be in the past and within the last 7 days.
         time: nil,
         # 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.
+        # When present, this is used directly — no lookup by externalId, email, or phone
+        # is performed. If you have both a userId and an externalId, send both so the
+        # event is attached to the right visitor without any lookup overhead.
         user_id: nil,
         # Properties to set on the visitor. (optional) You can also update these
         # properties via the identify endpoint.

data/rbi/oursprivacy_ingest/resources/visitor.rbi

@@ -6,13 +6,16 @@ module OursprivacyIngest
       # 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.
+      # 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.
       sig do
         params(
           token: String,
@@ -42,24 +45,25 @@ module OursprivacyIngest
         # These properties are used throughout the Ours app to pass known values onto
         # destinations
         default_properties: nil,
-        # 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.
+        # The email address of a user. When userId is absent and externalId does not
+        # resolve a visitor, we search your account for a visitor with this email. If no
+        # match is found, we try userProperties.phone_number before creating a new
+        # visitor.
         email: nil,
-        # 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.
+        # Your system's unique identifier for this user. When userId is absent, we search
+        # your account for an existing visitor with this externalId. If no match is found,
+        # we try email and then userProperties.phone_number before creating a new visitor.
+        # If you also have the userId from cookies or local storage, send both — it
+        # removes the lookup round-trip.
         external_id: nil,
         # 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.
         identity_context: nil,
         # 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.
+        # When present, this is used directly — no lookup by externalId, email, or phone
+        # is performed. If you have both a userId and an externalId, send both so the
+        # event is attached to the right visitor without any lookup overhead.
         user_id: nil,
         request_options: {}
       )

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oursprivacy-ingest
 version: !ruby/object:Gem::Version
-  version: 1.19.0
+  version: 1.20.0
 platform: ruby
 authors:
 - Ours Privacy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi