Setting Up API Access for Google DV360

The Google DV360 Connector API lets an unattended integration deliver hashed identifiers from a Narrative dataset into Customer Match audiences in your Google Display & Video 360 (DV360) 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 DV360 API guide. The guides are listed under Guides on the Google DV360 Connector reference page.

Prerequisites

Prerequisite	Who does it	How often
API key	A Narrative admin	Once
Google DV360 Connector installed	A Narrative admin	Once
DV360 advertiser linked to Narrative	A partner-level user in DV360	Once per DV360 advertiser
A DV360 profile	Your integration, or anyone in the Narrative UI	Once per DV360 advertiser

API key

Create the key under Settings → API Keys with these permissions:

Read and write on datasets and connections
Write on uploads
Read on installations, app_profiles, and apps

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 DV360 Connector installed

The Google DV360 Connector is app 15. Find your installation of it among your destination connectors:

curl -s "https://api.narrative.io/installations?app_categories=destination_connector" \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# find the record with "app_id": 15 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": 15, "company_id": <COMPANY_ID>, "tier_id": "free",
#    "permissions": [{"access": "read", "resource": "app_profiles"}, ...], ...}

Record the installation ID. If no record has "app_id": 15, install the Google DV360 Connector from the Narrative Marketplace.

DV360 advertiser linked to Narrative

Narrative delivers Customer Match audiences to DV360 as an external data partner, so you link your DV360 advertiser to Narrative I/O once, before you create a profile for it. Follow Link your DV360 account in the connector reference. Note the ID of the DV360 advertiser you linked. The API calls it the DV360 customer ID, and you use it to create the profile.

Set up API access

The Customer Match delivery 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
DV360 connector	`https://googledv360cmu.narrativeconnectors.com`	An installation token	Profiles, connection settings schemas

Get an installation token

The DV360 connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from Google DV360 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://googledv360cmu.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "google_dv360_customer_id": <DV360_CUSTOMER_ID>,
#    "name": "Example Brand DV360", "status": "enabled", ...}]}

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

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

Create a profile

A profile ties your Narrative company to one DV360 advertiser, and every connection names the profile it delivers through. Create one profile for each DV360 advertiser you linked, and send its ID as google_dv360_customer_id, a number:

curl -s -X POST https://googledv360cmu.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Brand DV360",
    "description": "Customer Match audiences for Example Brand",
    "google_dv360_customer_id": <DV360_CUSTOMER_ID>
  }'
# → {"id": "<PROFILE_ID>", "created_at": "...",
#    "google_dv360_customer_id": <DV360_CUSTOMER_ID>, "name": "Example Brand DV360",
#    "status": "disabled", "updated_at": "..."}

description is optional. The connector confirms with Google that the DV360 advertiser is linked to Narrative before it saves the profile. A new profile starts out disabled. Record its id, then enable it:

curl -s -X POST https://googledv360cmu.narrativeconnectors.com/profiles/{profile_id}/enable \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "...",
#    "google_dv360_customer_id": <DV360_CUSTOMER_ID>, "name": "Example Brand DV360",
#    "status": "enabled", "updated_at": "..."}

Enable the profile before you create connections on it.

Find your profile

GET /profiles lists every DV360 profile in your company, as shown in Get an installation token. To read one:

curl -s https://googledv360cmu.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "...",
#    "google_dv360_customer_id": <DV360_CUSTOMER_ID>, "name": "Example Brand DV360",
#    "status": "enabled", "updated_at": "..."}

Use a profile whose status is enabled and whose google_dv360_customer_id is the advertiser you want to deliver to. The Narrative API also lists the installation’s 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 DV360", "status": "enabled", ...}]}

Remove a profile

Remove a profile when you no longer deliver to its DV360 advertiser:

curl -s -X DELETE https://googledv360cmu.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → 204, no body

The profile no longer appears in GET /profiles.

Read the connection settings schemas

Each kind of DV360 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://googledv360cmu.narrativeconnectors.com/interfaces

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

The Customer Match delivery 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 DV360 Connector reference page.

Delivery notifications

The Google DV360 Connector reports each delivery as an app webhook event. Subscribe a webhook to app 15 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": 15,
    "url": "https://your-host.example/hooks/narrative",
    "name": "dv360-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 15, "name": "dv360-deliveries",
#    "secret": "<WEBHOOK_SECRET>", "status": "active",
#    "url": "https://your-host.example/hooks/narrative", ...}

Keep the secret to verify that each webhook request comes from Narrative. The connector sends these events:

Event	Sent when
`audience.delivery.completed`	A delivery to a Customer Match audience finishes
`audience.delivery.failed`	A delivery to a Customer Match audience 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 DV360 Connector

Supported identifiers for DV360

Hashing PII

Prepare identifiers for DV360

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 DV360 Connector installed

DV360 advertiser linked to Narrative

Set up API access

Get an installation token

Create a profile

Find your profile

Remove a profile

Read the connection settings schemas

Connection settings

Delivery notifications

Google DV360 Connector

Hashing PII

Connector Interfaces

API Keys

​Prerequisites

​API key

​Google DV360 Connector installed

​DV360 advertiser linked to Narrative

​Set up API access

​Get an installation token

​Create a profile

​Find your profile

​Remove a profile

​Read the connection settings schemas

​Connection settings

​Delivery notifications

​Related content

Google DV360 Connector

Hashing PII

Connector Interfaces

API Keys

Prerequisites

API key

Google DV360 Connector installed

DV360 advertiser linked to Narrative

Set up API access

Get an installation token

Create a profile

Find your profile

Remove a profile

Read the connection settings schemas

Connection settings

Delivery notifications

Related content