> For the complete documentation index, see [llms.txt](https://documentation.freshpaint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/pinterest-ads/pinterest-ads-reference.md).

# Pinterest Ads Reference

## Destination Info

* Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls
* Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode)
* Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration.md)
* Refer to this destination as **pinterest-ads** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object)
  * If you've configured multiple Ad Account IDs, you can choose a specific one by suffixing the Ad Account ID, such as: **`pinterest-ads::1234123456`**. You can retrieve this value from the Pinterest Ads configuration page for the Ad Account ID of interest.
* Connection Modes:

<table><thead><tr><th width="200.33333333333331" align="right"></th><th data-type="checkbox">Client-side</th><th data-type="checkbox">Server-side</th></tr></thead><tbody><tr><td align="right">Web</td><td>false</td><td>true</td></tr><tr><td align="right">Mobile</td><td>false</td><td>true</td></tr><tr><td align="right">Server</td><td>false</td><td>true</td></tr></tbody></table>

This is a reference document for the Pinterest Ads destination. For information on how to set up this integration, see the [Pinterest Ads Quick Start Guide](/integrations/destinations/direct-response-ads/pinterest-ads/pinterest-ads-quick-start-guide.md).

## Events

When you send an event (with a valid event name) to the Pinterest Ads destination from Freshpaint, Freshpaint will create an event in the Pinterest Ads conversion manager by sending requests to the Pinterests conversion API.

## Track Events

When you send an event to the Pinterest Ads destination, you can track conversions from your ads based on those events.

Below are the Required, Recommended, and Optional properties which are mapped to the Pinterest Ads request:

### Valid Event Names

The event name must be one of the below events, matching symbols, case, and whitespace.

* `add_to_cart`
* `checkout`
* `custom`
* `lead`
* `page_visit`
* `search`
* `signup`
* `view_category`
* `watch_video`

### Valid Action Sources

By default if no action source is provided we will assume web, otherwise one of the below sources must be sent:

* `app_android`
* `app_ios`
* `web`
* `offline`

### Property Table

{% hint style="info" %}
The following event properties are **required** in order to attribute events to specific ads, and if in HIPAA mode, must be selected in the Required Properties Allow List.
{% endhint %}

<table data-header-hidden data-full-width="true"><thead><tr><th width="165"></th><th width="164"></th><th width="103"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Freshpaint property</strong></td><td><strong>Pinterest Ads</strong><br><strong>parameter</strong></td><td><strong>Type</strong></td><td><strong>Requirement</strong></td><td><strong>Description</strong></td></tr><tr><td><code>$epik</code></td><td><code>click_id</code></td><td>string</td><td>Recommended</td><td>The unique identifier stored in the _epik cookie on your domain or &#x26;epik= query parameter in the URL. This acts as the click ID.</td></tr><tr><td><code>$event_name</code></td><td><code>event_name</code></td><td>string</td><td>Required (always sent)</td><td>The event name sent to Pinterest. This must be a valid event name as <a href="#valid-event-names">listed here</a>.</td></tr><tr><td><code>action_source</code></td><td><code>action_source</code></td><td>string</td><td>Recommended</td><td>The source of the event. This must be a valid source as<a href="#valid-action-sources"> listed here</a>.</td></tr><tr><td><code>email</code></td><td><code>em</code></td><td>string</td><td>Recommended for view-through conversion attribution</td><td>Hashed email of user who initiated the event.</td></tr><tr><td><code>$ip</code></td><td><code>client_ip_address</code></td><td>string</td><td>Recommended for view-through conversion attribution</td><td>IP address of user who initiated the event.</td></tr><tr><td><code>$user_agent</code></td><td><code>client_user_agent</code></td><td>string</td><td>Recommended for view-through conversion attribution</td><td>User agent from the browser of the user who initiated the event.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/pinterest-ads/pinterest-ads-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.