Setting Up API Access for Pinterest

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. They connect their account, and you deliver to it the same way. Complete the prerequisites and set up API access on this page before you follow any Pinterest API guide. The guides are listed under Guides on the Pinterest Connector and Pinterest Conversions API Connector reference pages.

Prerequisites

What you need depends on the guide you follow:

Prerequisite	Audiences	Conversion events	Partner invites
API key	✓	✓	✓
Pinterest Connector installed	✓	✓	✓
A connected Pinterest profile	✓	✓
A Pinterest ad account on the profile	✓	✓

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

Pinterest Connector installed

The Pinterest Connector is app 20. Find your installation of it:

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. To deliver to an account someone else owns, invite a partner 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:

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

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.

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.

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 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 shows how to get its ID:

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

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. For a profile a partner connected, send a reconnect invite. 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:

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:

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 and Pinterest Conversions API Connector reference pages.

Delivery notifications

The Pinterest Connector reports each delivery as an app webhook event. Subscribe a webhook to app 20 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": 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:

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

See App subscription for the subscription fields and Verifying deliveries for checking the secret.

Pinterest Connector

Supported identifiers, profiles, and invites

Pinterest Conversions API Connector

The pinterest_conversion_event attribute and its fields

Webhook Event Reference

Subscription fields, delivery payloads, and verification

API Keys

Create and rotate keys for programmatic access

Overview

All connectors

Prerequisites

API key

Pinterest Connector installed

A connected Pinterest profile

Set up API access

Get an installation token

Connect your Pinterest account

Renew the authorization

Find your profile

List your ad accounts

Connection settings

Delivery notifications

Pinterest Connector

Pinterest Conversions API Connector

Webhook Event Reference

API Keys

​Prerequisites

​API key

​Pinterest Connector installed

​A connected Pinterest profile

​Set up API access

​Get an installation token

​Connect your Pinterest account

​Renew the authorization

​Find your profile

​List your ad accounts

​Connection settings

​Delivery notifications

​Related content

Pinterest Connector

Pinterest Conversions API Connector

Webhook Event Reference

API Keys

Prerequisites

API key

Pinterest Connector installed

A connected Pinterest profile

Set up API access

Get an installation token

Connect your Pinterest account

Renew the authorization

Find your profile

List your ad accounts

Connection settings

Delivery notifications

Related content