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

> Prerequisites and API access every Pinterest Connector API guide needs

The Pinterest Connector API lets an unattended integration deliver hashed identifiers into audiences in your Pinterest ad account and send conversion events to the Pinterest Conversions API. You sign in to Narrative once to create an API key, and you connect your Pinterest account once. The integration works from the API key after that.

To deliver to a Pinterest ad account that someone else owns, such as a client's, send that person a [partner invite](/guides/connectors/pinterest/connect-account-api.md). They connect their account, and you deliver to it the same way.

Complete the [prerequisites](#prerequisites) and [set up API access](#set-up-api-access) on this page before you follow any Pinterest API guide. The guides are listed under **Guides** on the [Pinterest Connector](/reference/connectors/pinterest.md#guides) and [Pinterest Conversions API Connector](/reference/connectors/pinterest-conversions-api.md#guides) reference pages.

## Prerequisites

What you need depends on the guide you follow:

| Prerequisite | Audiences | Conversion events | Partner invites |
| - | :-: | :-: | :-: |
| [API key](#api-key) | ✓ | ✓ | ✓ |
| [Pinterest Connector installed](#pinterest-connector-installed) | ✓ | ✓ | ✓ |
| [A connected Pinterest profile](#a-connected-pinterest-profile) | ✓ | ✓ | |
| [A Pinterest ad account on the profile](#list-your-ad-accounts) | ✓ | ✓ | |

### API key

Create the key under **Settings → API Keys** with read and write on `datasets` and `connections`, write on `uploads`, and read on `installations`. 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.

### Pinterest Connector installed

The Pinterest Connector is app `20`. 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": 20 and note its "id"
```

Record the installation ID. If no record has `"app_id": 20`, install the Pinterest Connector from the Narrative Marketplace.

### A connected Pinterest profile

A connector profile holds the Pinterest authorization that every delivery uses. One profile reaches every ad account that the approving Pinterest user can access.

To deliver to your own Pinterest ad account, create a profile and approve Narrative on Pinterest once, as described in [Connect your Pinterest account](#connect-your-pinterest-account). To deliver to an account someone else owns, [invite a partner](/guides/connectors/pinterest/connect-account-api.md) instead. The partner's approval creates the profile.

## Set up API access

The guides talk 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 |
| Pinterest connector | `https://pinterest.narrativeconnectors.com` | An installation token | Profiles, ad accounts, audiences, audience status, invites, Pinterest authorization |

### Get an installation token

The Pinterest connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from [Pinterest Connector installed](#pinterest-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": 1234}

curl -s https://pinterest.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "company_id": 1234,
#    "name": "Example Brand", "status": "enabled",
#    "user_account": {"id": "<PINTEREST_USER_ID>", "business_name": "Example Brand, Inc.",
#                     "username": "examplebrand"},
#    "token_expires_at": "2026-11-08T13:25:50Z", ...}]}
```

Send the API key to `api.narrative.io` and the installation token to `pinterest.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.

### Connect your Pinterest account

Connect your Pinterest account once. Every delivery after that runs from your API key.

**1. Create a profile**

In Narrative, go to **Installed Apps → Pinterest Connector**. In the **Profiles** tab, click **Add profile**, enter a profile name, and click **Create profile**.

**2. Approve Narrative on Pinterest**

Click **Connect to Pinterest**, sign in to the Pinterest account that can reach your ad accounts, and approve Narrative. The profile shows **Connected** once Pinterest confirms.

[Setting Up the Pinterest Connector](/guides/connectors/pinterest/setting-up.md) covers these steps in more detail.

To approve Narrative from your integration instead of clicking **Connect to Pinterest**, request an authorization URL for the profile. [Find your profile](#find-your-profile) shows how to get its ID:

```bash theme={null}
curl -s -X POST https://pinterest.narrativeconnectors.com/profiles/{profile_id}/connect \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"url": "https://www.pinterest.com/oauth/?client_id=<CLIENT_ID>&redirect_uri=https%3A%2F%2Fpinterest.narrativeconnectors.com%2Foauth%2Fcallback&response_type=code&scope=user_accounts:read,ads:read,ads:write&state=<STATE>",
#    "expires_at": "2026-10-04T15:32:28.520261Z"}
```

Open the `url` in a browser before `expires_at`, sign in to Pinterest with a login that can reach your ad accounts, and approve Narrative's request to read and manage your ads. The profile then uses your Pinterest authorization. [Find your profile](#find-your-profile) to check `user_account` and `token_expires_at`.

#### Renew the authorization

A profile's Pinterest authorization lasts until the profile's `token_expires_at`. Renew it before that date to keep deliveries running. Send the same `POST /profiles/{profile_id}/connect` request, open the new `url`, and approve Narrative again with the same Pinterest login. In Narrative, the **Update token** button on the profile does the same. The profile keeps its ID and connections.

### Find your profile

`GET /profiles` lists every Pinterest profile in your company. To read one:

```bash theme={null}
curl -s https://pinterest.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "company_id": 1234, "name": "Example Brand",
#    "status": "enabled",
#    "user_account": {"id": "<PINTEREST_USER_ID>", "business_name": "Example Brand, Inc.",
#                     "username": "examplebrand"},
#    "token_expires_at": "2026-11-08T13:25:50Z", ...}
```

Use a profile whose `status` is `enabled`. `user_account` shows the Pinterest user the profile acts as, and `token_expires_at` shows when its Pinterest authorization runs out. To renew it before that date, see [Renew the authorization](#renew-the-authorization). For a profile a partner connected, send a [reconnect invite](/guides/connectors/pinterest/connect-account-api.md#re-authorize-a-profile). Record the profile `id`.

### List your ad accounts

Audiences and conversion events go to a Pinterest ad account. List the ad accounts the profile can reach:

```bash theme={null}
curl -s https://pinterest.narrativeconnectors.com/profiles/{profile_id}/ad-accounts \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"ad_accounts": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Brand Advertising"},
#                    {"id": "<AD_ACCOUNT_ID>", "name": "Example Brand Retail"}],
#    "bookmark": null}
```

To page through a long list, set `page_size` and pass the `bookmark` from each response to get the next page:

```bash theme={null}
curl -s "https://pinterest.narrativeconnectors.com/profiles/{profile_id}/ad-accounts?page_size=1" \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"ad_accounts": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Brand Advertising"}],
#    "bookmark": "<BOOKMARK>"}

curl -s "https://pinterest.narrativeconnectors.com/profiles/{profile_id}/ad-accounts?page_size=1&bookmark=<BOOKMARK>" \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"ad_accounts": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Brand Retail"}],
#    "bookmark": null}
```

A `null` bookmark means you have the last page. Record the `id` of the ad account you want to deliver to.

## Connection settings

For the `quick_settings` each connection accepts and how a delivery treats existing and new rows, see **API connection settings** on the [Pinterest Connector](/reference/connectors/pinterest.md#api-connection-settings) and [Pinterest Conversions API Connector](/reference/connectors/pinterest-conversions-api.md#api-connection-settings) reference pages.

## Delivery notifications

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

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

| Event | Sent when |
| - | - |
| `audience.delivery.completed` | A delivery to a Pinterest audience finishes |
| `audience.delivery.failed` | A delivery to a Pinterest audience fails |
| `conversion.delivery.completed` | A delivery of conversion events finishes |
| `conversion.delivery.failed` | A delivery of conversion events fails |

Read a subscription with `GET /webhooks/{webhook_id}`, or list all of them with `GET /webhooks`. To stop the notifications, delete the subscription:

```bash theme={null}
curl -s -X DELETE https://api.narrative.io/webhooks/{webhook_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {}
```

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

> **[Pinterest Connector](/reference/connectors/pinterest.md)**
>
> Supported identifiers, profiles, and invites

> **[Pinterest Conversions API Connector](/reference/connectors/pinterest-conversions-api.md)**
>
> The `pinterest_conversion_event` attribute and its fields

> **[Webhook Event Reference](/reference/webhooks/event-reference.md)**
>
> Subscription fields, delivery payloads, and verification

> **[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.