Server-side events · Platform reference
Pinterest Conversions API: events, fields and dedup rules
The Pinterest Conversions API (API v5) takes batches of web, app and offline events at /v5/ad_accounts/{ad_account_id}/events, usually alongside the Pinterest Tag. Events arrive but don't attribute when user_data is thin (no hashed email, no IP plus user agent, no _epik click ID), when the server event_id doesn't match the Tag's eventID, or when events are sent late. Pinterest asks for real time or at most one hour of lag.
Read from the official documentation on 9 November 2026. Sources are listed at the end.
Endpoint and authentication
POST https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/events
Bearer token: a conversion access token (Conversions API only) or an OAuth token with at least ads:write scope
Standard event names
Spelled exactly as Pinterest expects them. A near miss is treated as a different event.
| Event | Use it for |
|---|---|
| checkout | purchase/checkout; send value, currency, order_id, num_items in custom_data |
| lead | lead |
| signup | sign-up |
| add_to_cart | add to cart |
| add_payment_info | payment info added |
| page_visit | page visit |
| view_category | category view |
| search | search |
| watch_video | video watch |
| custom event names | your own names (case-insensitive); up to 15 custom event types per advertiser ID |
Required and recommended fields
| Field | What it needs |
|---|---|
| event_name | Required |
| action_source | Required: app_android, app_ios, web or offline |
| event_time | Required. Unix timestamp in seconds |
| event_id | Required. Must match the browser/app eventID for deduplication |
| user_data | Required. Must include at least one of em, hashed_maids, or client_ip_address together with client_user_agent |
| event_source_url | Full URL path of the conversion event |
| opt_out | Whether the user opted out of web or offline conversion events; recommended for all events |
| custom_data (value, currency, order_id, content_ids, num_items) | value = pre-tax, pre-shipping total of purchased items |
Match keys and hashing
| Key | Normalise and hash |
|---|---|
| em | SHA-256 of the email address in lower case |
| ph | SHA-256 of digits only (country code, area code, number); remove symbols, letters, spaces and leading zeros |
| ln | SHA-256 of last name in lower case |
| ge | SHA-256 of f, m or n |
| db | SHA-256 of YYYYMMDD |
| ct | SHA-256 of city, lowercase, no spaces or punctuation |
| st | SHA-256 of 2-letter state code in lower case |
| zp | SHA-256 of zip code, digits only |
| country | SHA-256 of 2-character ISO-3166 code in lower case |
| external_id | SHA-256 hashed. Your user or loyalty ID |
| hashed_maids | SHA-256 hashed GAIDs or IDFAs (app) |
| client_ip_address | Not hashed. Valid IPv4/IPv6; never 0.0.0.0 |
| client_user_agent | Not hashed. Must include at least two of OS family, browser family, device family; no 'Other', null or bot user agents |
Click ids
| Click id | Where it comes from |
|---|---|
| click_id (epik) | Cookie generated when a user clicks an ad: the _epik first-party cookie on your domain, or the &epik= query parameter in the landing URL. Pinterest points you to the _epik cookie value, which still works when the URL parameter is missing or stripped |
Deduplication
- The browser or app eventID must match the server event_id.
- For redundant events, Pinterest keeps the first event captured and removes duplicates within 48 hours.
- Deduplicated conversions show on the Events Overview page in Ads Manager.
- Event Quality Score includes an overlap component that measures how well CAPI and Tag duplicates are identified.
Time limits and batch sizes
- Send event data in real time or with a maximum lag of one hour.
- Up to 1,000 events per production request.
- Test requests (?test=true): only the first 20 events in a batch are processed.
- Event Quality scores reflect a 14-day average, so changes take time to show.
How to test before you trust it
- test=true query parameter: POST to /v5/ad_accounts/{ad_account_id}/events?test=true. Events go to a sandbox and aren't processed for reporting; keep test batches to 20 events.
- Test Events (Ads Manager > Conversions): Click Test Events in the left navigation to see results, warnings and recommendations for test requests.
- Event Quality Score: Ads Manager > Conversions > Event Quality. Scored Good / Fair / Needs Improvement from customer identifiers, event metadata and CAPI/Tag overlap.
Why events arrive but don't attribute
- user_data has no em, no hashed_maids and no IP plus user agent pair, so the request lacks the minimum identifiers Pinterest requires.
- _epik click ID not passed as click_id: the landing URL parameter is stripped by redirects and the _epik cookie value isn't read on the server.
- Server event_id doesn't match the Tag's eventID, so the same checkout is counted twice; Pinterest only merges duplicates within 48 hours.
- Events batched and sent hours later. Pinterest asks for real time or at most one hour of lag to support attribution and optimisation.
- client_user_agent set to a server or bot user agent, 'Other' or null, or client_ip_address set to 0.0.0.0. All are disallowed.
- Production traffic left on ?test=true, so it goes to the sandbox and never reaches reporting.
- Email hashed without lowercasing, or phone hashed with symbols or leading zeros, so the hash doesn't match.
- checkout sent with value including tax and shipping. Pinterest defines value as the pre-tax, pre-shipping total.
Sources
- Pinterest Developers: Track conversions in the API
- Pinterest Business Help: Validating your set up with event testing
- Pinterest Business Help: The Pinterest Conversions API
- Pinterest Business Help: Event Quality Score
Platforms change these rules without notice. If a source says something different from this page, the source wins.