How to Connect Perspection to Pinterest Conversions API for Server-Side Tracking

How do you connect Perspection to the Pinterest Conversions API?

Open the Perspection dashboard, navigate to Connectors then Destinations, select Pinterest, enter the Ad Account ID from Pinterest Business Hub, paste the Access Token from the Pinterest Developer App with ads:write scope, and click Save. Perspection validates the connection by querying the Pinterest Ad Account endpoint to confirm credentials.

Step-by-step: Generate Pinterest Conversions API credentials

1. Open Pinterest Business Hub and log in to the Pinterest Business account associated with the ad campaigns receiving conversions.

2. Click Ads in the top navigation and select the ad account from the account dropdown.

3. Copy the Ad Account ID displayed in the account selector. The Ad Account ID follows a numeric format, for example 123456789012.

4. Open the Pinterest Developer Portal and navigate to Apps in the developer dashboard.

5. Select the developer app or create a new app if no app exists.

6. Generate a new Access Token with the following scopes: ads:read and ads:write. The access token starts with pina_ followed by an alphanumeric string.

7. Store the Access Token securely. Pinterest does not display the full token again after generation.

Step-by-step: Configure the destination in Perspection

1. Log into the Perspection dashboard and select the workspace that should send events to Pinterest.

2. Open Connectors > Destinations from the left navigation.

3. Under Available Destinations, click the Pinterest card labeled "Conversions API."

4. Paste the Ad Account ID into the Ad Account ID field.

5. Paste the Access Token into the Access Token field.

6. (Optional) Enter a Conversion Token for enhanced server-side conversion tracking. The Conversion Token provides additional authentication for workspaces that require enhanced security.

7. Toggle the Live switch to enabled.

8. Click Save. Perspection creates the destination and displays a "Live" health badge.

9. Click Test to validate the connection. Perspection sends a GET request to the Pinterest Ad Account API endpoint (/v5/ad_accounts/{ad_account_id}) to confirm the Access Token and Ad Account ID are valid. Perspection reports "Connection test successful!" or displays the specific Pinterest API error message.

Required and optional fields

What data does Perspection send to Pinterest?

Perspection sends each event to the Pinterest Conversions API v5 with the event name mapped to a Pinterest standard event, Unix timestamp, action_source, SHA-256-hashed email and phone arrays, the Pinterest click ID (epik), client IP, user agent, external_id, and custom data including value, currency, content_ids, content_category, content_brand, num_items, order_id, and search_query.

The Perspection Pinterest connector (running on the Perspection dispatch worker) transforms raw events from the Perspection SDK into the Pinterest Conversions API payload schema before dispatch. The connector maps each field to the exact parameter name that the Pinterest API expects.

Event name mapping

Perspection automatically translates common event names to Pinterest standard events:

Custom event names that do not match the mapping table pass through to Pinterest unchanged. Pinterest accepts custom event names for flexible tracking beyond the seven standard events.

User data parameters

Perspection automatically extracts the Pinterest epik click ID from the stored click IDs using a three-tier fallback pattern: first from the JSONB click_ids column (new sparse-storage format), then from individual columns (legacy format), and finally from the properties object (SDK events). When the epik value is present, Perspection includes the epik as the click_id parameter in the Pinterest payload, enabling Pinterest to attribute the conversion back to the originating ad click.

Custom data parameters

PII hashing

Perspection hashes personally identifiable information before sending data to Pinterest. The Perspection BaseConnector class provides the hashing methods:

• Email: Converted to lowercase, trimmed of whitespace, then hashed with SHA-256 to produce a 64-character hexadecimal string.

• Phone: Non-digit characters are stripped, then the cleaned number is hashed with SHA-256 to produce a 64-character hexadecimal string.

Pinterest receives only the hashed values -- Perspection never transmits plaintext email addresses or phone numbers to the Pinterest API.

Consent handling

Perspection respects user consent signals when dispatching events to Pinterest. The Pinterest event payload includes an opt_out flag in custom_data that Perspection sets to true under any of the following conditions:

1. The user's CCPA consent field (ccpa_opt_out) equals true.

2. The user's ad_storage consent is set to denied.

3. The user's ad_user_data consent is set to denied.

4. The event properties include opt_out: true.

