> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads

> Push contacts into Google Ads Customer Match user lists for ad targeting and remarketing

Google Ads Customer Match lets you target ads to a custom list of contacts based on first-party data. The Cargo integration lets you create Customer Match user lists, push contacts into them, remove contacts, and pull size and match-rate metrics — all from your workflows.

## Authentication

Connect to Google Ads using OAuth.

<Info>
  The signed-in Google account must have access to the Google Ads accounts you want to push audiences into. Cargo requests the `https://www.googleapis.com/auth/adwords` scope and only stores an encrypted refresh token — Google handles access-token refresh.
</Info>

<Warning>
  Customer Match requires a Google Ads developer token with Customer Match access. New developer tokens may need to be approved by Google before they can upload Customer Match data — see [Get started with Customer Match](https://developers.google.com/google-ads/api/docs/remarketing/audience-segments/customer-match/get-started) for the current process.
</Warning>

***

## Google Ads actions

### Create Audience

Create a new CRM-based Customer Match user list on a Google Ads account.

**Configuration**

| Field                          | Description                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------- |
| **Ad account**                 | Google Ads customer ID (10 digits, no dashes), e.g. `1234567890`             |
| **Audience name**              | Display name for the new user list                                           |
| **Description**                | Optional description                                                         |
| **Membership lifespan (days)** | How long a member remains in the list. Max 540 days for CRM-based user lists |

**Returns**

The newly created `userListId`, plus the full `resourceName`, the `name`, and the `customerId`.

<Tip>
  CRM-based user lists are the only Customer Match list type that accepts hashed customer data via the API. You'll see the new list in the Google Ads UI under **Tools → Audience manager → Customer lists**.
</Tip>

### Add Contact to Audience

Add a single contact to a Customer Match user list. At least one identifier (email, phone, mobile advertising ID, or full address) is required.

**Configuration**

| Field                         | Description                                                             |
| ----------------------------- | ----------------------------------------------------------------------- |
| **Ad account**                | Google Ads customer ID                                                  |
| **Audience**                  | Customer Match user list to add the contact to                          |
| **Email**                     | Lowercased and SHA-256 hashed automatically before being sent to Google |
| **Phone number**              | E.164 format (e.g. `+15551234567`); SHA-256 hashed automatically        |
| **Mobile advertising ID**     | Optional IDFA or GAID                                                   |
| **First name**, **Last name** | Lowercased and SHA-256 hashed automatically                             |
| **Country code**              | ISO 3166-1 alpha-2 (e.g. `US`)                                          |
| **Postal code**               | Optional, paired with country code                                      |

<Warning>
  At least one identifier (email, phone, mobile ID, or a full address — first name + last name + country code + postal code) is required.
</Warning>

<Info>
  Cargo lowercases and SHA-256 hashes emails, phone numbers, and names before sending them to Google, as required by the Customer Match API. You only need to provide the raw value — the hashing happens automatically.
</Info>

**How it works under the hood**

Each call creates an `OfflineUserDataJob` of type `CUSTOMER_MATCH_USER_LIST`, adds a single create operation with the hashed identifiers, and runs the job. Google processes the upload asynchronously — there is no synchronous "added/not added" response.

### Remove Contact from Audience

Remove a contact from a Customer Match user list by email.

**Configuration**

| Field          | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| **Ad account** | Google Ads customer ID                                                  |
| **Audience**   | Customer Match user list to remove the contact from                     |
| **Email**      | Lowercased and SHA-256 hashed automatically before being sent to Google |

<Tip>
  Only contacts that were added with the same hashed email are removed. If a contact was added with a different identifier (phone, mobile ID, address), removing by email will not affect them.
</Tip>

### Create Report

Fetch size and match-rate metrics for a Customer Match user list.

**Configuration**

| Field          | Description                           |
| -------------- | ------------------------------------- |
| **Ad account** | Google Ads customer ID                |
| **Audience**   | Customer Match user list to report on |

**Returns**

| Field                 | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| `userListId`          | The user list ID                                                  |
| `resourceName`        | The full resource name (`customers/{cid}/userLists/{id}`)         |
| `sizeForDisplay`      | Estimated number of matched members for Display Network targeting |
| `sizeForSearch`       | Estimated number of matched members for Search Network targeting  |
| `matchRatePercentage` | Google's estimated match rate, as a percentage                    |

<Info>
  Google populates match data asynchronously after you push records into a list. New lists typically take 24–48 hours before metrics show meaningful values, and a list needs at least 1,000 members before Google reveals its match rate.
</Info>

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead retargeting" icon="bullseye">
    Sync engaged contacts (MQLs, trial signups, demo requests) into a user list and retarget them across Google Search, YouTube, and the Display Network.
  </Accordion>

  <Accordion title="Customer remarketing" icon="users">
    Push your existing customers into a user list to drive expansion campaigns, or build lookalike (Similar) audiences off them.
  </Accordion>

  <Accordion title="Suppression lists" icon="user-slash">
    Keep a user list of customers or unsubscribed contacts in sync, then exclude it from campaigns to avoid wasting spend on people you already converted.
  </Accordion>

  <Accordion title="Match-rate monitoring" icon="chart-line">
    Use **Create Report** in a scheduled workflow to track audience match rates over time and alert when they drop.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Provide as many identifiers as possible** — Google matches on any of email, phone, mobile ID, or full address. The more identifiers per contact, the higher the match rate.
2. **Send raw values, not pre-hashed** — Cargo normalizes (lowercase, trim, E.164 for phone) and SHA-256 hashes for you. Sending already-hashed data will skip the normalization step and lower your match rate.
3. **Use full addresses, not partials** — When supplying address fields, include first name, last name, country code, and postal code together. Partial addresses are dropped by Google.
4. **Wait before reading match rates** — Schedule **Create Report** at least 24 hours after pushing records. Lists below 1,000 members will return a placeholder match rate until they cross the threshold.
5. **Remove with the same identifier you added** — Google only removes contacts whose hashed identifier matches. If a contact was added with phone + address, removing by email alone won't take them out of the list.

***

## Limitations

* **Customer Match API migration**: Google announced that as of April 1, 2026, the `OfflineUserDataJobService` path used by this integration is being deprecated in favor of the new **Data Manager API**. Developer tokens that have been actively used for Customer Match uploads continue to work, but tokens that have been inactive for 180+ days will be blocked. See the [Google Ads Developer Blog](https://ads-developers.googleblog.com/2026/03/changes-to-customer-match-support-in.html) for details. Long-term, this integration will need to be migrated to the Data Manager API.
* **Manager (MCC) accounts**: this integration sets the `login-customer-id` header to the same value as the customer being pushed to. For accounts under a Manager (MCC) account, you may need to use the direct (non-manager) customer ID rather than the MCC ID.
* **One contact per action call**: each `Add Contact to Audience` call creates its own offline user data job. For very high-volume syncs (tens of thousands of records per minute), consider batching upstream — Google rate-limits job creation per customer.