Upload ad IDs to user lists

You can use the Bulk Uploader API to add and remove ad IDs to Google user lists for targeting. You can also upload user lists like those for Programmatic Guaranteed deals.

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
}

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