When opt_out is true, Pinterest excludes the event from audience building and ad targeting while still counting the conversion for reporting purposes.

Sample Pinterest API payload

For a purchase event, Perspection sends a payload structured as follows:

{
  "data": [
    {
      "event_name": "checkout",
      "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event_time": 1740700800,
      "action_source": "web",
      "user_data": {
        "em": ["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"],
        "ph": ["8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"],
        "external_id": ["user_12345"],
        "click_id": "ad_1234567890",
        "client_ip_address": "203.0.113.50",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
      },
      "custom_data": {
        "currency": "USD",
        "value": 149.99,
        "content_ids": ["SKU-001", "SKU-002"],
        "content_category": "Electronics",
        "content_brand": "ExampleBrand",
        "content_name": "Wireless Headphones",
        "num_items": 2,
        "order_id": "ORD-20260227-001",
        "opt_out": false
      }
    }
  ]
}

{
  "data": [
    {
      "event_name": "checkout",
      "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event_time": 1740700800,
      "action_source": "web",
      "user_data": {
        "em": ["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"],
        "ph": ["8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"],
        "external_id": ["user_12345"],
        "click_id": "ad_1234567890",
        "client_ip_address": "203.0.113.50",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
      },
      "custom_data": {
        "currency": "USD",
        "value": 149.99,
        "content_ids": ["SKU-001", "SKU-002"],
        "content_category": "Electronics",
        "content_brand": "ExampleBrand",
        "content_name": "Wireless Headphones",
        "num_items": 2,
        "order_id": "ORD-20260227-001",
        "opt_out": false
      }
    }
  ]
}

{
  "data": [
    {
      "event_name": "checkout",
      "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event_time": 1740700800,
      "action_source": "web",
      "user_data": {
        "em": ["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"],
        "ph": ["8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"],
        "external_id": ["user_12345"],
        "click_id": "ad_1234567890",
        "client_ip_address": "203.0.113.50",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
      },
      "custom_data": {
        "currency": "USD",
        "value": 149.99,
        "content_ids": ["SKU-001", "SKU-002"],
        "content_category": "Electronics",
        "content_brand": "ExampleBrand",
        "content_name": "Wireless Headphones",
        "num_items": 2,
        "order_id": "ORD-20260227-001",
        "opt_out": false
      }
    }
  ]
}

How do you verify Pinterest conversion events?

Click the Test button on the Pinterest destination card to validate the Ad Account ID and Access Token via the Pinterest API. Then trigger a real event on the website and check Pinterest Ads Manager under Reporting for incoming server events. Use the Perspection Sent Data tab to confirm successful delivery.

Step-by-step: Verify with the Perspection connection test

1. In the Perspection dashboard, navigate to Connectors > Destinations and expand the Pinterest destination card.

2. Click the Test button. Perspection sends a validation request to the Pinterest API endpoint at https://api.pinterest.com/v5/ad_accounts/{ad_account_id}.

3. Perspection reports the result as "Connection test successful!" with the response latency in milliseconds, or displays the specific Pinterest API error message if the connection fails.

4. Common failure causes: expired Access Token, incorrect Ad Account ID, Access Token missing ads:write scope, or network connectivity issues between Perspection servers and the Pinterest API.

Step-by-step: Verify in Pinterest Ads Manager

1. Open Pinterest Ads Manager and select the correct ad account.

2. Navigate to Reporting and filter by conversion source to isolate server-side (Conversions API) events.

3. Check the conversion event counts to confirm server-side events are arriving. Pinterest typically processes Conversions API events within 1-5 minutes of receipt.

4. Verify that the event names match expectations: page_visit for page views, checkout for purchases, add_to_cart for cart additions, signup for account registrations, and lead for form submissions.

Step-by-step: Verify in the Perspection dashboard

1. In the Perspection dashboard, navigate to the workspace Home Dashboard to view the event delivery overview.

2. Check the Destination Health monitoring panel for the Pinterest destination. The health badge should show "Live" (green) for healthy delivery, "Degraded" (yellow) for intermittent failures, or "Down" (red) for persistent failures.

3. Review the dispatch status to confirm events are being delivered successfully. Perspection tracks the success rate, average latency, and error count for each destination.

4. Monitor the Event Match Quality score to ensure Perspection is sending sufficient identity signals. Higher data completeness translates to better conversion attribution on Pinterest.

