NEB-4781: Add KYC, geo, and bot-detection structured fields

HISTORY

@@ -1,3 +1,6 @@
+=== 4.7.0 2026-08-27
+- Added support for KYC, geo, and bot-detection structured fields ($nationality, $year_of_birth, $kyc, $geo, $bot_identification) on existing event types
+
 === 4.6.0 2026-02-10
 - Bump the minimum version of httparty to 0.23.3 to ensure protection against CVE-2025-68696
 - Refactor Client to use dedicated internal HTTP clients for different API endpoints

README.md

@@ -87,6 +87,77 @@ response.api_error_message  # Error message associated with status Error Code
 response = client.score(user_id)
 ```
 
+### New KYC Signals, Geo & Bot Detection
+
+```ruby
+# $verification event with KYC outcome
+response = client.track("$verification", {
+  "$user_id"            => "23056",
+  "$verification_type"  => "$kyc",
+  "$status"             => "$success",
+  "$kyc" => {
+    "$names_match"           => true,
+    "$kyc_level"             => "$basic",
+    "$bin_nationality_match" => false,
+    "$provider"              => "lexisnexis"
+  }
+})
+
+# $create_account with account-level identity attributes
+response = client.track("$create_account", {
+  "$user_id"       => "23056",
+  "$nationality"   => "US",
+  "$year_of_birth" => 1985,
+  "$kyc" => {
+    "$names_match"       => true,
+    "$kyc_level"         => "$full",
+    "$provider"          => "prove"
+  },
+  "$geo" => {
+    "$uuid"     => "gc-abc-123",
+    "$provider" => "geocomply"
+  },
+  "$bot_identification" => {
+    "$result"   => "$human",
+    "$provider" => "datadome"
+  }
+})
+
+# $login event with geo and bot-detection signals
+response = client.track("$login", {
+  "$user_id"      => "23056",
+  "$login_status" => "$success",
+  "$geo" => {
+    "$uuid"     => "gc-abc-123",
+    "$provider" => "geocomply"
+  },
+  "$bot_identification" => {
+    "$result"   => "$human",
+    "$provider" => "datadome"
+  }
+})
+
+# $transaction event with KYC, geo, and bot-detection signals
+response = client.track("$transaction", {
+  "$user_id"        => "23056",
+  "$amount"         => 15230000,
+  "$currency_code"  => "USD",
+  "$kyc" => {
+    "$names_match"           => true,
+    "$bin_nationality_match" => true,
+    "$provider"              => "lexisnexis"
+  },
+  "$geo" => {
+    "$uuid"     => "gc-abc-123",
+    "$provider" => "geocomply"
+  },
+  "$bot_identification" => {
+    "$result"   => "$suspected",
+    "$provider" => "human_security"
+  }
+})
+```
+
 ## Decisions
 
 To learn more about the decisions endpoint visit our [developer docs](https://sift.com/developers/docs/ruby/decisions-api/get-decisions).

lib/sift/version.rb

@@ -1,5 +1,5 @@
 module Sift
-  VERSION = "4.6.0"
+  VERSION = "4.7.0"
   API_VERSION = "205"
   VERIFICATION_API_VERSION = "1.1"
 end

spec/unit/client_structured_fields_spec.rb

@@ -0,0 +1,60 @@
+require_relative '../spec_helper'
+require 'sift'
+
+describe Sift::Client do
+
+  before :each do
+    Sift.api_key = nil
+  end
+
+  it "Successfully submits a $create_account event with KYC, geo, and bot-detection structured fields" do
+    response_json = { :status => 0, :error_message => "OK" }
+    stub_request(:post, "https://api.siftscience.com/v205/events").
+      with { |request|
+        parsed_body = JSON.parse(request.body)
+        expect(parsed_body["$nationality"]).to eq("US")
+        expect(parsed_body["$year_of_birth"]).to eq(1985)
+        expect(parsed_body["$kyc"]).to eq({
+          "$names_match" => true,
+          "$kyc_level" => "$basic",
+          "$bin_nationality_match" => true,
+          "$provider" => "lexisnexis"
+        })
+        expect(parsed_body["$geo"]).to eq({
+          "$uuid" => "gc-abc-123",
+          "$provider" => "geocomply"
+        })
+        expect(parsed_body["$bot_identification"]).to eq({
+          "$result" => "$human",
+          "$provider" => "datadome"
+        })
+      }.to_return(:status => 200, :body => MultiJson.dump(response_json), :headers => {})
+
+    api_key = "foobar"
+    properties = {
+      :$type => "$create_account",
+      :$user_id => "23056",
+      :$nationality => "US",
+      :$year_of_birth => 1985,
+      :$kyc => {
+        :$names_match => true,
+        :$kyc_level => "$basic",
+        :$bin_nationality_match => true,
+        :$provider => "lexisnexis"
+      },
+      :$geo => {
+        :$uuid => "gc-abc-123",
+        :$provider => "geocomply"
+      },
+      :$bot_identification => {
+        :$result => "$human",
+        :$provider => "datadome"
+      }
+    }
+
+    response = Sift::Client.new(:api_key => api_key, :version => "205")
+              .track("$create_account", properties)
+    expect(response.ok?).to eq(true)
+    expect(response.api_status).to eq(0)
+  end
+end