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.

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 variant:
   • Default — standard event tracking and campaign optimisation
   • Retail — e-commerce focused with checkout, add-to-cart, and product catalog events for Shopping campaigns
   • Travel — search, booking, and destination events for travel-related campaigns
   • Media — sign-up, lead, and content engagement events for awareness campaigns
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.

Variants

Pinterest CAPI supports four configuration variants, each pre-configured with appropriate event priorities and data enrichment for different business types.

All variants use server-side delivery, API v5, automatic PII hashing, and include IP address and User-Agent forwarding by default.

Identity Signals

Pinterest uses identity signals to match server events to Pinterest user profiles. The more signals you provide, the better your event match rate.

Automatic Signals

These are sent automatically by Signal — no configuration needed:

User-Provided Signals (Hashed)

When a user is identified via _df.identify() with traits, the following fields are SHA-256 hashed before sending to Pinterest:

How to Send User Data

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

_df.identify("user-123", {
  email: "[email protected]",
  phone: "+44 7700 900123"
});

Signal normalises and hashes these fields automatically before sending to Pinterest.

Event Mapping

Example: Purchase Event

Datafly.js call:

_df.track("Order Completed", {
  order_id: "ORD-001",
  total: 129.99,
  currency: "USD",
  products: [
    { product_id: "SKU-A", name: "Widget", price: 49.99, quantity: 2 },
    { product_id: "SKU-B", name: "Gadget", price: 30.01, quantity: 1 }
  ]
});

Pinterest Conversions API payload sent by Signal:

{
  "data": [
    {
      "event_name": "checkout",
      "action_source": "web",
      "event_time": 1706540000,
      "event_id": "evt_abc123def456",
      "event_source_url": "https://example.com/checkout/confirmation",
      "user_data": {
        "client_ip_address": "203.0.113.50",
        "client_user_agent": "Mozilla/5.0 ...",
        "em": ["836f82db99121b3481011f16b49dfa5fbc714a0d1b1b9f784a1ebbbf5b39577f"],
        "click_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "partner_id": "epik_abc123def456"
      },
      "custom_data": {
        "currency": "USD",
        "value": "129.99",
        "order_id": "ORD-001",
        "num_items": 3,
        "content_ids": ["SKU-A", "SKU-B"],
        "contents": [
          { "id": "SKU-A", "item_price": "49.99", "quantity": 2 },
          { "id": "SKU-B", "item_price": "30.01", "quantity": 1 }
        ]
      }
    }
  ]
}

Example: Page Visit

Datafly.js call:

// Automatic — every page load sends a page visit event
_df.page();

Pinterest Conversions API payload sent by Signal:

{
  "data": [
    {
      "event_name": "page_visit",
      "action_source": "web",
      "event_time": 1706539000,
      "event_id": "evt_789ghi012jkl",
      "event_source_url": "https://example.com/products/widgets",
      "user_data": {
        "client_ip_address": "203.0.113.50",
        "client_user_agent": "Mozilla/5.0 ...",
        "click_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ]
}

Action Source

The action_source field indicates where the event originated. For all browser-originated events collected by Datafly.js, this is always set to web.

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 _df.identify().

Deduplication

If you are running both Signal server-side delivery and the Pinterest Tag client-side (during a migration period), you must deduplicate events to prevent double-counting.

Signal includes a unique event_id with every event. To deduplicate:

1. Pass the same event_id to both the client-side Pinterest Tag and Datafly.js.
2. Pinterest will automatically deduplicate events with matching event_name and event_id.

// Generate a shared event ID
const eventId = crypto.randomUUID();
 
// Send via Pinterest Tag (client-side)
pintrk('track', 'checkout', {
  event_id: eventId,
  value: 129.99,
  currency: 'USD'
});
 
// Send via Datafly.js (server-side)
_df.track("Order Completed", {
  event_id: eventId,
  total: 129.99,
  currency: "USD"
});

Troubleshooting

Rate Limits