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 thegoogle_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