LinkedIn Conversions API

Send conversions to LinkedIn server-to-server through the LinkedIn Conversions API (Linkedin-Version 202609).

Why route LinkedIn Conversions API through Datafly Signal

• Conversions survive ad blockers and tracking prevention. Signal sends the event from your own infrastructure, so the conversions LinkedIn 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 LinkedIn 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. LinkedIn is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
• Presets for B2B / SaaS, Retail and Insurance. The mapping starts from a working configuration for your vertical, and every field can be changed afterwards.

Prerequisites

1. A LinkedIn Campaign Manager ad account. Create one conversion rule per conversion type (Lead, Sign Up, Purchase, Request Quote and so on) with Conversions API as the data source, and note each rule ID (the number after /conversions/ in the rule’s URL).
2. A LinkedIn developer application with Advertising API access. Copy its Client ID and Client Secret.
3. Authorise the application for a member with access to the ad account, with the rw_conversions scope, and keep the refresh token (valid for a year). Signal uses it to mint access tokens.

Configuration

Configure in Signal

1. In the Management UI, go to Integrations > Integration Library and select LinkedIn 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/linkedin/install \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "LinkedIn Ads", "variant": "default", "config": {"client_id": "86abc123def456", "client_secret": "...", "refresh_token": "AQX...", "conversion_rule_id": "12345678"}, "delivery_mode": "server_side"}'

API endpoint

POST https://api.linkedin.com/rest/conversionEvents

Authentication: OAuth 2.0 Bearer token, refreshed from the refresh token. Allow egress to api.linkedin.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.

B2B / SaaS (saas)

B2B lead and subscription conversions: leads, demo requests, content downloads, sign-ups, trials and paid subscriptions, each streamed to the conversion rule configured for its type.

Retail (ecommerce)

Retail conversions: add to cart, checkout start, purchases with value and the order ID as event ID for Insight Tag deduplication, sign-ups and leads.

Default (default)

LinkedIn Conversions API core conversions: leads, sign-ups and purchases, matched on the hashed email, the li_fat_id click ID and (when both are known) hashed first and last name.

Insurance (insurance)

Insurance conversions: quote requests (Request Quote), leads, applications (Submit Application) and policy purchases with premium value and the policy number as event 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

eventId carries the Signal event ID, or the order ID on purchases, for deduplication against the Insight Tag. Each event is sent to the conversion rule configured for its type, else to the default rule. An event with neither an email nor an li_fat_id is not sent, because LinkedIn rejects it and one rejected conversion fails its whole batch. Conversions must be less than 90 days old.

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):

{
  "elements": [
    {
      "conversion": "urn:lla:llaPartnerConversion:999",
      "conversionHappenedAt": 1758500000123,
      "conversionValue": {
        "amount": "139.99",
        "currencyCode": "GBP"
      },
      "eventId": "T_1001",
      "user": {
        "externalIds": [
          "a1a37b21e9d35da94d0ae0b42483e449206f1e24c3790d28c113fb5fb9045f93"
        ],
        "userIds": [
          {
            "idType": "SHA256_EMAIL",
            "idValue": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d"
          },
          {
            "idType": "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
            "idValue": "lifat1"
          }
        ],
        "userInfo": {
          "hashedFirstName": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
          "hashedLastName": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f"
        }
      }
    }
  ]
}

Known limitations

• Name hashing trims and lowercases but does not remove spaces and punctuation as LinkedIn documents (#1390).

Troubleshooting