Pinterest Connector API - Narrative I/O Knowledge Base

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 of the guides.

Choose a guide

Audience delivery

Upload hashed emails and deliver them into a new or existing Pinterest audience.

Conversion events

Upload conversion events and send them to the Pinterest Conversions API.

Invite a partner

Send an invite link to someone who manages another Pinterest account, so you can deliver audiences and conversion events to it.

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.

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.

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 audience (`audience_first_party_new`)

The connector creates a customer list and an audience on it in Pinterest when you create the connection.

Field	What it does	Allowed values	Default
`ad_account_id`	The ad account the audience is created in	An ad account the profile can reach	None. Required
`audience_name`	The name of the audience and its customer list	Up to 500 characters	None. Required
`audience_description`	The audience’s description	Up to 10,000 characters	None
`write_mode`	How each delivery changes the audience: `overwrite` replaces its members, `append` adds to them	`overwrite`, `append`	`overwrite`
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

Existing audience (`audience_first_party_existing`)

Field	What it does	Allowed values	Default
`ad_account_id`	The ad account that holds the audience	An ad account the profile can reach	None. Required
`audience_id`	The audience to deliver to	The ID of a customer list audience in that ad account	None. Required
`write_mode`	How each delivery changes the audience	`overwrite`, `append`	`overwrite`
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

The connection keeps the write_mode it was created with.

Conversion events (`conversion_events`)

Field	What it does	Allowed values	Default
`test_mode_enabled`	Sends events to Pinterest as test events	`true`, `false`	`false`
`historical_data_enabled`	Whether the connection also sends events already in the dataset	`true`, `false`	`false`

Each event names its ad account in pinterest_ad_account_id, so the connection has no ad account setting. The connection sends events up to 7 days old.

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 Pinterest, historical_data_enabled delivers the dataset’s snapshots from the 30 days before the connection was created, as one delivery. After that, each new snapshot is delivered as it lands. What an audience delivery does depends on write_mode:

append uploads the delivery’s members into the audience’s customer list. Members stay in the list.
overwrite uploads the delivery’s members into a new customer list named <audience name> - <yyyy-mm-dd>. Once Pinterest marks the new list ready, the audience switches to it, so the audience holds only the members of the latest delivery. Earlier customer lists stay in the ad account.

An overwrite connection replaces the audience with each snapshot, so pair it with a dataset whose own write_mode is overwrite. Each snapshot of that dataset holds the full audience. A conversion connection sends each event in each snapshot it delivers. Uploading the same events again in a new snapshot sends them again.

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.