Use bid requests to build user profiles

A user profile is a mapping of a user identifier, such as the Google User ID included in BidRequest.user.id, to information about the user that you can use for bidding with interest-based ads or remarketing with user lists.

You may use data from bid requests to build user profiles only when all of the following apply:

The bid request allows personalized ads. In certain regions, you must also confirm that the user has consented to data from the bid request being used to build user profiles.
The publisher has granted you permission to use bid request data for user profiling.
Additional conditions based on the geographic region the user's device is located have been met.

This guide describes how you can determine if a bid request is eligible for use in building a user profile based on publisher permissions and the auction outcome.

Determine if personalized ads are allowed

Check the `non_personalized_ads_reason` field

Non-personalized bid requests aren't eligible for user profiling. Use the BidRequest.ext.privacy_treatments.non_personalized_ads_reason field to confirm whether personalized ads are allowed. If non_personalized_ads_reason is populated, personalized ads aren't allowed.

Use the TC string to check consent for IAB vendors

In regions where GDPR applies, IAB's Transparency and Consent Framework (TCF) is used to communicate which data processing activities are permitted. You can use the Transparency and Consent (TC) string found in the BidRequest.user.consent field to determine which vendor IDs received consent from the user to build user profiles. To learn more about the TC string used in the IAB TCF v2.0 specification, see Transparency and Consent String with Global Vendor & CMP List Formats. Additionally, see Buyer integration with the IAB Europe TCF to learn more about how to integrate with the TCF v2.0 spec in the context of Authorized Buyers.

You must confirm that the user has granted consent for TCF Purpose 3 to relevant vendors in order to build a user profile with data from the bid request. To learn more about TCF Purposes, see IAB's reference for Purposes.

Determine if the publisher granted permission

You must be granted permission by the publisher to use data from a bid request to build user profiles. You can only build user profiles using bid request data if the publisher allows user data collection, and there are no publisher restrictions applying to the required vendor IDs for purpose 3.

Check if the publisher allows user data collection

You can check whether a publisher allows user data collection using the BidRequest.ext.privacy_treatments.allow_user_data_collection field. You may only use data from the bid request for user profiling when the allow_user_data_collection field is set to true.

Check for publisher restrictions using the TC string

You can check whether any publisher restrictions apply to the required vendor IDs by parsing the TC string found in BidRequest.user.consent. View the TC string’s Publisher Restrictions Section to determine whether the publisher restricts purpose 3 for the required vendor IDs. To learn more about publisher restrictions and other data contained in the TC string, see What information is stored in a TC string?

Comply with additional conditions for the region

Additional conditions are dependent on auction outcomes, and are required in a given region for data from the corresponding bid request to be eligible for use in building user profiles. You can find the user's device location using the BidRequest.device.geo field. To learn more about how you can use the BidRequest.device.geo field to determine the user's device location, see the Geographical Targeting guide.

Understand additional conditions for EEA, UK, and Switzerland

Data from bid requests for impressions serving to user devices in the European Economic Area (EEA), the United Kingdom, and Switzerland can only be used to build user profiles if your corresponding bid entered the auction and won.

Understand additional conditions for Non-EEA, UK, or Switzerland regions

Data from bid requests for impressions serving to user devices outside the European Economic Area (EEA), the United Kingdom, and Switzerland can only be used to build user profiles if your corresponding bid meets one of the following conditions:

Your bid entered the auction and won.
Your bid entered the auction and was outbid.
Your bid entered the auction and was filtered because the bid was below the publisher's minimum CPM threshold, or bid floor. The bid floor is not always included in bid requests.

Use real-time feedback to determine auction outcome

You can use real-time feedback to learn about the auction outcome of previously placed bids from incoming bid requests. The following describes relevant fields in the BidFeedback message from the openrtb-adx.proto file:

Field	Description
`request_id`	A unique request ID used to identify the corresponding bid request. This field is set to the same value as the corresponding bid request's `BidRequest.id`field.
`creative_status_code`	A status code used to describe the auction outcome. You can find the possible status codes and their meanings in creative-status-codes.txt

Use win and loss notifications to determine auction outcome

You can use win and loss notifications to learn about the auction outcome of previously placed bids when your win or loss notification URLs are pinged. You can set a win notification URL using the BidResponse.seatbid.bid.nurl field, and a loss notification URL using the BidResponse.seatbid.bid.lurl field.

You can specify macros as the value for query string parameters set for either notification URL for additional information about the auction outcome. These will be replaced with a corresponding value when the specified endpoint is pinged. The following describes relevant macros:

Macro	Description
`${AUCTION_ID}`	A unique request ID used to identify the corresponding bid request. This field is set to the same value as the corresponding bid request's `BidRequest.id` field.
`${CREATIVE_STATUS_CODE}`	A status code used to describe the auction outcome. You can find the possible status codes and their meanings in creative-status-codes.txt

