Pinterest Conversions API
Send server-side conversion events to Pinterest for attribution and ad optimization via the Conversions API. Server-side events provide more reliable measurement data and are not affected by browser ad blockers or cookie restrictions.
Prerequisites
- A Pinterest Business account
- Your Pinterest Ad Account ID
- Access to the Pinterest Marketing API
Authentication
Pinterest Conversions API uses OAuth 2.0.
- Click Connect with OAuth in Zeotap
- Sign in with your Pinterest Business account
- Authorize the requested permissions
OAuth scopes: ads:write, ads:read.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Ad Account ID | Text | Yes | Your Pinterest Ad Account ID |
| Conversion Tag ID | Text | No | Optional conversion tag ID for event attribution |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Insert | Yes |
| Update | — |
| Upsert | — |
| Mirror | — |
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | — |
| Mirror | — |
| Upsert | — |
Features
| Feature | Supported |
|---|---|
| Field Mapping | Yes |
| Schema Introspection | No |
Required Mapping Fields
| Field | Description |
|---|---|
event_name | The conversion event type (e.g., checkout, add_to_cart, page_visit) |
email or hashed_email | User identifier for PII matching. Provide either a raw email (auto-hashed by Zeotap) or a pre-hashed SHA256 email |
Default Destination Fields
Event
| Field | Description |
|---|---|
event_name | The conversion event type |
event_time | Unix timestamp of the event |
User Data
| Field | Description |
|---|---|
email | User email address (auto-hashed before sending) |
hashed_email | Pre-hashed SHA256 email (passed through without re-hashing) |
phone | User phone number (auto-hashed before sending) |
hashed_phone | Pre-hashed SHA256 phone number (passed through without re-hashing) |
Custom Data
| Field | Description |
|---|---|
value | Monetary value of the event |
currency | ISO 4217 currency code (e.g., USD, EUR) |
order_id | Your unique order or transaction identifier |
content_ids | Product or content IDs associated with the event |
How It Works
Zeotap reads rows from your model query and applies field mapping to transform your data into Pinterest’s Conversions API format.
PII hashing: Raw user data fields (email, phone) are automatically normalized and hashed with SHA256 per Pinterest’s requirements before being sent. Pre-hashed fields (hashed_email, hashed_phone) are passed through without re-hashing.
Batching: Events are batched up to 1,000 per API call to POST /v5/ad_accounts/{ad_account_id}/events. For syncs with more than 1,000 events, Zeotap automatically splits them into multiple API calls.
Action source: All events are sent with action_source set to web by default.
Supported Event Types
Pinterest recognizes the following standard conversion events:
checkoutadd_to_cartpage_visitsignupleadsearchview_categorywatch_videocustom
Custom event names are also supported.
Rate Limits
- 1,000 events per API call — Zeotap automatically batches events to stay within this limit
- Pinterest Marketing API rate limits apply based on your application’s access tier
Troubleshooting
Invalid Ad Account ID
Verify your Ad Account ID in Pinterest Ads Manager settings. The ID should be numeric.
Permission denied
Ensure the authenticated Pinterest user has access to the ad account with conversion tracking permissions. The OAuth scopes ads:write and ads:read are required.
Events not appearing
Conversion events may take several hours to appear in Pinterest reporting. Verify that your conversion tag is active and correctly configured.
Token expired
Pinterest OAuth tokens have a limited lifetime. Zeotap automatically refreshes tokens when refresh credentials are available. If authentication fails, reconnect via OAuth.