Map anonymous users to authenticated accounts

Many users interact with your application before they log in. If you record consent during that pre-login session — under a temporary anonymous ID — those records become orphaned once the user authenticates. truConsent’s user mapping endpoint lets you reassign all consent records from an anonymous ID to an authenticated user ID in a single API call, keeping consent history continuous and auditable.

How it works

1. Record consent under an anonymous ID

   Before the user logs in, generate a stable anonymous identifier — a session ID, a UUID stored in a cookie, or a local storage key. Use this ID as the userId when recording consent.

   curl -X POST https://api.truConsent.io/consent/{collection_point_id}/consent \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "userId": "session_abc123",
       "action": "approved",
       "purposes": [
         {
           "id": "a1b2c3d4-0000-0000-0000-000000000001",
           "name": "Analytics",
           "consented": "approved",
           "is_mandatory": false,
           "purpose_type": null
         }
       ]
     }'

   Tip

   Use a stable anonymous ID that persists for the duration of the browsing session — don’t generate a new one on every page load. If the ID changes, consent records will be scattered across multiple IDs and won’t all be captured by the mapping call.

2. Map the anonymous ID to the authenticated user after login

   Once the user successfully authenticates, call POST /consent/map-user with both the anonymous ID and the authenticated user ID. This updates every consent record stored under the anonymous ID to use the authenticated user ID instead.

   curl -X POST https://api.truConsent.io/consent/map-user \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "anonymousId": "session_abc123",
       "authenticatedUserId": "user_456",
       "metadata": {}
     }'

   Field	Type	Required	Description
   anonymousId	string	Yes	The temporary ID used before the user logged in
   authenticatedUserId	string	Yes	The user’s permanent authenticated ID
   metadata	object	No	Any additional context you want to attach to the mapping event

   The response confirms how many records were updated:

   {
     "success": true,
     "mapped_count": 3,
     "anonymous_id": "session_abc123",
     "authenticated_user_id": "user_456",
     "message": "Successfully mapped 3 consent logs"
   }

   If mapped_count is 0, no records existed under the anonymous ID. This is expected if the user did not interact with any consent banners before logging in.

   Note

   Call this endpoint once per login event — right after the user’s session is established. Calling it multiple times for the same pair of IDs is safe but has no additional effect after the first successful mapping.

What happens to the anonymous ID

After a successful mapping, the anonymous ID no longer has any consent records associated with it in truConsent. All records are now attributed to authenticatedUserId. If the same user logs out and back in under the same anonymous ID (for example, if they clear cookies), the anonymous ID will appear empty — the records have moved to the authenticated account.