LinkedIn Conversions API for WordPress

You pay LinkedIn for every click, so the demo requests those clicks produce should be visible in Campaign Manager. On many B2B WordPress sites they are only partly visible: the Insight Tag cannot see events when a script is blocked, the page closes early, or the conversion happens where the tag does not run, like a CRM stage change two weeks later.

This guide is for a B2B site that runs LinkedIn ads to a landing page with its own contact or demo form (not LinkedIn’s in-app Lead Gen Forms). It covers how the Conversions API differs from the Insight Tag, which identifiers to send, how to capture li_fat_id on the landing page, how to set up the conversion rule, what the request looks like, and where it goes wrong. All numbers come from LinkedIn’s documentation on Microsoft Learn, fetched in October 2026, and I flag what I could not confirm.

Insight Tag vs Conversions API

The Insight Tag is a JavaScript snippet on your pages. It fires in the browser, calls window.lintrk("track", { conversion_id: 12345 }) for an event, and depends on the page, the script and the visitor’s browser cooperating. The Conversions API is an HTTPS endpoint where your server streams conversion events to LinkedIn, wherever the conversion actually happened. LinkedIn’s FAQ says to use CAPI to strengthen existing tracking, with the Insight Tag and the API together measuring online and offline events, and describes it as a way to connect data without relying on cookie-based tracking.

	Insight Tag	Conversions API
Runs where	Visitor’s browser	Your server (or a service acting for it)
Typical use	Page views, form-submit clicks, on-page events	Confirmed leads, qualified leads, closed-won, offline events
Needs	Tag installed and not blocked	Access token, conversion rule, an identifier for the person
Failure mode	Page closes or script blocked before it fires	Wrong payload, expired token, retired API version
Dedup	Counted when both send the same eventId	Discarded when the Insight Tag sent the same eventId

Neither replaces the other. See client-side vs server-side tracking in WordPress and why WordPress analytics data goes missing.

Why running both adds resilience

LinkedIn’s deduplication guide recommends sending events through both the Insight Tag and CAPI “for increased reliability and a more complete view of the customer journey”. The mechanics:

• Create a conversion rule for each data source: one for the Insight Tag, one for the Conversions API.
• Generate an eventId in the browser, pass it to window.lintrk("track", { conversion_id: 12345, event_id: "..." }), and send the same value as eventId from your server.
• If LinkedIn receives an Insight Tag event and a CAPI event from the same account with the same eventId, it discards the CAPI event and counts the Insight Tag one.

In reporting you then see both conversions side by side, for example “Insight Tag demo request” and “CAPI demo request”. LinkedIn says the Insight Tag count will typically be higher when deduplication works. Platform differences are in the dedup rules reference table.

Identifiers: what LinkedIn matches on

LinkedIn can only attribute a conversion to a member it manages to match, and only matched events can be used for attribution and optimisation. Each event needs at least one identifier, and more identifiers mean a better chance of a match. The documented ID types in user.userIds are:

• SHA256_EMAIL: the email, converted to lowercase, with no whitespace, then SHA-256 hashed and hex-encoded (max 64 characters).
• LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID: the click ID, also known as li_fat_id.
• PLAINTEXT_IP_ADDRESS and SHA256_IP_ADDRESS: IPv4 only.
• ACXIOM_ID and GOOGLE_AID: partner and Android IDs, rarely relevant here.

Beyond userIds, a user object can carry userInfo (first and last name, company name, title, country code), a lead URN for LinkedIn’s own Lead Gen Form responses, and a single externalIds entry. Two rules catch people out. If you identify someone only through userInfo, lead or externalIds, you must still send userIds as an empty list. And if you include userInfo, it needs both a first and last name (from the 202609 version onward you may send hashed names instead).

For a B2B form, the pair to aim for is the hashed work email and the click ID. LinkedIn’s FAQ recommends sending both for best matching. The click ID comes from the ad click itself, which is why you capture it.

Capture li_fat_id on landing and keep it with the lead

The click ID only exists if you switch it on. In Campaign Manager, open the Insight Tag and enable enhanced conversion tracking. LinkedIn then appends li_fat_id to the landing page URL whenever someone clicks one of your ads. LinkedIn states this is on by default for recently created Insight Tags, and developers can also set firstPartyTrackingEnabled to true through the API. The click-ID documentation is here.

There are two ways to read it, and the choice affects what you can measure:

• From the URL. Works even if you do not install the Insight Tag, but LinkedIn notes view-through attribution may be limited.
• From the li_fat_id cookie. Requires the Insight Tag on your site. The cookie persists for 30 days from the most recent ad click that landed on a page with the tag, and supports view-through attribution if the visitor clicked an ad in that window.

