Pinterest Ads

Send conversion events to Pinterest through the Pinterest Conversions API (API v5). This integration calls the same API as the Pinterest integration; use one of them.

Why route Pinterest Ads through Datafly Signal

• Conversions survive ad blockers and tracking prevention. Signal sends the event from your own infrastructure, so the conversions Pinterest optimises against are not filtered by the browser.
• Identifiers are hashed before they leave your infrastructure. Signal normalises and applies SHA-256 inside your own deployment, so Pinterest receives match keys, not raw personal data.
• Click and cookie identifiers are captured first-party and replayed on later conversions, so attribution survives when the landing-page cookie has expired.
• One consent decision governs every destination. Pinterest is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
• Presets for Retail, Automotive and Insurance. The mapping starts from a working configuration for your vertical, and every field can be changed afterwards.

Prerequisites

1. A Pinterest business account with Ads Manager. Copy the Ad Account ID.
2. In Ads Manager > Conversions, generate a Conversion access token.

Configuration

Configure in Signal

1. In the Management UI, go to Integrations > Integration Library and select Pinterest Ads.
2. Choose a preset, fill in the fields above and choose the pipelines and consent categories (advertising destinations default to marketing).
3. Click Install Integration.

Or with the Management API:

curl -X POST http://localhost:8084/v1/admin/integration-catalog/pinterest_ads/install \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Pinterest Ads", "variant": "default", "config": {"ad_account_id": "549764982399", "conversion_token": "ct_ABC123..."}, "delivery_mode": "server_side"}'

API endpoint

POST https://api.pinterest.com/v5/ad_accounts/{{ad_account_id}}/events

Authentication: Authorization: Bearer <conversion token>. Allow egress to api.pinterest.com from the network your delivery workers run on.

Presets and event mapping

Every preset sends only the fields it maps (the strict output contract is on). Events not listed are not sent.

Retail (ecommerce)

Full retail funnel for the Pinterest Conversions API: page_visit, view_category, search, add_to_wishlist, add_to_cart, initiate_checkout, add_payment_info and checkout (Pinterest’s purchase event) with contents, content IDs, value, currency and order ID.

Automotive (automotive)

Vehicle funnel: searches, vehicle page visits and saves, configurator (customize_product), finance and dealer leads, test-drive and service bookings (schedule), reservations and purchases.

Default (default)

Pinterest Conversions API core funnel: page visits, search, add to cart, leads, sign-ups and checkouts, with hashed email, phone and name, the _epik click ID, IP and user agent, and an event ID for tag deduplication.

Insurance (insurance)

Insurance quote and policy funnel: quote requests and leads as lead, contact requests, checkout, payment info and policy purchases as checkout with the policy number as event ID and order ID.

Identity and hashing

Email, phone and names come from datafly.identify() traits (a legacy properties.email / properties.phone is read when no trait is set). Raw personal data is never sent.

Deduplication and consent

event_id is required: the Signal event ID, or the order ID on purchases, matched against the Pinterest tag’s event ID.

Example: purchase (Default preset)

datafly.identify('crm-user-7', { email: 'jane.doe@example.com', phone: '07700 900123', first_name: 'Jane', last_name: 'Doe' });
datafly.track('purchase', {
  transaction_id: 'T_1001', value: 139.99, currency: 'GBP',
  items: [
    { item_id: 'SKU_1', item_name: 'Helmet', item_category: 'Motorbike', item_brand: 'Shoei', price: 120.00, quantity: 2 },
    { item_id: 'SKU_2', item_name: 'Gloves', price: 19.99, quantity: 1 }
  ]
});

Request Signal sends (rendered from the preset):

{
  "data": [
    {
      "action_source": "web",
      "custom_data": {
        "content_ids": [
          "SKU_1",
          "SKU_2"
        ],
        "contents": [
          {
            "id": "SKU_1",
            "item_brand": "Shoei",
            "item_category": "Motorbike",
            "item_name": "Helmet",
            "item_price": 120,
            "quantity": 2
          },
          {
            "id": "SKU_2",
            "item_name": "Gloves",
            "item_price": 19.99,
            "quantity": 1
          }
        ],
        "currency": "GBP",
        "num_items": 2,
        "order_id": "T_1001",
        "value": 139.99
      },
      "event_id": "T_1001",
      "event_name": "checkout",
      "event_source_url": "https://shop.example.co.uk/p/123?utm_source=x",
      "event_time": 1758500000,
      "user_data": {
        "click_id": "epik1",
        "client_ip_address": "203.0.113.7",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "em": [
          "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d"
        ],
        "external_id": [
          "a1a37b21e9d35da94d0ae0b42483e449206f1e24c3790d28c113fb5fb9045f93"
        ],
        "fn": [
          "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2"
        ],
        "ln": [
          "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f"
        ],
        "ph": [
          "033134b911b137918338415ee3d20a064b24773d36a3b02e8b99fdd3fcd6b4cd"
        ]
      }
    }
  ],
  "partner_name": "datafly"
}

Known limitations

• The purchase event is Pinterest’s checkout.
• custom_data.num_items is the number of order lines (#1389).

Troubleshooting