Skip to main content
Ask your AI

LinkedIn Conversions API

Server Source code Package

Server-side event delivery to LinkedIn's Conversions API for ad attribution.

Where this fits

LinkedIn Conversions API is a server destination in the walkerOS flow:

Sends conversion events server-side to LinkedIn's Conversions API, bypassing browser limitations for improved data quality. Sends the event's `id` as `eventId`, so LinkedIn can deduplicate it against the Insight Tag.

Installation​

npm install @walkeros/collector @walkeros/server-destination-linkedin
import { startFlow } from '@walkeros/collector';
import destinationLinkedin from '@walkeros/server-destination-linkedin';

await startFlow({
  destinations: {
    linkedin: {
      code: destinationLinkedin,
      config: {
        settings: {
          accessToken: process.env.LINKEDIN_ACCESS_TOKEN,
          conversionRuleId: '12345678',
        },
      },
    },
  },
});

Configuration​

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
accessToken*stringLinkedIn OAuth 2.0 Bearer token for Conversions API authentication
conversionRuleId*stringDefault LinkedIn conversion rule ID from Campaign Manager
apiVersionstringLinkedin-Version header value in YYYYMM format
doNotHashArray<string>Array of user data fields that should not be hashed
urlstringCustom URL for the LinkedIn Conversions API, ending in /
user_dataRecord<string, string>Mapping configuration for user data fields
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
conversionconversionPer-event conversion override with ruleId, value, and currency
ruleIdstringOverride conversion rule ID for this event
valuestring | numberConversion monetary value
currencystringISO 4217 currency code

Examples

Lead

A form submission is posted to LinkedIn as a conversion with the SHA-256 hashed email as the user identifier.

Event
{
  "name": "form submit",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "user@example.com"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000901000",
  "trigger": "test",
  "entity": "form",
  "action": "submit",
  "timestamp": 1700000901000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}
Out
sendServer("https://api.linkedin.com/rest/conversionEvents", "{\"elements\":[{\"conversion\":\"urn:lla:llaPartnerConversion:12345678\",\"conversionHappenedAt\":1700000901000,\"user\":{\"userIds\":[{\"idType\":\"SHA256_EMAIL\",\"idValue\":\"b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514\"}]},\"eventId\":\"ev-1700000901000\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t",
    "Content-Type": "application/json",
    "X-Restli-Protocol-Version": "2.0.0",
    "X-RestLi-Method": "BATCH_CREATE",
    "Linkedin-Version": "202604"
  }
})

Purchase

A completed order is sent to the LinkedIn Conversions API with conversion value, currency, and hashed email.

Event
{
  "name": "order complete",
  "data": {
    "value": 249.99,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "jane@example.com"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000900000",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000900000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}
Mapping
{
  "settings": {
    "conversion": {
      "map": {
        "value": "data.value",
        "currency": {
          "key": "data.currency",
          "value": "EUR"
        }
      }
    }
  }
}
Out
sendServer("https://api.linkedin.com/rest/conversionEvents", "{\"elements\":[{\"conversion\":\"urn:lla:llaPartnerConversion:12345678\",\"conversionHappenedAt\":1700000900000,\"user\":{\"userIds\":[{\"idType\":\"SHA256_EMAIL\",\"idValue\":\"8c87b489ce35cf2e2f39f80e282cb2e804932a56a213983eeeb428407d43b52d\"}]},\"eventId\":\"ev-1700000900000\",\"conversionValue\":{\"currencyCode\":\"EUR\",\"amount\":\"249.99\"}}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t",
    "Content-Type": "application/json",
    "X-Restli-Protocol-Version": "2.0.0",
    "X-RestLi-Method": "BATCH_CREATE",
    "Linkedin-Version": "202604"
  }
})

Purchase with li_fat_id

A purchase is sent to LinkedIn with both the hashed email and the first-party li_fat_id tracking identifier.

