Pinterest Conversions API

Datafly Signal delivers events to Pinterest server-to-server using the Conversions API (CAPI). This provides reliable conversion tracking for Pinterest ad campaigns without relying on the Pinterest Tag client-side script, improving measurement accuracy and ad performance optimisation.

Why route Pinterest through Datafly Signal

• Conversions survive ad blockers and tracking prevention. A browser tag served from an advertising domain is blocked outright for part of your traffic, and Safari’s ITP shortens the cookies it can set. Signal sends the event from your own server, so the conversions Pinterest optimises against are not filtered by the browser.
• Email and phone number are hashed before leaving your infrastructure. Signal normalises (trim and lowercase) and applies SHA-256 inside your own deployment, so Pinterest receives match keys rather than raw personal data.
• Client IP and user agent are carried in the payload. Both are taken from the original visitor request rather than your server, which is what Pinterest needs to attribute the event to the right session.
• Click identifiers are captured and replayed. Signal stores click_id first-party at collection time and attaches them to the conversion later, so attribution survives even when the original landing cookie has expired.
• Delivery is batched, rate-limited, and retried. Signal buffers to Kafka, respects the Pinterest rate limit, and retries on 429 or transient failure rather than dropping the event.
• Presets for Retail and Automotive. The mapping starts from a working configuration for your vertical instead of a blank field map.
• 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.
• No vendor tag on the page. Removing it removes its page weight and its independent access to your visitors.

Prerequisites

Before configuring Pinterest CAPI in Signal, you need a Pinterest Business account, an Ads Manager account with a Pinterest Tag, and API credentials. Follow the steps below to set everything up.

Step 1: Create a Pinterest Business Account

1. Go to pinterest.com/business/create and click Create Account.
2. Enter your email, password, business name, and website URL.
3. Complete the business profile by selecting your business type and industry.
4. If you already have a personal Pinterest account, convert it to a business account at Settings > Account management > Convert to business account.

Step 2: Set Up Pinterest Ads Manager

1. Navigate to ads.pinterest.com and sign in with your business account.
2. If prompted, complete the billing setup by adding a payment method under Billing > Payment method.
3. Note your Ad Account ID — a numeric ID (e.g. 549764982399) visible in the URL bar or under Ads > Overview > Account Settings.

Step 3: Create a Pinterest Tag

The Pinterest Tag is required even when using the Conversions API — it defines the container for your conversion events.

1. In Ads Manager, go to Conversions (left sidebar) > Set up the Pinterest tag.
2. Choose Conversions API as your setup method.
3. Note the Tag ID displayed on the setup page.
4. Under Conversion Access Token, click Generate New Token.
5. Copy the Conversion Access Token immediately — you will need this for Signal configuration.

Step 4: Generate an API Access Token

The API access token authenticates server-to-server requests to the Pinterest Conversions API.

1. Go to developers.pinterest.com and sign in with your Pinterest business account.
2. Click My apps > Create app (or select an existing app).
3. Enter an app name (e.g. “Datafly Signal”) and a description.
4. Once the app is created, go to the OAuth section.
5. Generate a token with the ads:write scope. This scope is required for sending conversion events.
6. Copy the access token — it typically starts with pina_.

Configure in Signal

Now that you have your Ad Account ID, API access token, and Conversion Access Token, configure the integration in Signal.

Configuration Fields

Management UI Setup

1. Go to Integrations > Add Integration > Pinterest Conversions API.
2. Choose a preset: Retail, Automotive, Default or Insurance (see Presets and event mapping).
3. Enter your ad_account_id, access_token, and conversion_token.
4. Select consent categories (typically advertising).
5. Click Save.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "pinterest",
    "name": "Pinterest Conversions API",
    "enabled": true,
    "config": {
      "ad_account_id": "549764982399",
      "access_token": "pina_ABC123...",
      "conversion_token": "ct_ABC123..."
    },
    "consent_categories": ["advertising"]
  }'

API Endpoint

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

Events are sent as a JSON array in the data field, with authentication via the Authorization: Bearer header.

Presets

Every preset sends server to server with API v5, the visitor’s IP address and user agent, and personal data only as SHA-256 hashes.

Identity signals

Pinterest matches a server event to a Pinterest user with the signals below. The more a visitor carries, the better the match rate.

Sent automatically

Hashed personal data

Pinterest only matches on these values, so Signal sends each one as an array of SHA-256 hashes (the shape Pinterest’s API defines), never in plain text:

Hashing happens in your own deployment before the event leaves it. See Personal data by integration.

How to send user data

Call datafly.identify() when a user logs in, registers or submits a form:

datafly.identify("user-123", {
  email: "jane.doe@example.com",
  phone: "+44 7700 900123",
  first_name: "Jane",
  last_name: "Doe"
});

Presets and event mapping

Event names are Pinterest’s own (page_visit, view_category, search, add_to_cart, add_to_wishlist, initiate_checkout, add_payment_info, checkout, lead, signup, contact, schedule, customize_product): an event name outside that list is rejected. checkout is Pinterest’s purchase event, so only a completed purchase is sent as checkout.