The practical pattern for a WordPress lead form is: read the value on page load, write it into a hidden field, and let the form handler store it. Here is a minimal version based on LinkedIn’s own example:

// On every landing page
const params = new URLSearchParams(window.location.search);
const fromUrl = params.get('li_fat_id');
const fromCookie = (document.cookie.match(/(?:^|; )li_fat_id=([^;]*)/) || [])[1];
const liFatId = fromUrl || (fromCookie ? decodeURIComponent(fromCookie) : '');

// Put it in the hidden field of every lead form on the page
document.querySelectorAll('input[name="li_fat_id"]').forEach(el => el.value = liFatId);

Two practical notes. First, the URL parameter is only on the first page of a visit, so store it once (for example in sessionStorage) or rely on the cookie. Second, save the value in the lead record itself, next to the email and a generated event ID. LinkedIn says the mapping from a li_fat_id to a member profile is stored for 365 days, so a CRM stage change months after the click can still reuse the saved ID, as long as the conversion timestamp is within the 90-day window described below.

Set up the conversion rule in Campaign Manager

CAPI events need a destination. LinkedIn’s requirements are: create a conversion rule, associate campaigns with it, then stream events. In Campaign Manager this is under Ad Account, Measurement, Conversion tracking, where a rule created for the API shows its data source as Direct API or a partner integration. For a demo request, pick the LEAD type; QUALIFIED_LEAD exists for sales-qualified follow-ups, and the MARKETING_QUALIFIED_LEAD and SALES_QUALIFIED_LEAD types arrive with version 202608 and later.

Two settings deserve a decision rather than the default:

• Post-click window (default 30 days) and view-through window (default 7 days). Allowed values are 1, 7, 30 and 90 days, and 180 or 365 days for a limited set of types that includes LEAD and QUALIFIED_LEAD. B2B sales cycles are long, so check what your cycle needs, but remember you are also choosing what LinkedIn counts as yours.
• Attribution type. LAST_TOUCH_BY_CAMPAIGN (default) counts a conversion once per campaign it can be attributed to; LAST_TOUCH_BY_CONVERSION counts it once for the conversion across campaigns.

Then associate campaigns. LinkedIn is blunt: conversions can only be attributed to campaigns the rule is associated with, so a rule with no campaigns attached produces nothing in reporting. You can set autoAssociationType when creating the rule through the API (up to 200 campaigns for ALL_CAMPAIGNS), or attach campaigns in Campaign Manager. The rule needs an ID that goes into events as urn:lla:llaPartnerConversion:{id}. You can read it from the rule’s URL in Campaign Manager, the part after /conversions/.

OAuth: the token and scopes

The Conversions API uses 3-legged OAuth. The documented permissions are rw_conversions (upload conversion data and manage conversion tracking) and r_ads (read the member’s ad accounts). The person who grants access must hold one of these roles on the ad account: ACCOUNT_BILLING_ADMIN, ACCOUNT_MANAGER, CAMPAIGN_MANAGER or CREATIVE_MANAGER.

Three details to plan for, from LinkedIn’s OAuth documentation:

• All access tokens are currently issued with a 60-day lifespan. A token you create today stops working in about two months.
• Programmatic refresh tokens are available only to a limited set of partners. For most advertisers, renewing means going through the authorization step again.
• If your app requests a different scope than before, previously issued tokens for the old scope are invalidated.

Ask any tool you use what happens on day 61, and put a reminder in your calendar.

The request: endpoint, headers and payload

A single event goes to POST https://api.linkedin.com/rest/conversionEvents. Every request needs these headers:

• Authorization: Bearer {token}
• Content-Type: application/json
• Linkedin-Version: YYYYMM (for example 202609)
• X-Restli-Protocol-Version: 2.0.0

A minimal body for a demo request looks like this:

