Pinterest Conversions API

Datafly Signal delivers events to Pinterest server-to-server using the Pinterest Conversions API. This enables accurate conversion tracking for Pinterest ad campaigns without relying on the Pinterest Tag client-side script.

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.

Configuration

Field	Required	Description
`ad_account_id`	Yes	Your Pinterest Ad Account ID (numeric). Found in Pinterest Ads Manager under account settings.
`access_token`	Yes	Pinterest API access token with `ads:write` scope. Generate via the Pinterest Developer Portal or OAuth flow.

Management UI Setup

Go to Integrations > Add Integration > Pinterest Conversions API.
Enter your ad_account_id and access_token.
Select consent categories (typically advertising).
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",
    "enabled": true,
    "config": {
      "ad_account_id": "1234567890",
      "access_token": "your_access_token"
    },
    "consent_categories": ["advertising"]
  }'

Identity Signals

Signal	Field	Description
`_pin_unauth`	`user_data.click_id` or cookie	Pinterest browser ID. Datafly Signal self-generates this as a UUID and stores it as a first-party cookie.
`epik`	`user_data.partner_id`	Pinterest click ID. Automatically extracted from the `epik` URL parameter when a user clicks a Pinterest ad.
`client_ip_address`	`user_data.client_ip_address`	Visitor’s IP address, forwarded from the original request.
`client_user_agent`	`user_data.client_user_agent`	Visitor’s User-Agent string, forwarded from the original request.

User-Provided Signals (Hashed)

When user data is available via _df.identify(), the following fields are SHA-256 hashed before sending to Pinterest:

Signal	Hashing	Description
`em` (email)	SHA-256, lowercase, trimmed	User’s email address
`hashed_maids`	SHA-256	Mobile advertising IDs (if available)

All PII hashing is performed server-side by the Delivery Worker. Raw PII never leaves your infrastructure.

Event Mapping

Datafly Event	Pinterest Event	Notes
`page` (page view)	`page_visit`	Sent for every page view
`Product Added`	`add_to_cart`	Includes product details
`Order Completed` / `Product Purchased`	`checkout`	Requires `value`, `order_quantity`
`Signed Up`	`signup`	User registration
`Lead Generated`	`lead`	Lead form submission
`Products Searched`	`search`	Includes `search_query`
`Product Viewed`	`view_category`	Includes product details
Custom events	`custom`	Sent with `custom_event_name`

Example: Checkout 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 Datafly:

{
  "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

{
  "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.

API Response

A successful response from Pinterest:

{
  "num_events_received": 1,
  "num_events_processed": 1,
  "events": [
    {
      "status": "processed",
      "error_message": ""
    }
  ]
}

An error response:

{
  "code": 2,
  "message": "Invalid ad_account_id",
  "status": "failure"
}

Rate Limits

Setting	Default
`rate_limit_rps`	100
`rate_limit_burst`	200

Pinterest allows up to 1,000 events per batch request. Datafly Signal batches events automatically when throughput is high to maximise efficiency.

TikTok Events API Snapchat CAPI