LinkedIn Conversions API

Datafly Signal delivers conversion events to LinkedIn server-to-server using the LinkedIn Marketing API Conversions endpoint. This enables accurate B2B conversion tracking for LinkedIn ad campaigns.

API Overview

LinkedIn’s Conversions API uses the LinkedIn Marketing API to report conversion events:

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

Authentication is via OAuth 2.0 Bearer token with the r_ads_reporting and rw_conversions scopes.

Configuration

Management UI Setup

1. Go to Integrations > Add Integration > LinkedIn Conversions API.
2. Enter your account_id.
3. Complete the OAuth flow by clicking Connect LinkedIn Account or manually enter the access_token.
4. Map your conversion events to LinkedIn conversion rule IDs.
5. Select consent categories (typically advertising).
6. 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": "linkedin",
    "name": "LinkedIn Conversions",
    "enabled": true,
    "config": {
      "account_id": "123456789",
      "access_token": "your_oauth_access_token",
      "conversion_rule_ids": {
        "Order Completed": "urn:lla:llaPartnerConversion:987654",
        "Lead Generated": "urn:lla:llaPartnerConversion:987655",
        "Signed Up": "urn:lla:llaPartnerConversion:987656"
      }
    },
    "consent_categories": ["advertising"]
  }'

Identity

LinkedIn Click ID (li_fat_id)

The primary identity signal for LinkedIn conversions is the li_fat_id (LinkedIn First-Party Ad Tracking ID). When a user clicks a LinkedIn ad, this parameter is appended to the landing page URL:

https://example.com/landing?li_fat_id=abc123-def456-ghi789

Datafly.js automatically captures the li_fat_id from the URL and includes it in all subsequent events. It is persisted as a first-party cookie for the duration of the attribution window.

User-Provided Signals (Hashed)

As a supplementary signal, Datafly Signal can send hashed email addresses:

Hashed email is sent in the user.userIds array and can improve match rates for users who are logged into LinkedIn.

Event Mapping

LinkedIn uses conversion rules rather than standard event names. Each conversion rule is created in LinkedIn Campaign Manager and assigned a unique ID. You map Datafly event names to conversion rule IDs in the integration configuration.

Events not mapped to a conversion rule ID are silently dropped for this integration.

Example: Conversion Event

Datafly.js call:

_df.track("Lead Generated", {
  lead_source: "contact_form",
  value: 500.00,
  currency: "USD"
});

LinkedIn Conversions API payload sent by Datafly:

{
  "conversion": "urn:lla:llaPartnerConversion:987655",
  "conversionHappenedAt": 1706540000000,
  "conversionValue": {
    "currencyCode": "USD",
    "amount": "500.00"
  },
  "user": {
    "userIds": [
      {
        "idType": "SHA256_EMAIL",
        "idValue": "836f82db99121b3481011f16b49dfa5fbc714a0d1b1b9f784a1ebbbf5b39577f"
      },
      {
        "idType": "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
        "idValue": "abc123-def456-ghi789"
      }
    ],
    "userInfo": {
      "firstName": "John",
      "lastName": "Doe",
      "companyName": "Acme Inc"
    }
  },
  "eventId": "evt_abc123def456"
}

Creating Conversion Rules in LinkedIn

Before configuring the Datafly integration, you need to create conversion rules in LinkedIn Campaign Manager:

1. Go to LinkedIn Campaign Manager > Analyze > Conversions.
2. Click Create Conversion.
3. Select the conversion type (e.g. Lead, Purchase, Sign-up).
4. Choose Conversions API as the tracking method.
5. Note the conversion rule URN (e.g. urn:lla:llaPartnerConversion:987654).
6. Enter this URN in the Datafly integration conversion_rule_ids mapping.

OAuth Token Refresh

LinkedIn OAuth access tokens expire after 60 days. Datafly Signal handles token refresh automatically if a refresh_token is provided:

{
  "config": {
    "account_id": "123456789",
    "access_token": "initial_access_token",
    "refresh_token": "your_refresh_token",
    "oauth_client_id": "your_client_id",
    "oauth_client_secret": "your_client_secret"
  }
}

Rate Limits

LinkedIn’s Marketing API has relatively strict rate limits compared to other advertising platforms. The defaults are set conservatively to avoid 429 responses.