> ## 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.

# Setting Up API Access for Google Ads

> Prerequisites and API access every Google Ads Connector 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 any Google Ads API guide. The guides are listed under **Guides** on the [Google Ads Connector](/reference/connectors/google-ads.md#guides) reference page.

## 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.md) for the procedure and the [Permissions Reference](/reference/security/permissions.md) 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.md#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.

### 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 [Setting Up the Google Ads Connector](/guides/connectors/google/setting-up-google-ads.md).

### 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`.

## Connection settings

For the `quick_settings` each connection accepts and how a delivery treats existing and new rows, see **API connection settings** on the [Google Ads Connector](/reference/connectors/google-ads.md#api-connection-settings) reference page.

## 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.md#app-subscription) for the subscription fields and [Verifying deliveries](/reference/webhooks/event-reference.md#verifying-deliveries) for checking the secret.

***

## Related content

> **[Google Ads Connector](/reference/connectors/google-ads.md)**
>
> Supported identifiers and audience membership duration

> **[Hashing PII](/guides/ingestion/hashing-pii.md)**
>
> Prepare identifiers for Google Ads

> **[Connector Interfaces](/concepts/data-activation/connector-interfaces.md)**
>
> Why a dataset connects to an interface rather than a connector

> **[API Keys](/account-settings/api-keys.md)**
>
> Create and rotate keys for programmatic access


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