Reference this guide for customer list updates, removals, and reporting.

> [!NOTE]
> **Note:** As of April 1, 2026, most new Customer Match integrations must use the [Data Manager API](https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match.md.txt). Existing eligible integrations can continue to use the Google Ads API for managing customer lists.

## Update a list with `OfflineUserDataJobService`

Once you've created your customer lists and set up targeting, it's best to
refresh them regularly.

To update your lists with the latest data, it is generally more efficient to
append or remove individual users, rather than removing all users from the list
and uploading them from scratch.

> [!IMPORTANT]
> **Important:** A user list can only be modified by the Google Ads or [data partner](https://support.google.com/google-ads/answer/7361372) account that created it.

### Append to a list

To append to an existing list, create an `OfflineUserDataJob` in the same way
you would when creating a new customer list.


### Java

```java
private void addUsersToCustomerMatchUserList(
    GoogleAdsClient googleAdsClient,
    long customerId,
    boolean runJob,
    String userListResourceName,
    Long offlineUserDataJobId,
    ConsentStatus adPersonalizationConsent,
    ConsentStatus adUserDataConsent)
    throws UnsupportedEncodingException {
  try (OfflineUserDataJobServiceClient offlineUserDataJobServiceClient =
      googleAdsClient.getLatestVersion().createOfflineUserDataJobServiceClient()) {
    String offlineUserDataJobResourceName;
    if (offlineUserDataJobId == null) {
      // Creates a new offline user data job.
      OfflineUserDataJob.Builder offlineUserDataJobBuilder =
          OfflineUserDataJob.newBuilder()
              .setType(OfflineUserDataJobType.CUSTOMER_MATCH_USER_LIST)
              .setCustomerMatchUserListMetadata(
                  CustomerMatchUserListMetadata.newBuilder().setUserList(userListResourceName));
      // Adds consent information to the job if specified.
      if (adPersonalizationConsent != null || adUserDataConsent != null) {
        Consent.Builder consentBuilder = Consent.newBuilder();
        if (adPersonalizationConsent != null) {
          consentBuilder.setAdPersonalization(adPersonalizationConsent);
        }
        if (adUserDataConsent != null) {
          consentBuilder.setAdUserData(adUserDataConsent);
        }
        // Specifies whether user consent was obtained for the data you are uploading. See
        // https://www.google.com/about/company/user-consent-policy for details.
        offlineUserDataJobBuilder
            .getCustomerMatchUserListMetadataBuilder()
            .setConsent(consentBuilder);
      }

      // Issues a request to create the offline user data job.
      CreateOfflineUserDataJobResponse createOfflineUserDataJobResponse =
          offlineUserDataJobServiceClient.createOfflineUserDataJob(
              Long.toString(customerId), offlineUserDataJobBuilder.build());
      offlineUserDataJobResourceName = createOfflineUserDataJobResponse.getResourceName();
      System.out.printf(
          "Created an offline user data job with resource name: %s.%n",
          offlineUserDataJobResourceName);
    } else {
      // Reuses the specified offline user data job.
      offlineUserDataJobResourceName =
          ResourceNames.offlineUserDataJob(customerId, offlineUserDataJobId);
    }

    // Issues a request to add the operations to the offline user data job. This example
    // only adds a few operations, so it only sends one AddOfflineUserDataJobOperations request.
    // If your application is adding a large number of operations, split the operations into
    // batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job. See
    // https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    // and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    // for more information on the per-request limits.
    List<OfflineUserDataJobOperation> userDataJobOperations = buildOfflineUserDataJobOperations();
    AddOfflineUserDataJobOperationsResponse response =
        offlineUserDataJobServiceClient.addOfflineUserDataJobOperations(
            AddOfflineUserDataJobOperationsRequest.newBuilder()
                .setResourceName(offlineUserDataJobResourceName)
                .setEnablePartialFailure(true)
                .addAllOperations(userDataJobOperations)
                .build());

    // Prints the status message if any partial failure error is returned.
    // NOTE: The details of each partial failure error are not printed here, you can refer to
    // the example HandlePartialFailure.java to learn more.
    if (response.hasPartialFailureError()) {
      GoogleAdsFailure googleAdsFailure =
          ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
      System.out.printf(
          "Encountered %d partial failure errors while adding %d operations to the offline user "
              + "data job: '%s'. Only the successfully added operations will be executed when "
              + "the job runs.%n",
          googleAdsFailure.getErrorsCount(),
          userDataJobOperations.size(),
          response.getPartialFailureError().getMessage());
    } else {
      System.out.printf(
          "Successfully added %d operations to the offline user data job.%n",
          userDataJobOperations.size());
    }

    if (!runJob) {
      System.out.printf(
          "Not running offline user data job '%s', as requested.%n",
          offlineUserDataJobResourceName);
      return;
    }

    // Issues an asynchronous request to run the offline user data job for executing
    // all added operations.
    offlineUserDataJobServiceClient.runOfflineUserDataJobAsync(offlineUserDataJobResourceName);

    // BEWARE! The above call returns an OperationFuture. The execution of that future depends on
    // the thread pool which is owned by offlineUserDataJobServiceClient. If you use this future,
    // you *must* keep the service client in scope too.
    // See https://developers.google.com/google-ads/api/docs/client-libs/java/lro for more detail.

    // Offline user data jobs may take 6 hours or more to complete, so instead of waiting for the
    // job to complete, retrieves and displays the job status once. If the job is completed
    // successfully, prints information about the user list. Otherwise, prints the query to use
    // to check the job again later.
    checkJobStatus(googleAdsClient, customerId, offlineUserDataJobResourceName);
  }
}

      
```

### C#

```c#
private static string AddUsersToCustomerMatchUserList(GoogleAdsClient client,
    long customerId, string userListResourceName, bool runJob,
    long? offlineUserDataJobId, ConsentStatus? adPersonalizationConsent,
    ConsentStatus? adUserDataConsent)
{
    // Get the OfflineUserDataJobService.
    OfflineUserDataJobServiceClient service = client.GetService(
        Services.V26.OfflineUserDataJobService);

    string offlineUserDataJobResourceName;
    if (offlineUserDataJobId == null)
    {
        // Creates a new offline user data job.
        OfflineUserDataJob offlineUserDataJob = new OfflineUserDataJob()
        {
            Type = OfflineUserDataJobType.CustomerMatchUserList,
            CustomerMatchUserListMetadata = new CustomerMatchUserListMetadata()
            {
                UserList = userListResourceName,
            }
        };

        if (adUserDataConsent != null || adPersonalizationConsent != null)
        {
            // Specifies whether user consent was obtained for the data you are uploading.
            // See https://www.google.com/about/company/user-consent-policy
            // for details.
            offlineUserDataJob.CustomerMatchUserListMetadata.Consent = new Consent();

            if (adPersonalizationConsent != null)
            {
                offlineUserDataJob.CustomerMatchUserListMetadata.Consent.AdPersonalization =
                    (ConsentStatus)adPersonalizationConsent;
            }

            if (adUserDataConsent != null)
            {
                offlineUserDataJob.CustomerMatchUserListMetadata.Consent.AdUserData =
                    (ConsentStatus)adUserDataConsent;
            }
        }

        // Issues a request to create the offline user data job.
        CreateOfflineUserDataJobResponse response1 = service.CreateOfflineUserDataJob(
            customerId.ToString(), offlineUserDataJob);
        offlineUserDataJobResourceName = response1.ResourceName;
        Console.WriteLine($"Created an offline user data job with resource name: " +
            $"'{offlineUserDataJobResourceName}'.");
    } else {
        // Reuses the specified offline user data job.
        offlineUserDataJobResourceName =
            ResourceNames.OfflineUserDataJob(customerId, offlineUserDataJobId.Value);
    }

    AddOfflineUserDataJobOperationsRequest request =
        new AddOfflineUserDataJobOperationsRequest()
        {
            ResourceName = offlineUserDataJobResourceName,
            Operations = { BuildOfflineUserDataJobOperations() },
            EnablePartialFailure = true,
        };
    // Issues a request to add the operations to the offline user data job. This example
    // only adds a few operations, so it only sends one AddOfflineUserDataJobOperations
    // request.
    // If your application is adding a large number of operations, split the operations into
    // batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job.
    // See https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    // and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    // for more information on the per-request limits.
    AddOfflineUserDataJobOperationsResponse response2 =
        service.AddOfflineUserDataJobOperations(request);

    // Prints the status message if any partial failure error is returned.
    // Note: The details of each partial failure error are not printed here,
    // you can refer to the example HandlePartialFailure.cs to learn more.
    if (response2.PartialFailureError != null)
    {
        // Extracts the partial failure from the response status.
        GoogleAdsFailure partialFailure = response2.PartialFailure;
        Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " +
            $"occurred");
    }
    Console.WriteLine("The operations are added to the offline user data job.");

    if (!runJob)
    {
        Console.WriteLine($"Not running offline user data job " +
            "'{offlineUserDataJobResourceName}', as requested.");
        return offlineUserDataJobResourceName;
    }

    // Issues an asynchronous request to run the offline user data job for executing
    // all added operations.
    Operation<Empty, OfflineUserDataJobMetadata> operationResponse =
        service.RunOfflineUserDataJob(offlineUserDataJobResourceName);

    Console.WriteLine("Asynchronous request to execute the added operations started.");

    // Since offline user data jobs may take 24 hours or more to complete, it may not be
    // practical to do operationResponse.PollUntilCompleted() to wait for the results.
    // Instead, we save the offlineUserDataJobResourceName and use GoogleAdsService.Search
    // to check for the job status periodically.
    // In case you wish to follow the PollUntilCompleted or PollOnce approach, make sure
    // you keep both operationResponse and service variables alive until the polling
    // completes.

    return offlineUserDataJobResourceName;
}
      
```

### PHP

```php
    private static function addUsersToCustomerMatchUserList(
        GoogleAdsClient $googleAdsClient,
        int $customerId,
        bool $runJob,
        ?string $userListResourceName,
        ?int $offlineUserDataJobId,
        ?int $adPersonalizationConsent,
        ?int $adUserDataConsent
    ) {
        $offlineUserDataJobServiceClient =
            $googleAdsClient->getOfflineUserDataJobServiceClient();

        if (is_null($offlineUserDataJobId)) {
            // Creates a new offline user data job.
            $offlineUserDataJob = new OfflineUserDataJob(
                [
                'type' => OfflineUserDataJobType::CUSTOMER_MATCH_USER_LIST,
                'customer_match_user_list_metadata' => new CustomerMatchUserListMetadata(
                    [
                    'user_list' => $userListResourceName
                    ]
                )
                ]
            );
            // Adds consent information to the job if specified.
            if (!empty($adPersonalizationConsent) || !empty($adUserDataConsent)) {
                $consent = new Consent();
                if (!empty($adPersonalizationConsent)) {
                    $consent->setAdPersonalization($adPersonalizationConsent);
                }
                if (!empty($adUserDataConsent)) {
                    $consent->setAdUserData($adUserDataConsent);
                }
                // Specifies whether user consent was obtained for the data you are uploading. See
                // https://www.google.com/about/company/user-consent-policy for details.
                $offlineUserDataJob->getCustomerMatchUserListMetadata()->setConsent($consent);
            }

            // Issues a request to create the offline user data job.
            /**
 * @var CreateOfflineUserDataJobResponse $createOfflineUserDataJobResponse
*/
            $createOfflineUserDataJobResponse =
                $offlineUserDataJobServiceClient->createOfflineUserDataJob(
                    CreateOfflineUserDataJobRequest::build($customerId, $offlineUserDataJob)
                );
            $offlineUserDataJobResourceName = $createOfflineUserDataJobResponse->getResourceName();
            printf(
                "Created an offline user data job with resource name: '%s'.%s",
                $offlineUserDataJobResourceName,
                PHP_EOL
            );
        } else {
            // Reuses the specified offline user data job.
            $offlineUserDataJobResourceName =
                ResourceNames::forOfflineUserDataJob($customerId, $offlineUserDataJobId);
        }

        // Issues a request to add the operations to the offline user data job. This example
        // only adds a few operations, so it only sends one AddOfflineUserDataJobOperations request.
        // If your application is adding a large number of operations, split the operations into
        // batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job. See
        // https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
        // and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
        // for more information on the per-request limits.
        /**
 * @var AddOfflineUserDataJobOperationsResponse $operationResponse
*/
        $response = $offlineUserDataJobServiceClient->addOfflineUserDataJobOperations(
            AddOfflineUserDataJobOperationsRequest::build(
                $offlineUserDataJobResourceName,
                self::buildOfflineUserDataJobOperations()
            )->setEnablePartialFailure(true)
        );

        // Prints the status message if any partial failure error is returned.
        // Note: The details of each partial failure error are not printed here, you can refer to
        // the example HandlePartialFailure.php to learn more.
        if ($response->hasPartialFailureError()) {
            // Extracts the partial failure from the response status.
            $partialFailure = GoogleAdsFailures::fromAny(
                $response->getPartialFailureError()->getDetails()->getIterator()->current()
            );
            printf(
                "%d partial failure error(s) occurred: %s.%s",
                count($partialFailure->getErrors()),
                $response->getPartialFailureError()->getMessage(),
                PHP_EOL
            );
        } else {
            print 'The operations are added to the offline user data job.' . PHP_EOL;
        }

        if ($runJob === false) {
            printf(
                "Not running offline user data job '%s', as requested.%s",
                $offlineUserDataJobResourceName,
                PHP_EOL
            );
            return;
        }

        // Issues an asynchronous request to run the offline user data job for executing all added
        // operations. The result is OperationResponse. Visit the OperationResponse.php file for
        // more details.
        $offlineUserDataJobServiceClient->runOfflineUserDataJob(
            RunOfflineUserDataJobRequest::build($offlineUserDataJobResourceName)
        );

        // Offline user data jobs may take 6 hours or more to complete, so instead of waiting
        // for the job to complete, retrieves and displays the job status once. If the job is
        // completed successfully, prints information about the user list. Otherwise, prints the
        // query to use to check the job again later.
        self::checkJobStatus($googleAdsClient, $customerId, $offlineUserDataJobResourceName);
    }
      
```

### Python

```python
def add_users_to_customer_match_user_list(
    client: GoogleAdsClient,
    customer_id: str,
    user_list_resource_name: str,
    run_job: bool,
    offline_user_data_job_id: Optional[str],
    ad_user_data_consent: Optional[str],
    ad_personalization_consent: Optional[str],
) -> None:
    """Uses Customer Match to create and add users to a new user list.

    Args:
        client: The Google Ads client.
        customer_id: The ID for the customer that owns the user list.
        user_list_resource_name: The resource name of the user list to which to
            add users.
        run_job: If true, runs the OfflineUserDataJob after adding operations.
            Otherwise, only adds operations to the job.
        offline_user_data_job_id: ID of an existing OfflineUserDataJob in the
            PENDING state. If None, a new job is created.
        ad_user_data_consent: The consent status for ad user data for all
            members in the job.
        ad_personalization_consent: The personalization consent status for ad
            user data for all members in the job.
    """
    # Creates the OfflineUserDataJobService client.
    offline_user_data_job_service_client: OfflineUserDataJobServiceClient = (
        client.get_service("OfflineUserDataJobService")
    )
    offline_user_data_job_resource_name: str

    if offline_user_data_job_id:
        # Reuses the specified offline user data job.
        offline_user_data_job_resource_name = (
            offline_user_data_job_service_client.offline_user_data_job_path(
                customer_id, offline_user_data_job_id
            )
        )
    else:
        # Creates a new offline user data job.
        offline_user_data_job: OfflineUserDataJob = client.get_type(
            "OfflineUserDataJob"
        )
        offline_user_data_job.type_ = (
            client.enums.OfflineUserDataJobTypeEnum.CUSTOMER_MATCH_USER_LIST
        )
        offline_user_data_job.customer_match_user_list_metadata.user_list = (
            user_list_resource_name
        )

        # Specifies whether user consent was obtained for the data you are
        # uploading. For more details, see:
        # https://www.google.com/about/company/user-consent-policy
        if ad_user_data_consent:
            offline_user_data_job.customer_match_user_list_metadata.consent.ad_user_data = client.enums.ConsentStatusEnum[
                ad_user_data_consent
            ]
        if ad_personalization_consent:
            offline_user_data_job.customer_match_user_list_metadata.consent.ad_personalization = client.enums.ConsentStatusEnum[
                ad_personalization_consent
            ]

        # Issues a request to create an offline user data job.
        create_offline_user_data_job_response: (
            CreateOfflineUserDataJobResponse
        ) = offline_user_data_job_service_client.create_offline_user_data_job(
            customer_id=customer_id, job=offline_user_data_job
        )
        offline_user_data_job_resource_name = (
            create_offline_user_data_job_response.resource_name
        )
        print(
            "Created an offline user data job with resource name: "
            f"'{offline_user_data_job_resource_name}'."
        )

    # Issues a request to add the operations to the offline user data job.

    # Best Practice: This example only adds a few operations, so it only sends
    # one AddOfflineUserDataJobOperations request. If your application is adding
    # a large number of operations, split the operations into batches and send
    # multiple AddOfflineUserDataJobOperations requests for the SAME job. See
    # https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    # and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    # for more information on the per-request limits.
    request: AddOfflineUserDataJobOperationsRequest = client.get_type(
        "AddOfflineUserDataJobOperationsRequest"
    )
    request.resource_name = offline_user_data_job_resource_name
    request.operations = build_offline_user_data_job_operations(client)
    request.enable_partial_failure = True

    # Issues a request to add the operations to the offline user data job.
    response: AddOfflineUserDataJobOperationsResponse = (
        offline_user_data_job_service_client.add_offline_user_data_job_operations(
            request=request
        )
    )

    # Prints the status message if any partial failure error is returned.
    # Note: the details of each partial failure error are not printed here.
    # Refer to the error_handling/handle_partial_failure.py example to learn
    # more.
    # Extracts the partial failure from the response status.
    partial_failure: Union[status_pb2.Status, None] = getattr(
        response, "partial_failure_error", None
    )
    if getattr(partial_failure, "code", None) != 0:
        error_details: Iterable[Any, None] = getattr(
            partial_failure, "details", []
        )
        for error_detail in error_details:
            failure_message: GoogleAdsFailure = client.get_type(
                "GoogleAdsFailure"
            )
            # Retrieve the class definition of the GoogleAdsFailure instance
            # in order to use the "deserialize" class method to parse the
            # error_detail string into a protobuf message object.
            failure_object: GoogleAdsFailure = type(
                failure_message
            ).deserialize(error_detail.value)
            errors: Iterable[GoogleAdsError] = failure_object.errors

            for error in errors:
                print(
                    "A partial failure at index "
                    f"{error.location.field_path_elements[0].index} occurred.\n"
                    f"Error message: {error.message}\n"
                    f"Error code: {error.error_code}"
                )

    print("The operations are added to the offline user data job.")

    if not run_job:
        print(
            "Not running offline user data job "
            f"'{offline_user_data_job_resource_name}', as requested."
        )
        return

    # Issues a request to run the offline user data job for executing all
    # added operations.
    offline_user_data_job_service_client.run_offline_user_data_job(
        resource_name=offline_user_data_job_resource_name
    )

    # Retrieves and displays the job status.
    check_job_status(client, customer_id, offline_user_data_job_resource_name)
      
```

### Ruby

```ruby
def add_users_to_customer_match_user_list(client, customer_id, run_job, user_list, job_id, ad_user_data_consent, ad_personalization_consent)
  offline_user_data_service = client.service.offline_user_data_job

  job_name = if job_id.nil?
    # Creates the offline user data job.
    offline_user_data_job = client.resource.offline_user_data_job do |job|
      job.type = :CUSTOMER_MATCH_USER_LIST
      job.customer_match_user_list_metadata =
        client.resource.customer_match_user_list_metadata do |m|
          m.user_list = user_list

          if !ad_user_data_consent.nil? || !ad_personalization_consent.nil?
            m.consent = client.resource.consent do |c|
              # Specifies whether user consent was obtained for the data you are
              # uploading. For more details, see:
              # https://www.google.com/about/company/user-consent-policy
              unless ad_user_data_consent.nil?
                c.ad_user_data = ad_user_data_consent
              end
              unless ad_personalization_consent.nil?
                c.ad_personalization = ad_personalization_consent
              end
            end
          end
        end
    end

    # Issues a request to create the offline user data job.
    response = offline_user_data_service.create_offline_user_data_job(
      customer_id: customer_id,
      job: offline_user_data_job,
    )
    offline_user_data_job_resource_name = response.resource_name
    puts "Created an offline user data job with resource name: " \
      "#{offline_user_data_job_resource_name}"

    offline_user_data_job_resource_name
  else
    client.path.offline_user_data_job(customer_id, job_id)
  end

  # Issues a request to add the operations to the offline user data job. This
  # example only adds a few operations, so it only sends one
  # AddOfflineUserDataJobOperations request.  If your application is adding a
  # large number of operations, split the operations into batches and send
  # multiple AddOfflineUserDataJobOperations requests for the SAME job. See
  # https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
  # and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
  # for more information on the per-request limits.
  response = offline_user_data_service.add_offline_user_data_job_operations(
    resource_name: offline_user_data_job_resource_name,
    enable_partial_failure: true,
    operations: build_offline_user_data_job_operations(client),
  )

  # Prints errors if any partial failure error is returned.
  if response.partial_failure_error
    failures = client.decode_partial_failure_error(response.partial_failure_error)
    failures.each do |failure|
      failure.errors.each do |error|
        human_readable_error_path = error
          .location
          .field_path_elements
          .map { |location_info|
            if location_info.index
              "#{location_info.field_name}[#{location_info.index}]"
            else
              "#{location_info.field_name}"
            end
          }.join(" > ")

        errmsg =  "error occured while adding operations " \
          "#{human_readable_error_path}" \
          " with value: #{error.trigger.string_value}" \
          " because #{error.message.downcase}"
        puts errmsg
      end
    end
  end
  puts "The operations are added to the offline user data job."

  unless run_job
    puts "Not running offline user data job #{job_name}, as requested."
    return
  end

  # Issues an asynchronous request to run the offline user data job
  # for executing all added operations.
  response = offline_user_data_service.run_offline_user_data_job(
    resource_name: offline_user_data_job_resource_name
  )
  puts "Asynchronous request to execute the added operations started."
  puts "Waiting until operation completes."

  # Offline user data jobs may take 6 hours or more to complete, so instead of
  # waiting for the job to complete, retrieves and displays the job status
  # once. If the job is completed successfully, prints information about the
  # user list. Otherwise, prints the query to use to check the job again later.
  check_job_status(
    client,
    customer_id,
    offline_user_data_job_resource_name,
  )
end
      
```

### Perl

```perl
sub add_users_to_customer_match_user_list {
  my ($api_client, $customer_id, $run_job, $user_list_resource_name,
    $offline_user_data_job_id, $ad_personalization_consent,
    $ad_user_data_consent)
    = @_;

  my $offline_user_data_job_service = $api_client->OfflineUserDataJobService();

  my $offline_user_data_job_resource_name = undef;
  if (!defined $offline_user_data_job_id) {
    # Create a new offline user data job.
    my $offline_user_data_job =
      Google::Ads::GoogleAds::V26::Resources::OfflineUserDataJob->new({
        type                          => CUSTOMER_MATCH_USER_LIST,
        customerMatchUserListMetadata =>
          Google::Ads::GoogleAds::V26::Common::CustomerMatchUserListMetadata->
          new({
            userList => $user_list_resource_name
          })});

    # Add consent information to the job if specified.
    if ($ad_personalization_consent or $ad_user_data_consent) {
      my $consent = Google::Ads::GoogleAds::V26::Common::Consent->new({});
      if ($ad_personalization_consent) {
        $consent->{adPersonalization} = $ad_personalization_consent;
      }
      if ($ad_user_data_consent) {
        $consent->{adUserData} = $ad_user_data_consent;
      }
      # Specify whether user consent was obtained for the data you are uploading.
      # See https://www.google.com/about/company/user-consent-policy for details.
      $offline_user_data_job->{customerMatchUserListMetadata}{consent} =
        $consent;
    }

    # Issue a request to create the offline user data job.
    my $create_offline_user_data_job_response =
      $offline_user_data_job_service->create({
        customerId => $customer_id,
        job        => $offline_user_data_job
      });
    $offline_user_data_job_resource_name =
      $create_offline_user_data_job_response->{resourceName};
    printf
      "Created an offline user data job with resource name: '%s'.\n",
      $offline_user_data_job_resource_name;
  } else {
    # Reuse the specified offline user data job.
    $offline_user_data_job_resource_name =
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::offline_user_data_job(
      $customer_id, $offline_user_data_job_id);
  }

  # Issue a request to add the operations to the offline user data job.
  # This example only adds a few operations, so it only sends one AddOfflineUserDataJobOperations
  # request. If your application is adding a large number of operations, split
  # the operations into batches and send multiple AddOfflineUserDataJobOperations
  # requests for the SAME job. See
  # https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
  # and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
  # for more information on the per-request limits.
  my $user_data_job_operations = build_offline_user_data_job_operations();
  my $response                 = $offline_user_data_job_service->add_operations(
    {
      resourceName         => $offline_user_data_job_resource_name,
      enablePartialFailure => "true",
      operations           => $user_data_job_operations
    });

  # Print the status message if any partial failure error is returned.
  # Note: The details of each partial failure error are not printed here, you can
  # refer to the example handle_partial_failure.pl to learn more.
  if ($response->{partialFailureError}) {
    # Extract the partial failure from the response status.
    my $partial_failure = $response->{partialFailureError}{details}[0];
    printf "Encountered %d partial failure errors while adding %d operations " .
      "to the offline user data job: '%s'. Only the successfully added " .
      "operations will be executed when the job runs.\n",
      scalar @{$partial_failure->{errors}}, scalar @$user_data_job_operations,
      $response->{partialFailureError}{message};
  } else {
    printf "Successfully added %d operations to the offline user data job.\n",
      scalar @$user_data_job_operations;
  }

  if (!defined $run_job) {
    print
"Not running offline user data job $offline_user_data_job_resource_name, as requested.\n";
    return;
  }

  # Issue an asynchronous request to run the offline user data job for executing
  # all added operations.
  my $operation_response = $offline_user_data_job_service->run({
    resourceName => $offline_user_data_job_resource_name
  });

  # Offline user data jobs may take 6 hours or more to complete, so instead of waiting
  # for the job to complete, this example retrieves and displays the job status once.
  # If the job is completed successfully, it prints information about the user list.
  # Otherwise, it prints, the query to use to check the job status again later.
  check_job_status($api_client, $customer_id,
    $offline_user_data_job_resource_name);
}
      
```

### curl

> [!NOTE]
> **Note:** While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request.   
>
> Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions.   
>
> Key Resources:
>
> - [Using REST](https://developers.google.com/google-ads/api/rest/overview.md.txt)
> - [REST Interface Structure](https://developers.google.com/google-ads/api/rest/design/overview.md.txt)
> - [JSON Field Mappings](https://developers.google.com/google-ads/api/rest/design/json-mappings.md.txt)
> - Consult the [REST API Reference](https://developers.google.com/google-ads/api/reference/rpc/latest/overview) for the specific service and method.

<br />

### Remove individual users using identifiers

To remove individual users:

- Set the `remove` attribute on an
  [`OfflineUserDataJobOperation`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobOperation.md.txt) equal to a
  [`UserData`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserData.md.txt) object.

- Add one or more [`UserIdentifier`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserIdentifier.md.txt) objects to the
  [`user_identifiers[]`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserData.md.txt#user_identifiers%5B%5D) repeated field. A single user
  identifier can be used to remove a user from a list, even if more than one
  identifier was submitted that matches the user.

> [!IMPORTANT]
> **Key Point:** Individual `remove` operations cannot be mixed with `create` operations in a single job (except when a `remove_all` operation is placed first). Running a job that mixes individual `remove` and `create` operations fails with a [`CONFLICTING_OPERATION`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobErrorEnum.OfflineUserDataJobError.md.txt#conflicting_operation) error.

### Check for partial failures

When you add operations to your job using
[`AddOfflineUserDataJobOperations`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobService/AddOfflineUserDataJobOperations.md.txt), you can optionally enable partial
failure by setting the [`enable_partial_failure`](https://developers.google.com/google-ads/api/reference/rpc/v26/AddOfflineUserDataJobOperationsRequest.md.txt#enable_partial_failure) field to `true` in
your [`AddOfflineUserDataJobOperationsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/AddOfflineUserDataJobOperationsRequest.md.txt).

If partial failure is enabled, operations that fail validation are recorded in
the [`partial_failure_error`](https://developers.google.com/google-ads/api/reference/rpc/v26/AddOfflineUserDataJobOperationsResponse.md.txt#partial_failure_error) field in the response, while valid
operations are added to the job. If partial failure is disabled (the default),
then any operation that fails validation causes the entire request to fail. For
more details, visit the [partial failure guide](https://developers.google.com/google-ads/api/docs/best-practices/partial-failures.md.txt).

It's important to check for any `partial_failure_error` in the response when
partial failure is enabled. If all of your operations fail validation, none will
be added to the job, and `partial_failure_error` will contain all of the
operation errors. If you then call [`RunOfflineUserDataJob`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobService/RunOfflineUserDataJob.md.txt), the job
will immediately complete with a `SUCCESS` status because it has no operations
to process.

### Remove all data from the list at once

To remove all users from a list, set `remove_all` to `true` in an
[`OfflineUserDataJobOperation`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobOperation.md.txt), then issue a
[`RunOfflineUserDataJob`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobService/RunOfflineUserDataJob.md.txt) request with the resource name associated
with the `remove_all` operation.

Unlike individual `remove` operations, a `remove_all` operation can be combined
with subsequent `create` operations in the same job, provided `remove_all` is
the first operation in the job. If not, then running the job returns an
[`INVALID_OPERATION_ORDER`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobErrorEnum.OfflineUserDataJobError.md.txt#invalid_operation_order) error. To completely replace the members
of a user list with new members, order the operations in
`AddOfflineUserDataJobOperationsRequest` in this sequence:

1. Set `remove_all` to `true` in an
   [`OfflineUserDataJobOperation`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobOperation.md.txt).

2. For each new member, add a `create` operation, setting their `UserData` in
   an `OfflineUserDataJobOperation`.

`remove_all` operations are executed hourly, and could run for up to 24 hours.

> [!TIP]
> **Tip:** It is generally more efficient to manage membership expirations by setting `membership_life_span` rather than by using the [`OfflineUserDataJobOperation.remove_all`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserDataJobOperation.md.txt#remove_all) field.

### Customer list refresh recommendations

You can retrieve recommendations of type
[`REFRESH_CUSTOMER_MATCH_LIST`](https://developers.google.com/google-ads/api/reference/rpc/v26/Recommendation.md.txt#refresh_customer_match_list_recommendation) to identify customer lists that
haven't been updated in some time. This is especially useful if you're a
third-party advertiser that enables its users to manage customer lists.

For more information on working with recommendations, visit the
[Optimization score and recommendations](https://developers.google.com/google-ads/api/docs/recommendations.md.txt) guide.

## Remove a list

Use the [`UserListService.MutateUserLists`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserListService/MutateUserLists.md.txt) method to submit a
[`remove`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserListOperation.md.txt#remove) operation using the resource name of the user list
you would like to remove.

## Update a list with UserDataService

The [`UserDataService`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserDataService.md.txt) has a limit of 10 operations and 100
total `user_identifiers` per request, so it is a better fit for small updates.
For example, if each of your `UserData` objects has one `UserIdentifier` for
`hashed_email` and another `UserIdentifier` for `hashed_phone_number`, then your
request can contain at most 50 `UserData` objects.

The `UserDataService` contains the `UploadUserData` method, which accepts an
[`UploadUserDataRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/UploadUserDataRequest.md.txt). In addition to the
`customer_id`, the `UploadUserDataRequest` accepts a list of operations to
create contacts and a required field called `customer_match_user_list_metadata`,
which is populated with the resource name of the remarketing list to target.

Begin by creating an `UploadUserDataRequest` instance in which you populate the
`customer_id` and `customer_match_user_list_metadata`:

### Java

```java
// Creates a request to add user data operations to the user list.
String userListResourceName =
    ResourceNames.userList(customerId, userListId);
UploadUserDataRequest.Builder uploadUserDataRequest =
    UploadUserDataRequest.newBuilder()
        .setCustomerId(String.valueOf(customerId))
        .setCustomerMatchUserListMetadata(
            CustomerMatchUserListMetadata.newBuilder()
                .setUserList(userListResourceName)
                .setConsent(
                    Consent.newBuilder()
                        .setAdUserData(ConsentStatus.GRANTED)
                        .setAdPersonalization(ConsentStatus.GRANTED)
                        .build())
                .build());
```

To upload user contact information, set `CrmBasedUserListInfo.upload_key_type`
to `CONTACT_INFO`.

First, add the operations to the `UploadUserDataRequest` object. Each operation
contains a `create` field populated with [`UserData`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserData.md.txt) objects that
hold one or more [`UserIdentifier`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserIdentifier.md.txt) instances. Each
`UserIdentifier` contains one piece of identifying information or can be one of
several different types, each of which is described in the following sections.

To upload customer email addresses, create a new
[`UserDataOperation`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserDataOperation.md.txt) and populate its `create` field with
a `UserData` object. The `UserData` object accepts a list of `user_identifiers`.
Normalize (trim whitespace and convert to lowercase) and SHA-256 hash each email
address before populating the `hashed_email` field:

### Java

```java
ImmutableList<String> EMAILS =
    ImmutableList.of(
        "client1@example.com",
        "client2@example.com",
        " Client3@example.com ");

// Normalize and hash email addresses using the SHA-256 hashing algorithm.
List<UserDataOperation> userDataOperations =
    new ArrayList<>(EMAILS.size());
for (String email : EMAILS) {
  String normalizedEmail = email.trim().toLowerCase();
  UserDataOperation userDataOperation =
      UserDataOperation.newBuilder()
          .setCreate(
              UserData.newBuilder()
                  .addUserIdentifiers(
                      UserIdentifier.newBuilder()
                          .setHashedEmail(toSHA256String(normalizedEmail))
                          .build())
                  .build())
          .build();
  userDataOperations.add(userDataOperation);
}
uploadUserDataRequest.addAllOperations(userDataOperations);
```

Uploading user `address_info` is similar to uploading user email addresses.
However, instead of passing a `hashed_email`, populate the `address_info` field
with an [`OfflineUserAddressInfo`](https://developers.google.com/google-ads/api/reference/rpc/v26/OfflineUserAddressInfo.md.txt) object containing the
user's `first_name`, `last_name`, `country_code`, and `postal_code`. Like email
addresses, `first_name` and `last_name` are considered personally identifiable
information and must be normalized and hashed before uploading.

### Java

```java
String firstName = "Alex";
String lastName = "Quinn";
String countryCode = "US";
String postalCode = "94045";

String normalizedFirstName = firstName.trim().toLowerCase();
String normalizedLastName = lastName.trim().toLowerCase();

UserIdentifier userIdentifierWithAddress =
    UserIdentifier.newBuilder()
        .setAddressInfo(
            OfflineUserAddressInfo.newBuilder()
                // First and last name must be normalized and hashed.
                .setHashedFirstName(toSHA256String(normalizedFirstName))
                .setHashedLastName(toSHA256String(normalizedLastName))
                // Country code and zip code are sent in plaintext.
                .setCountryCode(countryCode)
                .setPostalCode(postalCode)
                .build())
        .build();

UserDataOperation userDataOperation =
    UserDataOperation.newBuilder()
        .setCreate(
            UserData.newBuilder()
                .addUserIdentifiers(userIdentifierWithAddress)
                .build())
        .build();
uploadUserDataRequest.addOperations(userDataOperation);
```

After adding operations to the `UploadUserDataRequest` instance, call the
`uploadUserData` method on the `UserDataServiceClient` to send the request to
the Google Ads API server. You can see if the request was successful by inspecting the
received operations count and upload time in the response object. Keep in mind
that it may take several hours for the list to be populated with members.

### Java

```java
// Creates the user data service client.
try (UserDataServiceClient userDataServiceClient =
    googleAdsClient.getLatestVersion().createUserDataServiceClient()) {
  // Adds operations to the user list based on the user data type.
  UploadUserDataResponse response =
      userDataServiceClient.uploadUserData(uploadUserDataRequest.build());

  // Logs the results. It may take several hours for the list to be
  // populated with members.
  System.out.printf(
      "Received %d operations at %s%n",
      response.getReceivedOperationsCount(),
      response.getUploadDateTime());
}
```

## Switch list targeting level

If you need to switch the level at which your list is targeting, for example
from ad group to campaign level targeting, consult the switching targeting
levels [guide](https://developers.google.com/google-ads/api/docs/remarketing/audience-segments/website-visitors.md.txt#switch-targeting-levels).

## Review list performance

To collect performance data for your audience segments, issue a search request
against the [`ad_group_audience_view`](https://developers.google.com/google-ads/api/fields/v26/ad_group_audience_view.md.txt) or
[`campaign_audience_view`](https://developers.google.com/google-ads/api/fields/v26/campaign_audience_view.md.txt) resource. For
example, you can analyze `metrics.conversions` or `metrics.cost_per_conversion`
to determine if targeting a specific audience segment increases conversions, and
then adjust your [bid modifiers](https://developers.google.com/google-ads/api/docs/targeting/bid-modifiers.md.txt) accordingly.

```sql
SELECT
  ad_group.id,
  ad_group_criterion.criterion_id,
  ad_group_criterion.resource_name,
  metrics.conversions,
  metrics.cost_per_conversion
FROM ad_group_audience_view
WHERE segments.date DURING LAST_30_DAYS
```

We recommend waiting at least two weeks before optimizing bids based on traffic
volume to your account.