Server-side events · Platform reference
LinkedIn Conversions API: events, fields and dedup rules
LinkedIn Conversions API streams conversion events from your server to a conversion rule (conversionMethod CONVERSIONS_API) via POST /rest/conversionEvents, matched on hashed email, the li_fat_id click ID and other identifiers. Events arrive but don't attribute when the conversion rule isn't associated with the campaigns, when the event can't be matched to a member (only matched events are used for attribution), or when conversionHappenedAt is outside the past 90 days or sent in seconds instead of milliseconds.
Read from the official documentation on 9 November 2026. Sources are listed at the end.
Endpoint and authentication
POST https://api.linkedin.com/rest/conversionEvents
OAuth 2.0 (3-legged) Bearer token with rw_conversions and r_ads scopes, from a user holding ACCOUNT_BILLING_ADMIN, ACCOUNT_MANAGER, CAMPAIGN_MANAGER or CREATIVE_MANAGER on the ad account. Every request also needs the Linkedin-Version: {yyyymm} and X-Restli-Protocol-Version: 2.0.0 headers
Standard event names
Spelled exactly as LinkedIn expects them. A near miss is treated as a different event.
| Event | Use it for |
|---|---|
| PURCHASE | conversion rule type; supports 180/365-day windows |
| LEAD | lead form filled; supports 180/365-day windows |
| QUALIFIED_LEAD | qualified lead; usable as an optimisation target for Lead Gen campaigns |
| MARKETING_QUALIFIED_LEAD | API version 202608+ |
| SALES_QUALIFIED_LEAD | API version 202608+ |
| SIGN_UP | sign-up |
| SUBMIT_APPLICATION | application submitted |
| ADD_TO_CART | add to cart |
| START_CHECKOUT | checkout started |
| REQUEST_QUOTE | quote requested |
| BOOK_APPOINTMENT | appointment booked |
| START_TRIAL | trial started |
| KEY_PAGE_VIEW | important page view |
| CONTACT | contact via form or phone |
Required and recommended fields
| Field | What it needs |
|---|---|
| conversion | Conversion rule URN, format urn:lla:llaPartnerConversion:{id}; the rule must be enabled (not deleted) |
| conversionHappenedAt | Epoch time in MILLISECONDS; must be within the past 90 days. If your source records seconds, append 000 |
| user.userIds | List of {idType, idValue}; at least one valid ID, or an empty list [] when identifying the user only by userInfo, externalIds or lead |
| user.userInfo | Optional. If included: firstName + lastName (plain text), or from 202609 hashedFirstName/hashedLastName; plus optional companyName, title, countryCode |
| conversionValue | Optional {currencyCode (ISO), amount (decimal string)} |
| eventId | Optional advertiser-generated unique ID used for deduplication with the Insight Tag |
| X-RestLi-Method: BATCH_CREATE | Header for batch requests of up to 5,000 events |
Match keys and hashing
| Key | Normalise and hash |
|---|---|
| SHA256_EMAIL | Lowercase, no whitespace, then SHA-256 as a HEX string (max 64 characters) |
| LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID | Not hashed. The li_fat_id click ID / first-party cookie value |
| PLAINTEXT_IP_ADDRESS | Plain text, IPv4 only; LinkedIn hashes it with salt before matching |
| SHA256_IP_ADDRESS | IPv4 only, SHA-256 HEX of exactly 64 characters |
| ACXIOM_ID | Identifier for matching with the LiveRamp identity graph |
| GOOGLE_AID | Android advertising ID |
| userInfo.hashedFirstName / hashedLastName | Lowercase, no spaces or punctuation, special characters UTF-8 encoded, then SHA-256 HEX of 64 characters (version 202609+) |
| externalIds | Advertiser ID (max 1 used). Only matches when sent together with standard identifiers; after that LinkedIn keeps the mapping for one year |
Click ids
| Click id | Where it comes from |
|---|---|
| li_fat_id | Appended to landing page URLs on LinkedIn ad clicks once 'Enhanced conversion tracking' (first-party cookies) is on for the Insight Tag (default for new tags). Parse it from the URL, or read the li_fat_id cookie if the Insight Tag is installed. The cookie lasts 30 days from the last ad click; LinkedIn keeps the li_fat_id-to-member mapping for 365 days. Send it as LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID |
Deduplication
- To deduplicate, create a separate conversion rule for each data source (browser and server), capture the eventId in the browser, and send the same eventId with the server event.
- If LinkedIn receives an Insight Tag event and a Conversions API event from the same account with the same eventId, it discards the Conversions API event and counts only the Insight Tag event.
- Browser side: set window._linkedin_event_id before the Insight Tag base code for page-load conversions, or call window.lintrk('track', { conversion_id, event_id }) for event conversions; image pixels take &eventId=.
- Check that it works in the conversion breakdown: when dedup is working, the Insight Tag conversion normally shows the higher count.
Time limits and batch sizes
- conversionHappenedAt must be within the past 90 days (INVALID_CONVERSION_TIME_FIELD_VALUE otherwise).
- Up to 5,000 conversion events per BATCH_CREATE request; one invalid record fails the whole batch.
- Rate limits per member access token: 600 requests per minute and 500,000 requests per day.
- Conversion rule post-click windows: 1, 7, 30 or 90 days (default 30); 180 or 365 only for limited types. View-through default is 7.
- Marketing API version 202511 sunsets on 16 November 2026, so send a current Linkedin-Version header.
How to test before you trust it
- Payload Builder: linkedin.com/developers/payload-builder builds a conversion events payload from your inputs.
- Campaign Manager conversion breakdown: After associating campaigns, compare the Insight Tag and CAPI conversion counts to confirm events arrive and deduplication works.
- API error responses: 400 responses include batchIndex and a type such as INVALID_CONVERSION_TIME_FIELD_VALUE or INVALID_USER_IDENTIFICATION_FIELD_VALUE; 422 for missing conversionHappenedAt or user.userIds.
Why events arrive but don't attribute
- The conversion rule isn't associated with your campaigns. Conversions can only be attributed to campaigns associated with the rule, and if you omit autoAssociationType at creation, nothing is associated automatically.
- conversionHappenedAt sent in seconds instead of milliseconds, so the timestamp reads as 1970 and fails the 90-day check.
- No li_fat_id: enhanced conversion tracking is off for the Insight Tag, a redirect strips the URL parameter, or the conversion happens more than 30 days after the click, after the cookie has expired.
- Events that don't match a member are never used. LinkedIn says only matched events count for attribution and optimisation, so send several identifiers per event.
- Email hashed without lowercasing or trimming, or an IPv6 address sent. IP matching is IPv4-only.
- Pixel and CAPI tracked under a single conversion rule. LinkedIn's dedup requires a rule per data source plus a shared eventId.
- Events sent to a disabled or deleted conversion rule are rejected. The rule must have enabled=true.
- externalIds sent on its own before LinkedIn has seen it alongside a standard identifier, so there's nothing to match yet.
Sources
- LinkedIn (Microsoft Learn): Conversions API
- LinkedIn (Microsoft Learn): Conversions API Schema
- LinkedIn (Microsoft Learn): Deduplication
- LinkedIn (Microsoft Learn): Enabling Click IDs
Platforms change these rules without notice. If a source says something different from this page, the source wins.