> ## 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 DV360 Connector API

> Deliver Customer Match audiences to Google Display & Video 360 over the API, and set up what the DV360 API guide needs

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](#prerequisites) and [set up API access](#set-up-api-access) on this page before you follow the Customer Match delivery guide.

## Choose a guide

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

## Prerequisites

| Prerequisite | Who does it | How often |
| - | - | - |
| [API key](#api-key) | A Narrative admin | Once |
| [Google DV360 Connector installed](#google-dv360-connector-installed) | A Narrative admin | Once |
| [DV360 advertiser linked to Narrative](#dv360-advertiser-linked-to-narrative) | A partner-level user in DV360 | Once per DV360 advertiser |
| [A DV360 profile](#create-a-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](/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 DV360 Connector installed

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

```bash theme={null}
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:

```bash theme={null}
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](/reference/connectors/google-dv360#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](#google-dv360-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://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`.

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

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

```bash theme={null}
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:

```bash theme={null}
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](#get-an-installation-token). To read one:

```bash theme={null}
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:

```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 DV360", "status": "enabled", ...}]}
```

### Remove a profile

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

```bash theme={null}
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:

```bash theme={null}
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`.

## What the connection does

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

### New Customer Match list (`audience_first_party_new`)

The connector creates the list in Display & Video 360 when you create the connection.

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `name` | The list's name. Google requires it to be unique in the account | Any string | The connection ID |
| `description` | The list's description | 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 | None. Required |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `false` |

### Existing Customer Match list (`audience_first_party_existing`)

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `user_list_id` | The list to add members to. The list keeps its own membership duration | The numeric ID of a Customer Match list the profile's account can reach | 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 Display & Video 360, `historical_data_enabled` delivers everything in the dataset when the connection is created. After that, each new snapshot is delivered as it lands.

Every delivery adds members to the 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 missing from it stay in the list until their membership duration ends.

## Delivery notifications

The Google DV360 Connector reports each delivery as an app webhook event. Subscribe a webhook to app `15` 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": 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](/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 DV360 Connector" icon="google" href="/reference/connectors/google-dv360">
    Supported identifiers for DV360
  </Card>

  <Card title="Hashing PII" icon="hashtag" href="/guides/ingestion/hashing-pii">
    Prepare identifiers for DV360
  </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.