Setting Up API Access for Google Ads

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 and 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 page.

Prerequisites

Prerequisite	Who does it	How often
API key	A Narrative admin	Once
Google Ads Connector installed	A Narrative admin	Once
Google Ads account linked to Narrative	A Google Ads user, in Google Ads	Once per Google Ads account
A Google Ads 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 for the procedure and the Permissions Reference 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:

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:

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

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:

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.

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:

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:

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:

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:

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.

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:

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

Delivery notifications

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

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 for the subscription fields and Verifying deliveries for checking the secret.

Google Ads Connector

Supported identifiers and audience membership duration

Hashing PII

Prepare identifiers for Google Ads

Connector Interfaces

Why a dataset connects to an interface rather than a connector

API Keys

Create and rotate keys for programmatic access

Overview

All connectors

Prerequisites

API key

Google Ads Connector installed

Google Ads account linked to Narrative

Set up API access

Get an installation token

Find your profile

Create a profile

Read the connection settings schemas

Connection settings

Delivery notifications

Google Ads Connector

Hashing PII

Connector Interfaces

API Keys

​Prerequisites

​API key

​Google Ads Connector installed

​Google Ads account linked to Narrative

​Set up API access

​Get an installation token

​Find your profile

​Create a profile

​Read the connection settings schemas

​Connection settings

​Delivery notifications

​Related content

Google Ads Connector

Hashing PII

Connector Interfaces

API Keys

Prerequisites

API key

Google Ads Connector installed

Google Ads account linked to Narrative

Set up API access

Get an installation token

Find your profile

Create a profile

Read the connection settings schemas

Connection settings

Delivery notifications

Related content