Content IDs and contents come from your items[] (canonical), else the legacy products[], else a single flat item_id / product_id (automotive: then the legacy vehicle_id). value is your event’s value (else the legacy revenue): the total including tax and shipping, as the event specs define it. Pinterest recommends the pre-tax, pre-shipping value; to send that, edit the value mapping in the installed blueprint.

Retail preset (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 preset (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 preset (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 preset (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.

Example: purchase

A Retail purchase with two items from a known visitor, as Signal sends it to POST https://api.pinterest.com/v5/ad_accounts/<ad_account_id>/events:

{
  "data": [
    {
      "action_source": "web",
      "custom_data": {
        "content_ids": [
          "STK-7421"
        ],
        "contents": [
          {
            "id": "STK-7421",
            "item_brand": "BMW",
            "item_category": "SUV",
            "item_name": "BMW X3 xDrive30e",
            "item_price": 49995,
            "quantity": 1
          }
        ],
        "currency": "GBP",
        "num_items": 1,
        "order_id": "ORD-10042",
        "value": 49995
      },
      "event_id": "ORD-10042",
      "event_name": "checkout",
      "event_source_url": "https://shop.example.co.uk/checkout?gclid=g-123",
      "event_time": 1790155800,
      "user_data": {
        "click_id": "ep-123",
        "client_ip_address": "203.0.113.7",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15",
        "em": [
          "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d"
        ],
        "external_id": [
          "40ba61f5c6b64e4f3f389c4b7a244f2b176115cbf452d1d81cf9bf70ebdf739d"
        ],
        "fn": [
          "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2"
        ],
        "ln": [
          "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f"
        ],
        "ph": [
          "033134b911b137918338415ee3d20a064b24773d36a3b02e8b99fdd3fcd6b4cd"
        ]
      }
    }
  ],
  "partner_name": "datafly"
}

Example: product view

{
  "data": [
    {
      "action_source": "web",
      "custom_data": {
        "content_ids": [
          "PKT-001"
        ],
        "contents": [
          {
            "id": "PKT-001",
            "item_brand": "NorthEdge",
            "item_category": "Women > Jackets",
            "item_name": "Parka Jacket",
            "item_price": 129.99,
            "quantity": 1
          }
        ],
        "currency": "GBP",
        "value": 129.99
      },
      "event_id": "evt-spec-0001",
      "event_name": "page_visit",
      "event_source_url": "https://shop.example.co.uk/checkout?gclid=g-123",
      "event_time": 1790155800,
      "user_data": {
        "click_id": "ep-123",
        "client_ip_address": "203.0.113.7",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15",
        "em": [
          "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d"
        ],
        "external_id": [
          "40ba61f5c6b64e4f3f389c4b7a244f2b176115cbf452d1d81cf9bf70ebdf739d"
        ],
        "fn": [
          "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2"
        ],
        "ln": [
          "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f"
        ],
        "ph": [
          "033134b911b137918338415ee3d20a064b24773d36a3b02e8b99fdd3fcd6b4cd"
        ]
      }
    }
  ],
  "partner_name": "datafly"
}

Action source

action_source is web for events from Datafly.js, app_ios for the iOS SDK and app_android for the Android SDK.

Testing Your Integration

Step 1: Send Test Events

1. Add the Pinterest integration in Signal with your credentials.
2. Trigger events on your website (page views, add-to-cart, purchase).
3. Check the Signal event debugger to confirm events are being delivered successfully.

Step 2: Verify in Pinterest Ads Manager

1. In Pinterest Ads Manager, go to Conversions > Events tab.
2. You should see server events arriving with an “API” source indicator.
3. Events typically appear within 1-2 minutes of being sent.
4. Click on individual events to inspect the payload and parameter details.

Step 3: Check Event Match Rate

1. In the Conversions dashboard, review the Event Match Rate metric.
2. A higher match rate means Pinterest can attribute more events to user profiles.
3. If the rate is low, ensure epik click IDs and pin_unauth cookies are being captured, and add user identity signals via datafly.identify().

Deduplication

Each event carries an event_id: the event’s deduplication ID (event_id passed to datafly.track(), else Signal’s message ID), and on checkout the order ID (transaction_id, else order_id). If you still run the Pinterest Tag in the browser during a migration, give the tag the same ID so Pinterest counts the conversion once:

const eventId = crypto.randomUUID();
pintrk('track', 'add_to_cart', { event_id: eventId, value: 129.99, currency: 'GBP' });
datafly.track('add_to_cart', { event_id: eventId, value: 129.99, currency: 'GBP', items: [...] });

For a purchase, pass the order ID as the tag’s event_id. Once the server events are verified you can remove the tag.

Partner name

The delivery sends partner_name: "datafly" at the top of every request. Pinterest reads partner_name on each event and only for registered partners (ss-<name>); the top-level field has no effect on attribution (#1582).

Troubleshooting

Rate Limits