Merge pull request #235 from fingerprintjs/sync-openapi-12301

Sync OpenAPI Schema (12301) - Proxy details

Author: ilfa

.changeset/thick-toys-visit.md

@@ -0,0 +1,5 @@
+---
+"fingerprint-pro-server-api-openapi": minor
+---
+
+Add `details` object to the `proxy` signal. This field includes the `type` of the detected proxy (`residential` or `data_center`) and the `lastSeenAt` timestamp of when an IP was last observed to show proxy-like behavior.

schemas/components/schemas/Proxy.yaml

@@ -9,4 +9,6 @@ properties:
     description: |
       IP address was used by a public proxy provider or belonged to a known recent residential proxy
   confidence:
-    $ref: ProxyConfidence.yaml
+    $ref: ProxyConfidence.yaml
+  details:
+    $ref: ProxyDetails.yaml

schemas/components/schemas/ProxyDetails.yaml

@@ -0,0 +1,24 @@
+type: object
+# can be nullable when proxy is not detected
+nullable: true
+additionalProperties: false
+description: Proxy detection details (present if proxy is detected)
+required:
+  - proxyType
+properties:
+  proxyType:
+    type: string
+    enum:
+      - residential
+      - data_center
+    description: |
+      Residential proxies use real user IP addresses to appear as legitimate traffic, 
+      while data center proxies are public proxies hosted in data centers
+  lastSeenAt:
+    type: string
+    format: date-time
+    x-ogen-time-format: 2006-01-02T15:00:00Z
+    description: |
+      ISO 8601 formatted timestamp in UTC with hourly resolution
+      of when this IP was last seen as a proxy when available.
+    

schemas/components/schemas/WebhookProxy.yaml

@@ -6,4 +6,6 @@ properties:
     description: |
       IP address was used by a public proxy provider or belonged to a known recent residential proxy
   confidence:
-    $ref: ProxyConfidence.yaml
+    $ref: ProxyConfidence.yaml
+  details:
+    $ref: ProxyDetails.yaml

schemas/paths/examples/get_event_200.json

@@ -192,8 +192,12 @@
     },
     "proxy": {
       "data": {
-        "result": false,
-        "confidence": "high"
+        "result": true,
+        "confidence": "high",
+        "details": {
+          "proxyType": "residential",
+          "lastSeenAt": "2025-08-12T13:00:00Z"
+        }
       }
     },
     "incognito": {

schemas/paths/examples/get_event_200_with_broken_format.json

@@ -187,8 +187,12 @@
     },
     "proxy": {
       "data": {
-        "result": false,
-        "confidence": "high"
+        "result": true,
+        "confidence": "high",
+        "details": {
+          "proxyType": "residential",
+          "lastSeenAt": "2025-08-12T13:00:00Z"
+        }
       }
     },
     "incognito": {

schemas/paths/examples/get_event_search_200.json

@@ -191,7 +191,11 @@
       "proxy": {
         "data": {
           "result": false,
-          "confidence": "high"
+          "confidence": "high",
+          "details": {
+            "proxyType": "residential",
+            "lastSeenAt": "2025-08-12T13:00:00Z"
+          }
         }
       },
       "incognito": {

schemas/paths/examples/webhook.json

@@ -130,8 +130,12 @@
     }
   },
   "proxy": {
-    "result": false,
-    "confidence": "high"
+    "result": true,
+    "confidence": "high",
+    "details": {
+      "proxyType": "residential",
+      "lastSeenAt": "2025-08-12T13:00:00Z"
+    }
   },
   "tampering": {
     "result": false,