ACTION_ID: google_ads_sync
NAME: Google Ads: Sync Audience
CATEGORY: Integrations
CREDITS: 0

Add one lead per row to a Google Ads Customer Match list, or remove it
from one. Floqer normalizes and SHA-256 hashes the identifiers before
sending them through Google's Data Manager API.

PREREQUISITE: Google Ads connection. The user must create it in the Floqer
UI (Connections page); an agent cannot. The connection must include Google
Ads access (adwords scope). Older connections without that scope must be
reconnected: the `google_ads_account` options call then returns an error
saying "Reconnect your Google account...". Confirm the connection exists
before configuring.

1. INPUTS

operation (dropdown, required, defaults to ADD)
  Operation. Must be exactly ADD or REMOVE; any other value fails the
  row. Values:
    - { id: "ADD", name: "Add to list" } (default)
    - { id: "REMOVE", name: "Remove from list" }

google_ads_account (dropdown, required)
  Google Ads account. The account that owns the list. Values from
  google_ads_accounts.

manager_account_id (string, optional)
  Manager account ID. The manager (MCC) account ID, set when the
  connected Google user reaches the account through a manager account.

customer_match_list (dropdown, required)
  Customer Match list. The list to sync to. Values from
  google_ads_customer_lists.

email (email, optional)
  Email. The recommended identifier.

phone (string, optional)
  Phone. Must include the country code (E.164, e.g. +14155550100).
  Floqer does not infer a country code, so a number without one is
  skipped.

first_name, last_name, country_code, postal_code (string, optional)
  Name + address identifier. Used only when all four are present.
  country_code is ISO-3166-1 alpha-2 (e.g. US).

data_is_already_hashed (boolean, optional, default false)
  Data is already hashed. Set true when the email / phone / name columns
  already hold SHA-256 hex digests (64 hex characters). Each hash must be
  of the normalized value (email trimmed and lowercased, with dots and
  +tags removed for gmail.com / googlemail.com; phone in E.164; names
  lowercased). With it on, email and phone values that are not 64-char
  hex are dropped. country_code and postal_code are never hashed; keep
  them plain.

consent_ad_user_data (dropdown, optional)
consent_ad_personalization (dropdown, optional)
  Consent: ad user data / ad personalization. Required by Google for
  EEA users. Values: CONSENT_STATUS_UNSPECIFIED (default),
  CONSENT_GRANTED, CONSENT_DENIED. Sent only with ADD. Set
  CONSENT_GRANTED only when the user confirms consent was collected
  (needed for EEA users).

At least one identifier (email, phone, or the full name + address set)
is required per row.

2. OUTPUTS

No referenceable outputs. Check each row's cell in List Rows: complete
when Google accepted the add or remove, or failed with the error
message.

3. HOW TO CONFIGURE

Resolve the dropdowns via Get Action Field Options:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/google_ads_account
       (body: {})
       → accounts the connected Google user can access. `value` is the
         10-digit customer ID. Manager accounts are labelled "(Manager)".

  POST .../options/operation, .../options/consent_ad_user_data,
  .../options/consent_ad_personalization
       (body: {})
       → the allowed ids for these fixed dropdowns.

  POST .../options/customer_match_list
       (body: { "context": { "google_ads_account": "<customer_id>",
                             "manager_account_id": "<mcc_id>" } })
       → Customer Match lists under that account. `value` is the list
         ID. `manager_account_id` is optional; include it when the
         account is reached through a manager account.

Configure Action body:

{
  "inputs": {
    "operation": "ADD",
    "google_ads_account": "<customer_id>",
    "customer_match_list": "<list_id>",
    "email": "{{input.email}}",
    "phone": "{{input.phone}}"
  }
}

Field-by-field:
  - operation            Exactly `ADD` (default) or `REMOVE`.
  - google_ads_account   Customer ID from the `google_ads_account`
                         options call.
  - manager_account_id   Manager (MCC) customer ID. Set it together with
                         the same value in the `customer_match_list`
                         options context.
  - customer_match_list  List ID from the `customer_match_list` options
                         call.
  - email / phone / ...  Map the row's identifier columns.
  - consent_*            Omit to send CONSENT_STATUS_UNSPECIFIED.

4. KEY NOTES

- A row with no usable identifier fails with "No valid Customer Match
  identifier (...)" and Google is not called.
- Identifier normalization happens in Floqer: email is trimmed and
  lowercased (dots and +tags removed for gmail.com and googlemail.com
  only), phone is reduced to E.164. With `data_is_already_hashed` off,
  hashed emails and phones are dropped as invalid, and the row fails if
  nothing else is usable. Hashed names are hashed again, which gives zero
  matches and Google reports no error.
- Google processes the upload asynchronously. A complete cell means
  Google accepted the request; list membership and match rate show up in
  Google Ads later.
- A revoked or expired Google connection fails the row with a reconnect
  error. Transient Google errors are retried (3 attempts per row).
- Lists are created in Google Ads (or from the action in the Floqer UI).
  There is no public API call to create one.

5. WHERE IT FITS IN A WORKFLOW

Pattern: source or import -> email enrichment -> filter (qualified) ->
google_ads_sync (ADD) to build a retargeting audience.
For suppression: filter (customer / unsubscribed) -> google_ads_sync
(REMOVE).

6. WHEN TO USE

Use google_ads_sync to keep a Google Ads Customer Match audience in step
with a Floqer workflow.

Last updated: 2026-09-27.