Troubleshooting common issues

How does Perspection handle rate limits and retries for Pinterest?

The Pinterest Conversions API enforces rate limits tracked by a per-destination counter in Perspection. When Pinterest returns HTTP 429, the Pinterest connector retries with exponential backoff starting at 500 milliseconds, doubling on each attempt up to 3 retries. Non-retriable errors (HTTP 4xx other than 429) route to the Dead Letter Queue.

Rate limiting

The Perspection dispatch worker maintains a rate limit tracker for each Pinterest destination. The BaseConnector class resets the rate limit counter every 60 seconds. When a dispatch attempt detects zero remaining capacity, the event is re-queued for dispatch after the reset window.

Retry behavior

Retry timing

The Perspection retry mechanism uses exponential backoff with a base delay of 500 milliseconds:

1. First retry: 500ms after initial failure

2. Second retry: 1,000ms after first retry failure

3. Third retry: 2,000ms after second retry failure

After 3 failed retry attempts, the event is marked as failed and routed to the Perspection Dead Letter Queue. Workspace administrators can review and manually retry failed events from the DLQ management panel.

How does Perspection map events differently for Pinterest compared to Meta CAPI?

Perspection maps events to Pinterest using a distinct event name vocabulary because Pinterest defines different standard event names than Meta. Where Meta uses "PageView" and "Purchase," Pinterest uses "page_visit" and "checkout." The Meta CAPI connector sends fbp and fbc cookies; the Pinterest connector sends the epik click ID. Pinterest uses content_brand and search_query fields with no Meta equivalent.

Key differences between Pinterest and Meta event dispatch

Both connectors share the same PII hashing logic from the Perspection BaseConnector class: SHA-256 hashing for email (lowercase, trimmed) and phone (digits only). Both connectors use the same exponential backoff retry mechanism with 3 attempts and a 500ms base delay.

Methodology

All Pinterest Conversions API configuration steps in this guide were verified against the Perspection production dashboard and Pinterest Ads Manager as of February 2026.

"For Pinterest advertisers, the single most impactful action for improving conversion attribution is capturing the epik click ID. The epik parameter is Pinterest's equivalent of the Facebook fbc cookie -- the epik links an ad click to a downstream conversion. Perspection's first-party domain setup preserves the epik cookie beyond Safari ITP's 7-day restriction, which means return visitors who click a Pinterest ad and convert 10 or 14 days later are still attributed correctly. Advertisers using Perspection first-party domains with Pinterest server-side tracking see materially higher attributed conversions compared to standard Pinterest Tag implementations, because the Pinterest Tag loses the epik value after 7 days on Safari." -- Perspection Engineering Team

How does Perspection map events to Pinterest conversion parameters?

Perspection provides a visual and JSON-based event mapping editor that customizes how Perspection events translate to Pinterest Conversions API events. The editor supports event name remapping, property remapping via dot-notation paths, event ignoring, and toggling between drag-and-drop visual mode and raw JSON mode.

Beyond the default event name mapping, Perspection provides a visual and JSON-based event mapping editor for customizing how Perspection events translate to Pinterest events. The mapping editor supports:

1. Event name remapping: Map a custom source event name (for example product_viewed) to a specific Pinterest event name (for example view_category).

2. Property remapping: Map source properties to Pinterest-specific custom data keys using dot-notation paths (for example properties.price mapped to value).

3. Event ignoring: Mark specific source events to skip dispatch to Pinterest entirely.

4. Visual and JSON modes: Toggle between a drag-and-drop visual editor and a raw JSON editor for advanced configurations.

To configure event mapping, expand the Pinterest destination card in the Perspection dashboard, scroll to the Event Mapping section, and add mapping rules. Save the mapping configuration separately from the destination credentials.

Sources & References

1. Pinterest -- Conversions API Documentation, https://developers.pinterest.com/docs/conversions/conversions/

2. Pinterest -- Conversion Event Types, https://developers.pinterest.com/docs/conversions/event-data/

3. Pinterest Business -- Ads Manager Help, https://help.pinterest.com/en/business

4. Perspection Product Guide -- Event Match Quality, /library/event-match-quality-guide

5. Perspection Product Guide -- First-Party Tracking Domain, /library/first-party-tracking-domain-guide