> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinterest Ads

> Deliver better ads by syncing conversion events and customer list audiences to Pinterest Ads

## Overview

Manage your conversion tracking by syncing conversion events and promote your pins to a specific Pinterest audience by syncing customer lists from your data warehouse. Deliver more relevant ads, boost marketing ROI, and retarget your most loyal customers.

## Supported syncing

| Sync type | Description | Supported sync modes | API reference |
| - | - | - | - |
| [**Conversion Events**](#syncing-conversion-events) | Sync conversion events from any source to Pinterest Ads | Insert | [Events API](https://developers.pinterest.com/docs/api/v5/events-create/) |
| [**Customer List Audiences**](#syncing-customer-list-audiences) | Sync your PII data from any source to Pinterest Ads customer list audiences | Add, Remove | [Customer Lists API](https://developers.pinterest.com/docs/api/v5/customer_lists-create/) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to Pinterest Ads

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button. Select **Pinterest Ads** and click **Continue**. You can then authenticate Hightouch to Pinterest Ads by selecting **Log in to Pinterest Ads** and logging into your Pinterest Ads account.

Once successful, you will be redirected back to Hightouch to enter your **advertiser account ID** and **conversion access token**.

* **Advertiser account ID**: You can locate your advertiser account ID within your Pinterest business account by navigating to
  the dropdown button on the top right of the page, then **Business Access** > **Ad Accounts**. You can find your ID under your the **Asset name**.

  ![Locate advertiser account ID](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-pinterest-setup.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=725be996ae7e00b2ba6deffd1f8b8fbb)

* **Conversion access token**: If you want to send conversion events to Pinterest Ads, you also need to input a conversion access token. You can create a conversion access token within your Pinterest business account by navigating to the **Ads** dropdown then **Conversions** > **Conversion access token**. Click **Generate new token** and enter the token in Hightouch.

![Create conversion access token](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-pinterest-conversion-access-token.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=c12e5235e17e2f2d054e05f2f125642f)

## Sync configuration

Once you've set up your Pinterest Ads destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and the Pinterest Ads destination you want to sync to.

### Syncing conversion events

Hightouch supports syncing conversion events to Pinterest Ads.

> [!WARNING]
>
> To ensure syncs send each event, your event model must use a truly unique [primary key](https://docs.hightouch.com/getting-started/concepts.md#unique-primary-key-requirement). See the [events syncs](https://docs.hightouch.com/syncs/types-and-modes.md#event-syncs) documentation for more information.

#### Record matching

You can match events from your source to Pinterest Ads using the Event ID.

#### Field mapping

You can use [field mapping](https://docs.hightouch.com/syncs/mapping-data.md) to sync data to the event properties of a Pinterest Ads conversion event. Refer to the [Pinterest Ads developer docs](https://developers.pinterest.com/docs/api/v5/#operation/events/create) for descriptions of each property.
Ensure your model columns' data types match the data types of the fields you want to sync to.

For fields that expect an array , Hightouch automatically converts your row values to arrays if they aren't already. For example, you can map [string model columns](https://docs.hightouch.com/models/creating-models.md#data-types-and-casting) to array type Pinterest Ads fields.

The Pinterest Ads API requires the **Action Source** field, so you must map it to complete your configuration.
**Action Source** is an enumerated field which only accepts the following `string` values:

* "app\_android"
* "app\_ios"
* "web"
* "offline"

#### Handling PII

Pinterest Ads requires some identity information to be normalized and hashed. We support hashing for all fields that require values to be SHA256 hashed. Disabling PII hashing requires you to do this yourself.
If you're handling hashing yourself, make sure that email addresses are in lowercase before hashing, as explained in [Pinterest's documentation](https://developers.pinterest.com/docs/api/v5/#operation/events/create).

#### Cleaning phone numbers

You can select whether Hightouch should clean your phone numbers. By default, Hightouch doesn't clean phone numbers.

Pinterest Ads requires users' phone numbers to be normalized and hashed. The phone number should only include digits with country code, area code, and number without any symbols, letters, spaces, and leading zeros.

If you enable cleaning phone numbers, Hightouch tries to convert the phone number into E.164 format and remove the leading plus (`+`) symbol.

#### Using the test events endpoint

Pinterest Ads provides a [test events endpoint](https://help.pinterest.com/en/business/article/validating-your-set-up-with-event-testing) to validate your set up for conversion events. This endpoint does not affect
production conversion data, and returns warnings and recommendations based on your set up. Syncs can be run using this endpoint and results can be seen by clicking on **Test Events** under the the **Conversions Tab**.

### Syncing customer list audiences

A **customer list audience** is a [customer list that is added to an audience](https://help.pinterest.com/en/business/article/audience-targeting).
Depending on your model query results, Hightouch adds new user records into the Pinterest Ads customer list audience or removes them.

#### User identifiers

To identify which users to add or update in an audience, select model columns and the corresponding Pinterest Ads user fields. You can match on any of the following Pinterest Ads user fields:

* Email
* IDFA
* MAID
* LR\_ID
* DLX\_ID
* Hashed Pinner ID

> [!NOTE]
>
> Emails must be lowercase and can be plain text or hashed using SHA1, SHA256,
> or MD5. MAIDs and IDFAs must be hashed with SHA1, SHA256, or MD5.

> [!TIP]
>
> Increase match rates in Pinterest Ads by enabling [Match Booster](https://docs.hightouch.com/match-booster/overview.md).

> [!NOTE]
>
> If you map an identifier field that contains an array of values, Hightouch automatically fans out each element into a separate record when syncing to Pinterest Ads. Learn more about [array identifier fan-out](https://docs.hightouch.com/syncs/array-identifier-fan-out.md).

#### New audience creation

In your sync configuration, you can tell Hightouch to create a new customer list audience for you. You can optionally assign a custom name to your audience. If no name is provided, Hightouch defaults to using your model name.
To help differentiate the name of your customer list and audience, we save the customer list name as `customer list-{customer list name}` and audience name as `audience-{audience name}`.

The following example screenshot would create a new customer audience list called "Users 1."

![Creating a new customer list audience](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-pinterest-create-new-list.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f70bc83fbfa532e1d1acbae910e7a981)

After creation, the customer list name will be "customer list-Users 1," and the audience name will be "audience-Users 1."

#### Using an existing audience

Instead of creating a new data customer list audience, Hightouch can also sync users to existing audiences that are already populated in your Pinterest Ads account.
The Hightouch UI shows the customer list and audience as a comma-separated string.

In the example screenshot below, the customer list audience shows as "customer list-Users 1, audience-Users 1."

![Using an existing customer list audience](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-pinterest-use-existing-list.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=5b544d3530c502efcb65c90f2b323c05)

#### Field mapping

You can sync columns from your model to the following identifiers in Pinterest:

* Email
* IDFA
* MAID
* LR\_ID
* DLX\_ID
* Hashed Pinner ID

Hightouch [Match Booster](https://docs.hightouch.com/match-booster/overview.md) can help to provide additional identifiers and increase your match rates.

#### Handling PII

Pinterest Ads requires some identity information to be normalized and hashed. Hightouch supports hashing for all user types except for **Email**, since Pinterest Ads doesn't require hashing this field.

Enable PII hashing if you wish for Hightouch to normalize and hash PII fields using a SHA256 hash. Disabling PII hashing requires to do this yourself.

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

### Matched users count

Below only applies to the audiences sync type.

Hightouch retrieves the audience metadata from Pinterest Ads in real-time. The matched number displayed in Hightouch should reflect what you see in Pinterest Ads. Note that the matched numbers are approximated to maintain privacy thresholds. Hightouch takes the matched count to calculate a match rate for your sync, where applicable. The calculation breakdown:

`matched_user_count / # of rows queried in the latest sync run`

The match rate is **not** calculated when:

* syncing to an existing segment because the total number of records to ever be uploaded to the segment is unknown
* removed users from your model is not removed in Pinterest Ads because the matched user count would be inflated in the calculation

Common causes for low match rates:

* Your audience model is too small. Most ad platforms do not display the matched number unless there's at least one thousand matched users to maintain privacy thresholds.
* The upload is still processing. We recommend waiting at least **72 hours** from the first sync run for numbers to settle.
* Your data isn’t cleaned or hashed properly. Hightouch normalizes and hashes your data according to destination requirements, but it’s still good to make sure that the data is as clean as possible. Note that Hightouch cannot clean your data if you opt to hash it yourself. In that case, ensure you follow the data cleaning requirements for Pinterest Ads.

## Common errors

### Delayed syncing

Pinterest takes around 24 hours to fully sync after Hightouch has synced data to their API. You can find more details under **customer list** on [Pinterest's audience targeting help page](https://help.pinterest.com/en/business/article/audience-targeting).

### Smaller audience size

You may notice that the audience size may be smaller than the total number of records synced to Pinterest Ads. This is because [Pinterest filters out
records that don't have a Pinterest account](https://developers.pinterest.com/docs/api/v5/#tag/customer_lists).

### 400 - Invalid request

You may receive a `400 - {"code":1,"message":"Invalid request: {} is not valid under any of the given schemas"}` error message because a row being sent to Pinterest contains a `null` or blank value.

Ensure that mapped fields do not contain any`null` or blank values. You can resolve this error by:

* Filtering these rows in the model's query
* Selecting the [Don't sync null values](https://docs.hightouch.com/syncs/mapping-data.md#dont-sync-null-values) checkbox in of the field mapping configurations.