Event
{
  "name": "order complete",
  "data": {
    "value": 89.99,
    "currency": "USD"
  },
  "context": {
    "li_fat_id": [
      "abc123-fat-id",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "buyer@co.com"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000902000",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000902000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}
Mapping
{
  "settings": {
    "conversion": {
      "map": {
        "value": "data.value",
        "currency": {
          "key": "data.currency",
          "value": "USD"
        }
      }
    }
  },
  "data": {
    "map": {
      "user_data": {
        "map": {
          "li_fat_id": "context.li_fat_id"
        }
      }
    }
  }
}
Out
sendServer("https://api.linkedin.com/rest/conversionEvents", "{\"elements\":[{\"conversion\":\"urn:lla:llaPartnerConversion:12345678\",\"conversionHappenedAt\":1700000902000,\"user\":{\"userIds\":[{\"idType\":\"SHA256_EMAIL\",\"idValue\":\"484c39bfb51212665d9673805c112b5ba04cbf0460b6d3f00bcdc18b92afed66\"},{\"idType\":\"LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID\",\"idValue\":\"abc123-fat-id\"}]},\"eventId\":\"ev-1700000902000\",\"conversionValue\":{\"currencyCode\":\"USD\",\"amount\":\"89.99\"}}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t",
    "Content-Type": "application/json",
    "X-Restli-Protocol-Version": "2.0.0",
    "X-RestLi-Method": "BATCH_CREATE",
    "Linkedin-Version": "202604"
  }
})

When it fails

  • no identifier form: A form submit event without a user identifier cannot be sent to LinkedIn: the push fails with missing-input instead of counting as delivered. Reported as failed with code missing-input.
  • no identifier order: A order complete event without a user identifier cannot be sent to LinkedIn: the push fails with missing-input instead of counting as delivered. Reported as failed with code missing-input.

Failures​

A response outside the 2xx range, a network error, or no answer within 5 seconds fails the event: the push answers failed with the code transport (with the HTTP status) or timeout, the event goes to the dead-letter queue, and the collector logs one ERROR line. Any 2xx answer counts as delivered: the destination does not read the response body. Without accessToken or conversionRuleId the destination does not start: every push answers failed with the code config, and the collector logs destination init failed. A rule with silent: true sends nothing.

The quickstart sets no config.consent, so LinkedIn receives every event, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).

User identification​

The destination builds a userIds array from the event data. At least one identifier is required; an event without one fails with missing-input.

SHA256_EMAIL: resolved from event.user.email or a user_data.email mapping. The email is normalized (trimmed, lowercased) and SHA-256 hashed before sending. Set doNotHash: ['email'] if you are pre-hashing upstream: the email is then sent trimmed and lowercased, but not hashed.

userInfo: firstName and lastName mapped in user_data are sent together as user.userInfo, with title, companyName and countryCode when mapped; with only one of the two names, none of these fields is sent. LinkedIn takes them in plain text, so they leave your server unhashed.

LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID: the LinkedIn click ID (li_fat_id). The session source reads it from the landing page URL into its session start event only, so carry it to your conversion events yourself (the snippet reads context.li_fat_id). Map it via user_data in settings or through event mapping:

"settings": {
  "accessToken": "$secret.LINKEDIN_ACCESS_TOKEN",
  "conversionRuleId": "12345678",
  "user_data": {
    "li_fat_id": "context.li_fat_id"
  }
}

Every other key in user_data (besides email, li_fat_id and the five userInfo keys) is dropped without a log line, and a list mapped to email is ignored in favour of event.user.email.

Per-event conversion override​

The default conversionRuleId from settings applies to all events. Override it per event via mapping to route different events to different Campaign Manager conversion rules:

"mapping": {
  "order": {
    "complete": {
      "settings": {
        "conversion": {
          "map": {
            "ruleId": { "value": "99887766" },
            "value": "data.value",
            "currency": { "key": "data.currency", "value": "EUR" }
          }
        }
      }
    }
  }
}

When currency resolves to nothing, the value is sent in USD.

Browser deduplication​

When you run both the web LinkedIn Insight Tag and this server destination, LinkedIn needs a separate conversion rule for each data source: the Insight Tag rule's ID goes in the web destination's conversion.id, the Conversions API rule's ID in conversionRuleId here. This destination sends the event's id as eventId; map eventId: 'id' on the web side so both send the same ID. LinkedIn then counts a conversion it receives from both once, under the Insight Tag rule (deduplication).

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)