LinkedIn Conversions API
Server-side event delivery to LinkedIn's Conversions API for ad attribution.
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- Integrated
- Bundled
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',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"linkedin": {
"package": "@walkeros/server-destination-linkedin",
"config": {
"settings": {
"accessToken": "$secret.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
| Property | Type | Description | More |
|---|---|---|---|
accessToken | string | LinkedIn OAuth 2.0 Bearer token for Conversions API authentication | |
conversionRuleId | string | Default LinkedIn conversion rule ID from Campaign Manager | |
apiVersion | string | Linkedin-Version header value in YYYYMM format | |
doNotHash | Array<string> | Array of user data fields that should not be hashed | |
url | string | Custom URL for the LinkedIn Conversions API, ending in / | |
user_data | Record<string, string> | Mapping configuration for user data fields |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
conversion | conversion | Per-event conversion override with ruleId, value, and currency | |
ruleId | string | Override conversion rule ID for this event | |
value | string | number | Conversion monetary value | |
currency | string | ISO 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.
{
"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"
}
}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.
{
"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"
}
}{
"settings": {
"conversion": {
"map": {
"value": "data.value",
"currency": {
"key": "data.currency",
"value": "EUR"
}
}
}
}
}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.
{
"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"
}
}{
"settings": {
"conversion": {
"map": {
"value": "data.value",
"currency": {
"key": "data.currency",
"value": "USD"
}
}
}
},
"data": {
"map": {
"user_data": {
"map": {
"li_fat_id": "context.li_fat_id"
}
}
}
}
}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
failedwith codemissing-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
failedwith codemissing-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.
Consent
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).