Upload ad IDs to user lists

You can use the Bulk Uploader API to add and remove ad IDs to Authorized Buyers user lists for targeting. You can't use the Authorized Buyers Bulk Uploader API to modify Display & Video 360 audience lists.

Here's a sample HTTPS Bulk Uploader API URL:

https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}

The endpoint accepts HTTPS POST requests.

The value for GoogleNetworkId should be your Cookie Matching Network ID (NID) which uniquely identifies your account for Bulk Uploader and Cookie Matching.

The HTTPS POST request's payload is an encoded protocol buffer that describes the lists to be modified. See the schema for the Bulk Uploader service in cookie-bulk-upload-proto.txt. The payload of each request is limited to 100 KB.

To learn more about how to compile and use cookie-bulk-upload.proto to serialize and parse messages, see the tutorial for your preferred language.

You can upload the following identifiers types:

Google user ID
Partner-provided ID
iOS IDFA
Android advertising ID
Roku ID
Amazon Fire TV ID
Xbox or Microsoft ID

Upload Google user IDs

Google user IDs are encrypted IDs from the doubleclick.net domain.

Here's how to upload a Google user ID:

Set up Cookie Matching with Google and host the match table.
Use your match table to convert your user IDs into Google User IDs.
Upload Google User IDs to the user list.

For example, if you receive the following during Cookie Matching:

https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1

The google_gid parameter is the encrypted Google User ID.

To add it to a user list, copy it to the UpdateUsersDataRequest body:

ops {
  user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
  user_list_id: 111
  delete: false
  user_id_type: GOOGLE_USER_ID
}

Upload partner-provided IDs

Partner-provided IDs are IDs under the partner's own domain. Here's how to upload a partner-provided ID:

Set up Cookie Matching with Google, and allow Google to host your match table.
Upload your partner-provided IDs to the user list.

For example, if you have a user ID for your domain set as 123456, you can populate it in Google's hosted match table with Cookie Matching. Your match tag should include a web-safe base64-encoded version of the ID assigned to the google_hm parameter, such as the following:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```

You can then upload the partner-provided ID to a user list with UpdateUsersDataRequest:

ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}

Google then translates the user list from partner-provided IDs to Google user IDs, and adds the IDs to your user list.

Upload IDFA or Android advertising IDs

You can also upload device IDs.

Upload device ID with UpdateUsersDataRequest:

ops {
 user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
 user_list_id: 111
 delete: false
 user_id_type: IDFA
}

Google then translates the user list from device IDs to Google user IDs, and adds the IDs to your user list.

Sample

All Bulk Uploader request and response examples are written in Text Format. You have to send them as serialized Protocol Buffer messages to the Bulk Uploader API endpoint.

For example, to upload an IDFA and partner-provided ID to user list 123, create an UpdateUsersDataRequest:

ops {
  user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
  user_list_id: 123
  delete: false
  user_id_type: IDFA
}
ops {
  user_id: "1234567"
  user_list_id: 123
  delete: false
  user_id_type: PARTNER_PROVIDED_ID
}
# See warning before use. Requires affirmative end-user consent.
process_consent: true

Then, send an HTTPS POST request with the serialized UpdateUsersDataRequest message as the payload.

If all of the operations are successful, you get the following UpdateUsersDataResponse:

status: NO_ERROR

If some of the operations were successful, the response includes an UpdateUsersDataResponse with an error for each failed operation:

status: PARTIAL_SUCCESS
errors {
  user_id: "1234567"
  error_code: UNKNOWN_ID
  user_id_type: PARTNER_PROVIDED_ID
}

If none of the operations were successful, the response includes an UpdateUsersDataResponse with status set to BAD_COOKIE:

status: BAD_COOKIE

Process Consent In Bulk Upload Request

Bulk Upload partners are required to obtain affirmative end-user consent before adding a user to a user list. The partner should include process_consent on each bulk upload request. This signal indicates the partner has collected consent for all the data included in the upload, in accordance with Google's EU User Consent Policy.

Ad tech partners using the Bulk Upload API must indicate that they have gathered the proper legal consent using the process_consent flag.

In the short-term, requests without process_consent=true, return a missing consent error but continue to be processed without change.

status: MISSING_CONSENT_WILL_BE_DROPPED

Beginning March 2024, requests without process_consent=true will be dropped entirely and will return the following error.

status: MISSING_CONSENT