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

# Google Ads Connector API

> Deliver Customer Match audiences to Google Ads over the API, and set up what the Google Ads API guide needs

The Google Ads Connector API lets an unattended integration deliver hashed identifiers from a Narrative dataset into Customer Match user lists in your Google Ads account. A person signs in once to create an API key, and the integration uses that key from then on.

Complete the [prerequisites](#prerequisites) and [set up API access](#set-up-api-access) on this page before you follow the guide.

## Choose a guide

<CardGroup cols={2}>
  <Card title="Customer Match delivery" icon="users" href="/guides/connector-apis/google-ads/customer-match-api">
    Upload hashed emails and deliver them into a new or existing Customer Match user list.
  </Card>
</CardGroup>

## Prerequisites

| Prerequisite | Who does it | How often |
| - | - | - |
| [API key](#api-key) | A Narrative admin | Once |
| [Google Ads Connector installed](#google-ads-connector-installed) | A Narrative admin | Once |
| [Google Ads account linked to Narrative](#google-ads-account-linked-to-narrative) | A Google Ads user, in Google Ads | Once per Google Ads account |
| [A Google Ads profile](#create-a-profile) | Your integration, or anyone in the Narrative UI | Once per Google Ads account |

### API key

Create the key under **Settings → API Keys** with read and write on `datasets` and `connections`, write on `uploads`, and read on `installations`, `apps`, and `app_profiles`. Add read and write on `webhooks` if you want delivery notifications. See [API Keys](/account-settings/api-keys) for the procedure and the [Permissions Reference](/reference/security/permissions) for what each resource covers.

Create it from a shared team account rather than a personal login, so the integration keeps working when someone changes roles.

### Google Ads Connector installed

The Google Ads Connector is app `14`. Find your installation of it:

```bash theme={null}
curl -s https://api.narrative.io/installations \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# find the record with "app_id": 14 and note its "id"
```

To read that installation on its own:

```bash theme={null}
curl -s https://api.narrative.io/installations/{installation_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id": <INSTALLATION_ID>, "app_id": 14, "company_id": <COMPANY_ID>, "tier_id": "free",
#    "permissions": [{"access": "read", "resource": "app_profiles"}, ...], ...}
```

Record the installation ID. If no record has `"app_id": 14`, install the Google Ads Connector from the Narrative Marketplace.

### Google Ads account linked to Narrative

Narrative delivers to Google Ads as a Customer Match partner, so you link your Google Ads account to Narrative I/O once, before you create a profile for it. In Google Ads, open **Tools → Data manager**, click **Narrative I/O**, and authorize the link request. See [Link your Google Ads account](/reference/connectors/google-ads#link-your-google-ads-account).

The customer ID is the ten-digit number at the top of Google Ads. The API takes it as a number without dashes, so `123-456-7890` becomes `1234567890`.

## Set up API access

The guide talks to two hosts, and each takes its own credential:

| Host | Base URL | Credential | Handles |
| - | - | - | - |
| Narrative API | `https://api.narrative.io` | Your API key | Datasets, uploads, connections, webhooks |
| Google Ads connector | `https://googleads.narrativeconnectors.com` | An installation token | Profiles, connection settings schemas |

### Get an installation token

The Google Ads connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from [Google Ads Connector installed](#google-ads-connector-installed):

```bash theme={null}
curl -s -X POST https://api.narrative.io/installations/{installation_id}/token \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"access_token": "<INSTALLATION_TOKEN>", "access_token_expires_in": 10799,
#    "refresh_token": "<REFRESH_TOKEN>", "refresh_token_expires_in": 86399}
```

Store `access_token` as `$INSTALLATION_TOKEN`. It lasts about three hours, so request a new one at the start of each run of your integration.

Confirm that both hosts answer:

```bash theme={null}
curl -s https://api.narrative.io/company-info/whoami \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id": <COMPANY_ID>}

curl -s https://googleads.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "google_ads_customer_id": <GOOGLE_ADS_CUSTOMER_ID>,
#    "name": "Example Brand", "status": "enabled", ...}]}
```

Send the API key to `api.narrative.io` and the installation token to `googleads.narrativeconnectors.com`.

<Tip>
  API keys contain characters that shells mangle. Read the key from a file or an environment variable rather than pasting it inline.
</Tip>

### Find your profile

A profile ties your Narrative company to one Google Ads customer ID, and every connection names the profile it delivers through. `GET /profiles` lists them all. To read one:

```bash theme={null}
curl -s https://googleads.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "...",
#    "google_ads_customer_id": <GOOGLE_ADS_CUSTOMER_ID>, "name": "Example Brand",
#    "status": "enabled", "updated_at": "..."}
```

Use a profile whose `status` is `enabled` and whose `google_ads_customer_id` is the account you want to deliver to. Record its `id`.

The Narrative API lists the same profiles by name and status:

```bash theme={null}
curl -s https://api.narrative.io/installations/{installation_id}/profiles \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "name": "Example Brand", "status": "enabled", ...}]}
```

### Create a profile

Create one profile for each linked Google Ads account. Send the customer ID as a number without dashes:

```bash theme={null}
curl -s -X POST https://googleads.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Brand",
    "description": "Customer Match lists for Example Brand",
    "google_ads_customer_id": 1234567890
  }'
```

`description` is optional. Record the `id` of the new profile, then enable it:

```bash theme={null}
curl -s -X POST https://googleads.narrativeconnectors.com/profiles/{profile_id}/enable \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "google_ads_customer_id": <GOOGLE_ADS_CUSTOMER_ID>,
#    "name": "Example Brand", "status": "enabled", ...}
```

You can also create the profile in the Narrative UI, under **Installed Apps → Google Ads Connector**. See [Installation](/reference/connectors/google-ads#installation).

### Read the connection settings schemas

Each kind of Google Ads connection has a JSON schema for its `quick_settings`. The connector serves the schemas without a token, and the Narrative API serves the same content:

```bash theme={null}
curl -s https://googleads.narrativeconnectors.com/interfaces

curl -s https://api.narrative.io/apps/14/interfaces \
  -H "Authorization: Bearer $NIO_API_TOKEN"
```

The guide uses `audience_first_party_new` and `audience_first_party_existing`.

## What the connection does

A connection's `quick_settings` choose the interface and say how the connection delivers. The fields depend on the interface.

### New user list (`audience_first_party_new`)

The connector creates the user list in Google Ads when you create the connection.

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `name` | Name of the user list in Google Ads | Any string | The connection ID |
| `description` | Description of the user list | Any string | Empty |
| `membership_duration_days` | How many days a member stays in the list after an upload includes it. Set once, when the list is created | 1 to 540 | 540 |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `false` |

### Existing user list (`audience_first_party_existing`)

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `user_list_id` | The user list to add members to. The list keeps its own membership duration | The numeric ID of a Customer Match user list in the profile's Google Ads account | None. Required |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `false` |

### Existing and new rows

A connection delivers every snapshot written to the dataset after the connection is created. The `historical_data_enabled` quick setting decides whether the connection also delivers data that was already in the dataset when you created it:

* With `historical_data_enabled` set to `true`, the connection first delivers data already in the dataset, then keeps delivering new snapshots as they land.
* With `historical_data_enabled` set to `false`, the connection delivers only snapshots written after it was created.

How far back the first delivery reaches depends on the connector, and each connector's guide states it.

For Google Ads, `historical_data_enabled` delivers the dataset's snapshots from the 30 days before the connection was created. After that, each new snapshot is delivered as it lands.

Every delivery adds members to the user list, and the connection never removes them. A member leaves the list when its membership duration runs out. When you overwrite the dataset, the connection adds the rows in the new snapshot, and members that are missing from it stay in the list until their membership duration ends.

## Delivery notifications

The Google Ads Connector reports each delivery as an app webhook event. Subscribe a webhook to app `14` to receive them:

```bash theme={null}
curl -s -X POST https://api.narrative.io/webhooks \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook_subscription_app",
    "app_id": 14,
    "url": "https://your-host.example/hooks/narrative",
    "name": "google-ads-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 14, "name": "google-ads-deliveries",
#    "secret": "<WEBHOOK_SECRET>", "status": "active",
#    "url": "https://your-host.example/hooks/narrative", ...}
```

Keep the `secret` to verify each delivery. The connector sends these events:

| Event | Sent when |
| - | - |
| `audience.delivery.completed` | A delivery to a Customer Match user list finishes |
| `audience.delivery.failed` | A delivery to a Customer Match user list fails |

Read a subscription with `GET /webhooks/{webhook_id}`, and stop the notifications with `DELETE /webhooks/{webhook_id}`. See [App subscription](/reference/webhooks/event-reference#app-subscription) for the subscription fields and [Verifying deliveries](/reference/webhooks/event-reference#verifying-deliveries) for checking the secret.

***

## Related content

<CardGroup cols={2}>
  <Card title="Google Ads Connector" icon="google" href="/reference/connectors/google-ads">
    Supported identifiers and audience membership duration
  </Card>

  <Card title="Hashing PII" icon="hashtag" href="/guides/ingestion/hashing-pii">
    Prepare identifiers for Google Ads
  </Card>

  <Card title="Connector Interfaces" icon="plug" href="/concepts/data-activation/connector-interfaces">
    Why a dataset connects to an interface rather than a connector
  </Card>

  <Card title="API Keys" icon="key" href="/account-settings/api-keys">
    Create and rotate keys for programmatic access
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.