From 07a38ea7dc6b385d300c09a231e8e6f087e6dea4 Mon Sep 17 00:00:00 2001
From: Juan Langlois <56458805+jilanglois@users.noreply.github.com>
Date: Tue, 7 Jan 2025 09:53:08 -0300
Subject: [PATCH] feat: add opaqueUserId and placementId fields to auction
 request description (#135)

Document opaque_user_id and placement_id on auction calls
---
 topsort-api-v2.yml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index f40e9e3..a94f2a6 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -408,6 +408,23 @@ components:
         - mobile
       default: desktop
 
+    OpaqueUserID:
+      type: string
+      description:
+        An anonymized unique identifier that maps to the original user ID without revealing the original value and
+        should match the value used for events. The opaque user ID allows correlating user activity, such as Impressions,
+        Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so
+        that Topsort can attribute purchases. If your users are always logged in you may use a hash of your customer ID.
+        If your users may interact with your app or site while logged out we recommend generating a random identifier
+        (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least
+        a year.
+      example: 71303ce0-de89-496d-8270-6434589615e8
+
+    PlacementId:
+      type: integer
+      format: int32
+      description: The marketplace's ID of the placement where the ad will appear.
+
     GeoTargeting:
       type: object
       description: An object describing geographical information associated with this auction.
@@ -446,6 +463,10 @@ components:
           $ref: '#/components/schemas/Products'
         geoTargeting:
           $ref: '#/components/schemas/GeoTargeting'
+        opaqueUserId:
+          $ref: '#/components/schemas/OpaqueUserID'
+        placementId:
+          $ref: '#/components/schemas/PlacementId'
       required:
         - type
         - slots
@@ -498,6 +519,10 @@ components:
           minLength: 1
         products:
           $ref: '#/components/schemas/Products'
+        opaqueUserId:
+          $ref: '#/components/schemas/OpaqueUserID'
+        placementId:
+          $ref: '#/components/schemas/PlacementId'
       required:
         - type
         - slots