You can use the Bulk Uploader API to add and remove ad IDs to Authorized Buyers user lists for targeting. > [!NOTE] > **Note:** Cookie matching must be enabled in order to use the Bulk Uploader API. 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide). The HTTPS POST request's payload is an encoded [protocol buffer](https://developers.google.com/protocol-buffers) that describes the lists to be modified. See the schema for the Bulk Uploader service in [cookie-bulk-upload-proto.txt](https://developers.google.com/static/authorized-buyers/rtb/downloads/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](https://protobuf.dev/getting-started/). You can upload the following identifiers types: - Google user ID - Partner-provided ID - [iOS IDFA](https://support.google.com/authorizedbuyers/answer/3221407) - Android advertising ID - Roku ID - Amazon Fire TV ID - Xbox or Microsoft ID > [!NOTE] > **Note:** In bulk uploader operations, you must provide the full ID. Don't use base64 encoded ID to your bulk uploader operations. ### Upload Google user IDs Google user IDs are encrypted IDs from the `doubleclick.net` domain. Here's how to upload a Google user ID: 1. Set up [Cookie Matching](https://developers.google.com/authorized-buyers/rtb/cookie-guide) with Google and host the match table. 2. Use your match table to convert your user IDs into Google User IDs. 3. 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: 1. Set up [Cookie Matching](https://developers.google.com/authorized-buyers/rtb/cookie-guide) with Google, and allow Google to host your match table. 2. 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](https://en.wikipedia.org/wiki/Base64#URL_applications) 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 3. 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 } 4. 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. 1. Upload device ID with `UpdateUsersDataRequest`: ops { user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A" user_list_id: 111 delete: false user_id_type: IDFA } 2. Google then translates the user list from device IDs to Google user IDs, and adds the IDs to your user list. > [!NOTE] > **Note:** If Google is unable to match the IDFA to a Google user ID, the Bulk Uploader ID returns an error response. ## Workflow All Bulk Uploader request and response examples are written in [Text Format](https://protobuf.dev/reference/protobuf/textformat-spec/). You have to send them as serialized [Protocol Buffer](https://developers.google.com/protocol-buffers) 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 > [!WARNING] > **Warning:** You must have a valid legal basis and user consent, if required, to share user data with Google for processing purposes before indicating `process_consent: true`. See section `Process Consent In Bulk Upload Request`. 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 ## Example This is an example Python script demonstrating how you can use the library generated by [cookie-bulk-upload.proto](https://developers.google.com/static/authorized-buyers/rtb/downloads/cookie-bulk-upload-proto.txt) to populate a user list with a given ID using the bulk uploader service: #!/usr/bin/python # # Copyright 2023 Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """A sample demonstrating usage of the Authorized Buyers Bulk Upload service. Successfully running this example will add the provided ID to the given user list. To learn more about the bulk uploader service, see: https://developers.google.com/authorized-buyers/rtb/bulk-uploader """ import argparse import gen.cookie_bulk_upload_pb2 import requests BULK_UPLOAD_ENDPOINT_TEMPLATE = 'https://cm.g.doubleclick.net/upload?nid=%s' def main(account_nid, user_list_id, user_id, user_id_type): # Build the bulk upload request. update_request = gen.cookie_bulk_upload_pb2.UpdateUsersDataRequest() update_request.send_notifications = True ops = update_request.ops op = ops.add() op.user_list_id = user_list_id op.user_id = user_id op.user_id_type = user_id_type user_id_type_value = gen.cookie_bulk_upload_pb2.UserIdType.Name( user_id_type) print(f'For NID "{account_nid}", adding user ID "{user_id}" of type ' f'"{user_id_type_value}" to user list ID "{user_list_id}"') # Execute the bulk upload request. response = requests.post(BULK_UPLOAD_ENDPOINT_TEMPLATE % account_nid, data=update_request.SerializeToString()) # Parse and display the response. update_response = gen.cookie_bulk_upload_pb2.UpdateUsersDataResponse() update_response.ParseFromString(response.content) print('Operation completed with the following:') print(f'\tHTTP Status code: {response.status_code}') status_value = gen.cookie_bulk_upload_pb2.ErrorCode.Name( update_response.status) print(f'\tUpdateUsersDataResponse.status: {status_value}') print(f'\tUpdateUsersDataResponse.errors: {update_response.errors}') print('\tUpdateUsersDataResponse.notifications: ' f'{update_response.notifications}') n_status_value = gen.cookie_bulk_upload_pb2.NotificationStatus.Name( update_response.notification_status) print(f'\tUpdateUsersDataResponse.notification_status: {n_status_value}') if __name__ == '__main__': parser = argparse.ArgumentParser( description=('A sample demonstrating usage of the Authorized Buyers ' 'bulk uploader service.')) parser.add_argument('-n', '--account_nid', required=True, help='The Account NID.') parser.add_argument('-u', '--user_id', required=True, help='The User ID to be added.') parser.add_argument('-l', '--user_list_id', type=int, required=True, help='The user list that the ID is being added to.') parser.add_argument('-t', '--user_id_type', type=int, required=True, help=('The type of user ID being added. See ' '"UserIdType" enum for more details.')) args = parser.parse_args() main(args.account_nid, args.user_list_id, args.user_id, args.user_id_type) ## Process Consent In Bulk Upload Request Partners using the Bulk Upload API must indicate that they have the proper legal basis to share user data with Google for Bulk Upload purposes using the process_consent parameter. This requirement applies to all Bulk Upload requests. For user data that requires end-user consent as required by Google's EU User Consent Policy (see https://www.google.com/about/company/user-consent-policy/) or by other local laws, partners are required to obtain end-user consent and indicate gathered consent by setting `process_consent=True`. For user data which is not subject to end-user consent requirements, partners are required to indicate that consent is not required by setting `process_consent=True`. Requests where `process_consent` is missing will be filtered and return the following error: status: MISSING_CONSENT_WILL_BE_DROPPED Requests where `process_consent` is set to `false` will be filtered and return the following error: status: MISSING_CONSENT