Use the creative status code to comply with additional conditions

Relevant creative status code values for complying with additional conditions include the following:

Creative status code	Description	Compliance details
1	Your bid won the auction.	Conditions are met for all regions.
79	You were outbid.	Conditions are met for non-EEA, UK or CH regions.
80	Your bid was below the bidfloor.	Conditions are met for non-EEA, UK, or CH regions.

You can build user profiles with bid request data only when the corresponding bid response has met the additional conditions for the region that the user's device is located.

Review examples

The following examples step through a sequence of events showing how you can determine whether a bid request is eligible for use in building a user profile. For brevity, the JSON bid request and bid response objects included in these examples only include the fields necessary for determining eligibility.

Find bid request ineligible due to publisher blocking data collection

Your bidding endpoint receives a bid request:

{
  "id": "D3x8RPLO96R6T137tQ6168",
  "device": {
    "geo": {
      "country": "GBR"
    }
  },
  "user": {
    "id": "D17oNZQUJqB4Rt4n4Ec61AC9tee"
  }
}

Conclusion: The bid request doesn't populate BidRequest.ext.privacy_treatments.allow_user_data_collection because it is false. Based on this, we can determine that this bid request is ineligible for use in building a user profile because the publisher permission requirement hasn’t been met.

Find bid request from the UK eligible

The following example uses a win notification to determine that data from a bid request originating from a device in the UK is eligible to use in user profiling for vendor ID 755 and ATP ID 99999:

Your bidding endpoint receives a bid request:

{
  "id": "D3x8RPLO96R6T137tQ6168",
  "imp": [
    {
      "bidfloor": 140.414643547123,
      "bidfloorcur": "JPY"
    }
  ],
  "device": {
    "geo": {
      "country": "GBR"
    }
  },
  "user": {
    "consent": "CQhuOAQQhuOAQB7ACBENCOEIALAAAELAAAwIF5gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgXmAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAA.gF5gAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAg",
    "id": "D17oNZQUJqB4Rt4n4Ec61AC9tee",
    "ext": {
      "consented_providers_settings": {
        "consented_providers": [99999]
      }
    }
  },
  "regs": {
    "ext": {
      "gdpr": 1
    }
  },
  "ext": {
    "privacy_treatments": {
      "allow_user_data_collection": 1
    }
  }
}

You place a bid:

{
  "seatbid": [
    {
      "bid": [
        {
          "price": 149.83914184570312,
          "lurl": "http://example.com/loss?bid_request_id=${AUCTION_ID}&creative_status_code=${CREATIVE_STATUS_CODE}",
          "nurl": "http://example.com/win?bid_request_id=${AUCTION_ID}"
        }
      ]
    }
  ],
  "cur": "JPY"
}

Your bid wins in the auction, causing your win notification URL to be pinged with the expanded value for ${AUCTION_ID}:

http://example.com/win?bid_request_id=D3x8RPLO96R6T137tQ6168
Conclusion: You now know that vendor ID 755 and ATP ID 99999 are eligible to use the bid request with ID "D3x8RPLO96R6T137tQ6168" to build a user profile for Google User ID "D17oNZQUJqB4Rt4n4Ec61AC9tee" in the UK because:
- The bid request indicates the following:
  - The user device is located in a region where IAB TCF is enforced.
  - The TC string indicates:
    - Vendor ID 755 is permitted to build user profiles by the user because the user has consented to purpose 3 for vendor ID 755.
    - There are no publisher restrictions.
  - ATP ID 99999 is also permitted to build user profiles by the user because the ATP ID is included in the consented_providers field.
  - The publisher allows user data collection.
  - The bid request ID is "D3x8RPLO96R6T137tQ6168".
  - The Google User ID is "D17oNZQUJqB4Rt4n4Ec61AC9tee".
  - The user device is located in "GBR".
- Your win notification endpoint is pinged with a query string parameter indicating that the bid request with ID "D3x8RPLO96R6T137tQ6168" has won the auction.
- The user consent, publisher permission, and additional condition requirements for the UK have been met.

Find bid request from the UK ineligible due to auction loss

The following example determines that vendor ID 755 is ineligible to use the bid request for user profiling because the publisher has restricted purpose 3 for vendor ID 755.

Your bidding endpoint receives a bid request:

{
  "id": "D3x8RPLO96R6T137tQ6168",
  "imp": [
    {
      "bidfloor": 140.414643547123,
      "bidfloorcur": "JPY"
    }
  ],
  "device": {
    "geo": {
      "country": "GBR"
    }
  },
  "user": {
    "consent": "CQhuOAQQhuOAQB7ACBENCOEIALAAAELAAAwIF5gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgXmAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAA.gF5gAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAg",
    "id": "D17oNZQUJqB4Rt4n4Ec61AC9tee"
  },
  "regs": {
    "ext": {
      "gdpr": 1
    }
  },
  "ext": {
    "privacy_treatments": {
      "allow_user_data_collection": 1
    }
  }
}

