Data API: Anonymous IDs integration

NOTE: This guide covers the Data API. You can still use it to upload all types of anonymous (traditional) IDs, but we recommend the First-Party Data Uploader. For an overview of all upload options, see ID-based first-party data.

Advertisers can upload traditional IDs themselves or use a trusted external provider. This guide helps you determine which data endpoint to use, and provides a sample Python script to get started. For more options, see Getting started with data onboarding.

General requirements

• You should be familiar with our data integration environment and authentication.
• Traditional IDs are first-party data that contain user identifiers. For examples, see supported IDs.
• If you are an advertiser uploading data on behalf of yourself, use the POST /data/advertiser endpoint.
• When you upload data, you can add optional optimizations to your segment, such as base bid or bid factor overrides.

Special requirements

If you are an advertiser in the Medical Health industry category, make sure the audience data you upload complies with the following requirements:

• It must not contain data about individuals in Washington or Nevada.
• It must include only the following data:
  • Consented data: You have affirmative consent from the individual to use and disclose data about their health for advertising purposes.
  • Modeled data: Identifiers are associated with individuals for whom you have no knowledge or evidence suggesting specific health conditions.

Python code sample

To begin your integration, download the sample code in Python, which demonstrates how you can interact with our first-party Data API and accomplish two tasks:

1. Generate the signature required to POST.
2. Structure your users' UID2s in the correct JSON format.

Here's what you need to know about the code sample:

• The code sample is compatible with currently-supported versions of Python (version 3.6 and later) and consists of three sections: Parameters, Functions, and Execution.
• Instead of UID2s, you can specify other types of IDs (TDID, DAID, or RampID) in your input file, however, this code sample will return them labeled as the UID2 property values (line 110 in the code sample).
• You are expected to provide the required parameter values by replacing the variables directly in the code sample in its #PARAMETERS section with no additional modifications to the code sample. If you prefer to use the command line to specify the parameter values, set the useCommandLineArgs value to True and modify the #EXECUTION section of the code sample accordingly.

Parameters

In the #PARAMETERS section of the code sample, the following variables must be defined to execute the script successfully.

The following parameter values are preset but can be changed, if needed. The rest of the preset parameters should not be modified.

Functions

In the #FUNCTIONS section of the code sample, there are two functions that do the following:

1. Generate the TtdSignature required for the POST request.
2. Create a request to POST the JSON payload. This code validates that the request contains no more than the batchSize for each request.
3. Generate errors, if there are any.

After all the data upload is successful, you must use the Platform API to create audiences from it. For details about using your first-party data to create audiences, see Building audiences.

Optional optimization properties

You can include bid factors and base bid values in the upload request.

IMPORTANT: Be aware of the following interactions with other properties in the Platform API.

The following table lists the interactions with other optimizations.

For details on Platform API interactions, see FAQs.

Bid factors

If needed, you can specify bid factors and base bid values for certain data segments in the optional BaseBidCPM and BidFactor properties during the upload.

Here's an example of a POST /data/advertiser request with optional properties.

NOTE: If you are an external data provider, you must also include your DataProviderId in the request.

{
    "AdvertiserId": "ADVERTISER_ID_PLACEHOLDER",
    "Items": [
        {
            "TDID": "123e4567-e89b-12d3-a456-426652340000",
            "Data": [
                {
                    "Name": "1210",
                    "TimestampUtc": "2023-11-11T10:11:30+5000",
                    "TTLInMinutes": 43200,
                    "BidFactor": 1.5,
                    "BaseBidCPM": 5.0
                }
            ]
        }
    ]
}

FAQs

The following is a list of commonly asked questions about segments.

How do I remove a user from a segment?

To remove a user from a segment, set the TTLInMinutes property to 0.

What happens if a user is in two segments with different bid factors?

When a user is in segments with different bid factors, the multiplier uses the highest value.

What is the minimum and maximum bid that can be placed for a segment?

At minimum, a bid must be at least half of the BaseBidCPM.amount value set in the ad group, or the BaseBidCPM property for the segment. The maximum bid for a segment is set in the MaxBidCPM property in the ad group.

How do I default a segment back to ad group settings?

• To disable bid factor changes, you can upload a new segment with the same identifiers and set the BidFactor property to 1.

• To use the BaseBid ad group settings, you must delete the segment with the POST /data/deletion-optout/advertiser endpoint.