{
  "conversion": "urn:lla:llaPartnerConversion:104012",
  "conversionHappenedAt": 1790934072000,
  "eventId": "lead-8841",
  "conversionValue": { "currencyCode": "USD", "amount": "250.0" },
  "user": {
    "userIds": [
      { "idType": "SHA256_EMAIL",
        "idValue": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d" },
      { "idType": "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
        "idValue": "<li_fat_id saved with the lead>" }
    ]
  }
}

The hash above is the SHA-256 of jane.doe@example.com, lowercase. In PHP, hash('sha256', strtolower(trim($email))) produces the same thing. Here is what each field does:

• conversion is the rule URN.
• conversionHappenedAt is an epoch timestamp in milliseconds. If your system stores seconds, add three zeros. It must be within the past 90 days or the request fails.
• eventId is optional, but it is what deduplication runs on. Use a stable ID per lead, not a random one per attempt, so retries and the browser event refer to the same thing.
• conversionValue is optional: an ISO currency code and the amount as a decimal string.

A success returns 201 Created. A 400 means validation failed and the message names the cause. 401 means an empty token and 403 means the user lacks access to the ad account or the permissions. For batches, set the X-RestLi-Method: BATCH_CREATE header and wrap events in an elements array.

Limits you can plan around

LinkedIn documents a maximum of 600 requests per minute and 500,000 requests per day through your member access token, and up to 5,000 conversion events in each batch request. A lead form will not come near these. The batch rule matters more than it looks: if any value in a batch is invalid, all records fail and you must resubmit the whole payload after fixing it (the error includes a batchIndex pointing at the offender).

Timing and attribution windows

LinkedIn says it takes up to 24 hours to complete ingestion and an additional 48 hours for reporting, so complete data can take up to 72 hours to show up. Send events in real time, or ideally within a day, so the campaign can use them while they are fresh.

On attribution reach, the FAQ states conversions can be attributed for up to a maximum of 180 days for most conversion types, made up of 90 days for the conversion timestamp and 90 days of attribution lookback. That matches the API error message about conversion time needing to be within 90 days. For LEAD, QUALIFIED_LEAD, PURCHASE, ADD_TO_CART, SUBMIT_APPLICATION and the newer MQL and SQL types, you can additionally choose a 180 or 365-day window on the rule. So “180 days” is the general maximum, not the whole story for lead types.

API versions: the maintenance cost nobody puts in the pitch

LinkedIn’s marketing API is versioned. You pass Linkedin-Version: YYYYMM on every call, and the latest version is not applied by default. A missing or deprecated version header returns an error. New versions ship monthly and each is supported for a minimum of one year. When I re-fetched the versioning page in early October 2026, the latest version was 202609, and a notice on the page said Marketing version 202510 would be sunset on 15 October 2026. This post goes live after that date, so treat 202510 as retired: the example above uses 202609, and you should check the page for a newer one.

That has real consequences for a direct integration:

• An integration that still sends a sunset version can start failing with the deprecated-header error, even though nothing in your code changed.
• Features differ by version: hashed names arrive in 202609, MQL and SQL types in 202608.
• LinkedIn’s own FAQ says a direct integration needs developer resources and ongoing maintenance, and lists a typical build at 1 to 2 weeks.

LinkedIn describes migration as updating the header value, so the work is remembering to do it yearly, before an error tells you. If that is a chore you would rather hand off, a partner integration is a fair choice (LinkedIn lists Google Tag Manager, Zapier, Dreamdata, Supermetrics, Tealium and Adobe) or a forwarding service.

Setup checklist

Pitfalls

• Rule exists, no campaigns attached. Events are accepted but nothing is credited. Attach the campaigns.
• Old timestamps. Anything beyond 90 days fails. A late CRM sync can push a lead outside the window.
• Email not normalised. Hash Jane.Doe@Example.com and you get a different hash from jane.doe@example.com. Lowercase first, trim whitespace.

How this works in Traculo

Traculo’s WordPress plugin forwards site events from Traculo’s servers to LinkedIn’s Conversions API, alongside GA4, Meta, Google Ads, TikTok, Snapchat, Pinterest and Plausible. Each event has a delivery log with LinkedIn’s response, with CSV and JSON export, which is where you would spot an expired token or a rejected payload.

The honest limits: you still create the conversion rule and attach campaigns in Campaign Manager yourself, you need a valid token with the right scopes and a plan to renew it, and matching only works if the email or click ID is on the event. In Traculo you paste in your access token and ad account ID, and Traculo does not renew the token for you; an expired one shows as an error in the delivery log. You map each site event to a conversion rule, unmapped events are skipped (logged as “Skipped: no mapping”), and requests use the LinkedIn-Version 202509 header.

Frequently asked questions

Related reading

• Meta Conversions API for WordPress: the complete guide
• Dedup rules and limits on every ad platform
• Google Ads offline conversions for WordPress leads
• TikTok, Snapchat and Pinterest Conversions API on WooCommerce
• Track form submissions in WordPress: CF7, WPForms, Gravity Forms
• Meta CAPI deduplication, event_id explained
• Server-Side Tracking for WordPress: a beginner’s guide
• Client-side vs server-side tracking in WordPress

If you would rather not maintain the payloads, hashing and version headers yourself, Traculo’s WordPress plugin forwards your lead events to LinkedIn and logs every response. See the integrations page to check whether it fits your setup.