You place a bid:

{
  "seatbid": [
    {
      "bid": [
        {
          "price": 149.83914184570312,
          "lurl": "http://example.com/loss?bid_request_id=${AUCTION_ID}&creative_status_code=${CREATIVE_STATUS_CODE}",
          "nurl": "http://example.com/win?bid_request_id=${AUCTION_ID}"
        }
      ]
    }
  ],
  "cur": "JPY"
}

Your bid loses in the auction, causing your loss notification URL to be pinged with the expanded values for ${AUCTION_ID} and ${CREATIVE_STATUS_CODE}:

http://example.com/loss?bid_request_id=D3x8RPLO96R6T137tQ6168&creative_status_code=79
Conclusion: You now know that the bid request with ID "D3x8RPLO96R6T137tQ6168" is ineligible for building a user profile for Google User ID "D17oNZQUJqB4Rt4n4Ec61AC9tee" in the UK because:
- The bid request indicates the following:
  - The user device is located in a region where IAB TCF is enforced.
  - The TC string indicates:
    - Vendor ID 755 is permitted to build user profiles by the user because the user has consented to purpose 3 for vendor ID 755.
    - There are no publisher restrictions.
  - The publisher allows user data collection.
  - The bid request ID is "D3x8RPLO96R6T137tQ6168".
  - The Google User ID is "D17oNZQUJqB4Rt4n4Ec61AC9tee".
  - The user device is located in "GBR".
- Your loss notification endpoint is pinged with query string parameters indicating that the bid request with ID "D3x8RPLO96R6T137tQ6168" has lost the auction due to being outbid.
- The additional condition requirements for the UK haven't been met.

Find bid request from the UK ineligible due to publisher restriction

The following example determines that vendor ID 755 is ineligible to use the bid request for user profiling because the publisher has restricted purpose 3 for vendor ID 755.

Your bidding endpoint receives a bid request:

{
  "id": "D3x8RPLO96R6T137tQ6168",
  "imp": [
    {
      "bidfloor": 140.414643547123,
      "bidfloorcur": "JPY"
    }
  ],
  "device": {
    "geo": {
      "country": "GBR"
    }
  },
  "user": {
    "consent": "CQhuhyAQhuhyAB7ACBENCOEIALAAAELAAAwIF5gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgXmAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAGCAAgLzDAAQF5iAAIC8w.gF5gAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAg"
  },
  "regs": {
    "ext": {
      "gdpr": 1
    }
  },
  "ext": {
    "privacy_treatments": {
      "allow_user_data_collection": 1
    }
  }
}

You place a bid:

{
  "seatbid": [
    {
      "bid": [
        {
          "price": 149.83914184570312,
          "lurl": "http://example.com/loss?bid_request_id=${AUCTION_ID}&creative_status_code=${CREATIVE_STATUS_CODE}",
          "nurl": "http://example.com/win?bid_request_id=${AUCTION_ID}"
        }
      ]
    }
  ],
  "cur": "JPY"
}

Conclusion: You now know that vendor ID 755 is ineligible to use the bid request with ID "D3x8RPLO96R6T137tQ6168" to build user profiles because:
- The bid request indicates the following:
  - The user device is located in a region where IAB TCF is enforced.
  - The TC string indicates:
    - Vendor ID 755 is permitted to build user profiles by the user because the user has consented to purpose 3 for vendor ID 755.
    - There are publisher restrictions for purpose 3 targeting vendor ID 755.
  - The publisher allows user data collection.
  - The bid request ID is "D3x8RPLO96R6T137tQ6168".
  - The Google User ID is "D17oNZQUJqB4Rt4n4Ec61AC9tee".
  - The user device is located in "GBR".
- The publisher permission requirement hasn’t been met.

Find non-EEA bid request eligible

The following example uses real-time feedback to determine that a bid request from a non-EEA region is eligible despite being filtered because the bid entered the auction.

Your bidding endpoint receives a bid request:

{
  "id": "D3x8RPLO96R6T137tQ6168",
  "imp": [
    {
      "bidfloor": 140.414643547123,
      "bidfloorcur": "JPY"
    }
  ],
  "device": {
    "geo": {
      "country": "JPN"
    }
  },
  "user": {
    "id": "D17oNZQUJqB4Rt4n4Ec61AC9tee"
  },
  "ext": {
    "privacy_treatments": {
      "allow_user_data_collection": 1
    }
  }
}

You place a bid:

{
  "seatbid": [
    {
      "bid": [
        {
          "price": 120.846348234842
        }
      ]
    }
  ],
  "cur": "JPY"
}

