> ## 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. # Pinterest Connector API > Deliver audiences and conversion events to your Pinterest ad account over the API, invite partners to connect their accounts, and set up what every Pinterest 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/connector-apis/pinterest/connect-account-api). 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 of the guides. ## Choose a guide Upload hashed emails and deliver them into a new or existing Pinterest audience. Upload conversion events and send them to the Pinterest Conversions API. 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](#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) 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. ### 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/connector-apis/pinterest/connect-account-api) 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": "", "access_token_expires_in": 10799, # "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": "", "company_id": 1234, # "name": "Example Brand", "status": "enabled", # "user_account": {"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. In Narrative, go to **Installed Apps → Pinterest Connector**. In the **Profiles** tab, click **Add profile**, enter a profile name, and click **Create profile**. 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](/reference/connectors/pinterest#installation) 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=&redirect_uri=https%3A%2F%2Fpinterest.narrativeconnectors.com%2Foauth%2Fcallback&response_type=code&scope=user_accounts:read,ads:read,ads:write&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": "", "company_id": 1234, "name": "Example Brand", # "status": "enabled", # "user_account": {"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/connector-apis/pinterest/connect-account-api#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": "", "name": "Example Brand Advertising"}, # {"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": "", "name": "Example Brand Advertising"}], # "bookmark": ""} curl -s "https://pinterest.narrativeconnectors.com/profiles/{profile_id}/ad-accounts?page_size=1&bookmark=" \ -H "Authorization: Bearer $INSTALLATION_TOKEN" # → {"ad_accounts": [{"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 ` - `. 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: ```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": "", "app_id": 20, "name": "pinterest-deliveries", # "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#app-subscription) for the subscription fields and [Verifying deliveries](/reference/webhooks/event-reference#verifying-deliveries) for checking the secret. *** ## Related content Supported identifiers, profiles, and invites The `pinterest_conversion_event` attribute and its fields Subscription fields, delivery payloads, and verification Create and rotate keys for programmatic access This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.