advertiser-dataprovider-guide.md

UID2 API Documentation > v1 > Integration Guides > Advertiser/Data Provider Integration Guide

Overview

This guide covers integration steps for organizations that collect user data and push it to DSPs. Data collectors include advertisers, data on-boarders, measurement providers, identity graph providers, third-party data providers, and other organizations who send data to DSPs.

Integration Steps

This section outlines the steps data collectors complete to map PII to UID2 identifiers for audience-building and targeting. PII refers to a user's normalized email address or SHA256-hashed and normalized email address.

1. Retrieve a UID2 for PII using the identity map endpoints.

Step	Endpoint	Instruction
a	GET /identity/map POST /identity/map	Send a request containing PII to the identity mapping endpoints.
b	GET /identity/map POST /identity/map	The returned advertising_id (UID2) can be used to target audiences on relevant DSPs. The response returns a user's UID2 and a salt bucket_id that rotates annually. When a user's UID2 updates, the salt bucket remains the same. See 3 for how to check for salt bucket rotation. We recommend storing a user's UID2 and bucket_id in a mapping table for ease of maintenance. See 4 for guidance on incremental updates.

2. Send UID2 to a DSP to build an audience.

Send the advertising_id (UID2) from 1 to a DSP while building your audiences. Each DSP has a unique integration process for building audiences. Please follow the integration guidance provided by the DSP for sending UID2s to build an audience.

3. Monitor for salt bucket rotations related to your stored UID2s.

Because a UID2 is an identifier for a user at a particular moment in time, a user's UID2 will rotate at least once a year.

We recommend checking salt bucket rotation daily for active users. While salt buckets rotate annually, the date they rotate may change. Checking salt bucket rotation every day ensures your integration has the current UID2s.

Step	Endpoint	Instruction
a	GET /identity/buckets	Send a request to the bucket status endpoint for all salt buckets changed since a given timestamp.
b	GET /identity/buckets	The bucket status endpoint will return a list of bucket_id and last_updated timestamps.
c	GET /identity/map POST /identity/map	Compare the returned bucket_id to the salt buckets of UID2s you've cached. If a UID2's salt bucket rotated, resent the PII to the identity mapping service for a new UID2.
d	GET /identity/map POST /identity/map	Store the returned advertising_id and bucket_id.

4. Use an incremental process to continuously update UID2s.

Continuously update and maintain UID2-based audiences utilizing the preceding steps.

The response from 1 contains mapping information. Cache the mapping between PII (identifier), UID2 (advertising_id), and salt bucket (bucket_id), along with a last updated timestamp.

Using the results of 3, repeat 1 to remap UID2s with rotated salt buckets. Repeat 2 to update the UID2s in audiences.

Frequently Asked Questions

How do I know when to refresh the UID2 due to salt bucket rotation?

Metadata supplied with the UID2 generation request indicates the salt bucket used for generating the UID2. Salt buckets persist and correspond to the underlying PII used to generate a UID2. Use the GET /identity/buckets endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh. This workflow typically applies to data providers.

How often should UIDs be refreshed for incremental updates?

The recommended cadence for updating audiences is daily.

How should I generate the SHA256 of PII for mapping?

The system should follow the email normalization rules and hash without salting. The value needs to be base64-encoded before sending.