Your bid loses in the auction. In a future bid request, your bidding endpoint receives a bid request containing real-time feedback:

{
  "id": "9B5K1zj5T61jRM80t25s13",
  "ext": {
    "bid_feedback": [
      {
        "request_id": "3265hT3M9Uq7370Ou263Zp",
        "creative_status_code": 1
      },
      {
        "request_id": "D3x8RPLO96R6T137tQ6168",
        "creative_status_code": 80
      }
    ]
  }
}

Conclusion: You now know that the bid request with ID "D3x8RPLO96R6T137tQ6168" is eligible for building a user profile for Google User ID "D17oNZQUJqB4Rt4n4Ec61AC9tee" in Japan because:
- The bid request indicates the following:
  - The user device is located in a region where IAB TCF isn't enforced.
  - The publisher allows user data collection.
  - The bid request ID is "D3x8RPLO96R6T137tQ6168".
  - The Google User ID is "D17oNZQUJqB4Rt4n4Ec61AC9tee".
  - The user device is located in "JPN".
- You received bid request feedback indicating that the bid request with ID "D3x8RPLO96R6T137tQ6168" lost the auction due to your bid being below the bid floor. For non-EEA countries such as Japan, entering the auction and being filtered for this reason meets the additional conditions.
- The publisher permission and additional condition requirements for Japan have been met.

Find non-EEA bid request ineligible

The following example uses real-time feedback to determine that a bid request from a non-EEA region is ineligible because it was filtered before the auction.

Your bidding endpoint receives a bid request:

{
  "id": "D3x8RPLO96R6T137tQ6168",
  "imp": [
    {
      "bidfloor": 140.414643547123,
      "bidfloorcur": "JPY"
    }
  ],
  "device": {
    "geo": {
      "country": "JPN"
    }
  },
  "user": {
    "id": "D17oNZQUJqB4Rt4n4Ec61AC9tee"
  },
  "ext": {
    "privacy_treatments": {
      "allow_user_data_collection": 1
    }
  }
}

You place a bid:

{
  "seatbid": [
    {
      "bid": [
        {
          "price": 149.83914184570312
        }
      ]
    }
  ],
  "cur": "JPY"
}

Your bid loses in the auction. In a future bid request, your bidding endpoint receives a bid request containing real-time feedback:

{
  "id": "9B5K1zj5T61jRM80t25s13",
  "ext": {
    "bid_feedback": [
      {
        "request_id": "3265hT3M9Uq7370Ou263Zp",
        "creative_status_code": 1
      },
      {
        "request_id": "D3x8RPLO96R6T137tQ6168",
        "creative_status_code": 10
      }
    ]
  }
}

Conclusion: You now know that the bid request with ID "D3x8RPLO96R6T137tQ6168" is ineligible for building a user profile for Google User ID "D17oNZQUJqB4Rt4n4Ec61AC9tee" in Japan because:
- The bid request indicates the following:
  - The user device is located in a region where IAB TCF isn't enforced.
  - The publisher allows user data collection.
  - The bid request ID is "D3x8RPLO96R6T137tQ6168".
  - The Google User ID is "D17oNZQUJqB4Rt4n4Ec61AC9tee".
  - The user device is located in "JPN".
- You received bid request feedback indicating that the bid request with ID "D3x8RPLO96R6T137tQ6168" didn't enter the auction due to your bid using a disapproved creative.
- The additional condition requirements for non-EEA countries such as Japan haven't been met.

Next steps

RTB API UserLists resource reference: Reference for the Real-time Bidding API's userLists resource, which is used to create and modify user lists used for remarketing.
Cookie Matching: Reference for the Cookie Matching Service, and other related services, used for remarketing.
Upload ad IDs to user lists: Reference for the Bulk Uploader API that is used to upload identifiers to user lists.

Use bid requests to build user profiles Stay organized with collections Save and categorize content based on your preferences.

Determine if personalized ads are allowed

Check the non_personalized_ads_reason field

Use the TC string to check consent for IAB vendors

Determine if the publisher granted permission

Check if the publisher allows user data collection

Check for publisher restrictions using the TC string

Comply with additional conditions for the region

Understand additional conditions for EEA, UK, and Switzerland

Understand additional conditions for Non-EEA, UK, or Switzerland regions

Use real-time feedback to determine auction outcome

Use win and loss notifications to determine auction outcome

Use the creative status code to comply with additional conditions

Review examples

Find bid request ineligible due to publisher blocking data collection

Find bid request from the UK eligible

Find bid request from the UK ineligible due to auction loss

Find bid request from the UK ineligible due to publisher restriction

Find non-EEA bid request eligible

Find non-EEA bid request ineligible

Next steps

Use bid requests to build user profiles

Check the `non_personalized_ads_reason` field