# LinkedIn Conversions API for B2B SaaS: connect campaigns to qualified outcomes

Canonical URL: https://www.martechdevs.com/blog/linkedin-conversions-api

By [Jafrin Akter Alo](https://www.martechdevs.com/authors/jafrin-akter-alo)

Data Engineer and Co-founder, martechdevs

Published: 2025-04-28

Last updated: 2026-10-12

LinkedIn Conversions API sends business outcomes from your systems to LinkedIn so eligible conversions can be matched and attributed to advertising. For B2B SaaS, the useful application is connecting a campaign to a later qualification, opportunity or customer milestone. Start with a reliable CRM definition and a delivery process you can reconcile. An API connection cannot repair ambiguous stages, missing contact relationships or an inflated pipeline value.

## Choose the outcome before the integration

A form submission tells you someone submitted a form. It does not establish that they fit your product, have a buying problem or entered a sales process. Feeding only form submissions back to an advertising platform can leave the marketing team judging campaigns on a different outcome from the one sales cares about.

Choose a milestone your team can verify. For example: a sales rep accepts a qualified opportunity after confirming the account fits your service and the buyer has a relevant project. Define the required evidence, who records it and when that decision becomes final enough to send.

Keep the earlier lead event if it remains useful, but give each stage its own meaning. Do not rename all leads “qualified” to increase the number of conversion signals.

Before building, answer four questions:

- Which business change should produce one event?
- Which entity reaches that milestone: a person, account or opportunity?
- Where is the original occurrence time recorded?
- What action will the campaign team take differently with this information?

If the CRM cannot distinguish a genuine qualification from a bulk cleanup, fix that first. The [lead-scoring guide](https://www.martechdevs.com/blog/lead-scoring-model) helps separate fit, intent and demonstrated qualification. A score crossing a threshold is only a useful conversion definition when the threshold represents an outcome the business trusts.

## Select the simplest route that preserves the meaning

There are three reasonable starting points. Compare their handling of data and failures, not just the number of setup steps.

### HubSpot's native conversion events

HubSpot supports LinkedIn conversion events based on contact lifecycle changes. Its current guide says only stage updates occurring after the conversion event is created count through that configuration. Review the mapped LinkedIn type, shared fields and consent-property settings. A historical list of already-qualified contacts is not automatically a backfill. [HubSpot's setup instructions](https://knowledge.hubspot.com/ads/create-and-sync-ad-conversion-events-with-your-linkedin-ads-account) describe the available settings and subscription requirements.

This route is useful when your agreed outcome really is a contact lifecycle transition. It becomes less straightforward when your commercial truth lives on opportunities, several contacts belong to one deal, or the same person can participate in different purchases.

For example, changing three contacts at one company to “Customer” does not necessarily mean three new customer accounts. Decide the counting unit before mapping the event.

### A supported partner connection

A connector can reduce the infrastructure you maintain. Inspect which objects and changes it supports, whether it preserves occurrence time, how it records failed deliveries and whether you can replay one event safely. Ask to see the actual field mapping before assuming that “CRM integration” includes your opportunity-stage logic.

LinkedIn distinguishes advertiser and partner access routes in its [Conversions API overview](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/conversions-overview). Use the route appropriate to the integration. An advertiser implementing its own connection should not assume it needs to complete the same onboarding as a vendor building a product for many advertisers.

### A direct connection from your application or warehouse

Choose a direct integration when you need explicit opportunity logic, controlled identity mappings or a delivery ledger your team owns. Budget for authentication, monitoring, API changes and failed-event recovery as part of the implementation.

An advertiser can generate a Direct API access token in Campaign Manager under Measure, Signals manager and Direct API. Store it in the server's secret-management system. LinkedIn's [Direct API instructions](https://www.linkedin.com/help/lms/answer/a1711116) explain token creation and conversion setup. Never put the token into a website tag, client bundle or shared spreadsheet.

For Salesforce or another CRM, treat the following as a design pattern: consume the relevant recorded stage change, resolve the associated person under your chosen rule, construct the event and send it through the selected connection. Confirm the available change-history mechanism in your own CRM setup. Polling today's stage without retaining previous state can turn every daily sync into another supposed qualification.

![Verified CRM milestone passes eligibility and identity checks, stable event creation, API delivery, attribution and campaign-quality review](https://www.martechdevs.com/assets/blog/linkedin-conversions-api.svg)

## Define a CRM event that survives retries and edits

Write a small event contract before mapping fields. A useful starting point contains:

- Outcome: the exact stage transition and evidence required.
- Entity: the opportunity or contact that qualifies under your counting rule.
- Episode: the particular occurrence when repeated qualification is legitimately possible.
- Occurred at: the recorded time of the milestone, with a known timezone.
- Identity: the eligible person's identifiers and their relationship to the entity.
- Delivery state: pending, accepted or failed, with a reason and attempt history.

Suppose opportunity `opp_1042` first becomes sales-qualified on Monday. A Tuesday retry must carry the same business-event identity and Monday's occurrence time. Updating the opportunity amount on Wednesday should not create another qualification unless your written definition deliberately says it should.

If the opportunity moves backwards and later qualifies again, decide whether that is a correction or a new episode. Make the rule consistent across the warehouse and CRM. A platform cannot infer your intended business semantics from a stage label.

Resolve the person deliberately, too. The opportunity owner is your employee, not the buyer. A generic billing address is not necessarily the contact who interacted with an ad. Do not send an event for every associated person just because the CRM provides a list of contacts.

For an account-level outcome, retain the account and opportunity relationships in your own analysis even when the delivery payload represents a person. Our [single-customer-view guide](https://www.martechdevs.com/blog/single-customer-view) covers the identity relationships needed to avoid confusing people with customer accounts.

## Configure the rule, associations and payload separately

LinkedIn's [API implementation guide](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api?view=li-lms-2026-09) requires a conversion rule, campaign associations and streamed events. These are separate checks. An accepted event cannot receive campaign credit through an association that does not exist.

Create the rule with the correct account, outcome type and `CONVERSIONS_API` method. Review the actual associated campaigns after creation, including any automatic association. Do not assume that selecting an automatic mode covers every campaign you might want to evaluate.

Direct requests also require the documented authentication and version headers, including `Linkedin-Version` and `X-Restli-Protocol-Version`. Use a currently supported API version and assign responsibility for upgrading it. Copying an old tutorial's version indefinitely is a maintenance failure waiting to happen.

The following is a payload inspection fixture, not a request to run against a live account. The rule ID and event identity are fictional. The hash represents the reserved example address `ada.example@example.com`; replace all example values through your validated mapping.

```json
{
  "conversion": "urn:lla:llaPartnerConversion:123",
  "conversionHappenedAt": 1791799200000,
  "eventId": "opp_1042:sql:episode_1",
  "user": {
    "userIds": [
      {
        "idType": "SHA256_EMAIL",
        "idValue": "c9a113580a216ed5b18c6a941ff6735df99a072d83c0ec780487e7bbad894d5f"
      }
    ]
  }
}
```

The timestamp represents 12 October 2026 at 10:00 UTC. LinkedIn expects milliseconds since the Unix epoch. Email identifiers use lowercase, whitespace-free input followed by SHA-256 hashing to hexadecimal. Follow the [current event schema](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api-schema?view=li-lms-2026-09) for your chosen identifiers.

Do not apply another platform's email transformations automatically. Preserve the original CRM record and create destination-specific representations at the delivery boundary. Hashing the already-hashed value again produces a different identifier, even though the result still looks like a valid hash.

Keep personal data out of event IDs, job names and routine error logs. Record enough information to trace an internal outcome without making every operational surface a copy of the customer's details.

## Deduplicate repeated representations of the same outcome

Two events require deduplication when they represent the same business occurrence. A website submission and a qualification three weeks later are different outcomes. They should not share an event ID merely because they concern the same person.

For an outcome sent through both Insight Tag and Conversions API, LinkedIn documents separate conversion rules for the browser and server sources. Send the same `eventId` for the corresponding occurrence in the same ad account. When LinkedIn identifies that pair, it counts the Insight Tag event and removes the redundant CAPI event from campaign reporting. Follow the [LinkedIn deduplication implementation](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/deduplication?view=li-lms-2026-09).

This means lower reported CAPI counts can be expected when browser and server coverage overlap correctly. A target of equal browser and server attributed totals would be the wrong acceptance criterion.

Your own sender still needs retry controls. Store whether an outcome was queued and its previous delivery result. A timeout is not proof the remote system received nothing. Preserve the event identity when retrying, use the documented response semantics, and investigate recurring failures instead of generating fresh IDs until one appears successful.

Test three distinct cases: browser only, server only and both sources representing one occurrence. Then test two legitimate outcomes for the same person. The second outcome must remain distinguishable from a retry of the first.

## Separate three clocks in a long sales cycle

Long B2B sales cycles create three different timing questions: when the buyer interacted with advertising, when the business outcome occurred and when your integration delivered the event.

Uploaded events must have occurred within the past 90 days, as the [HubSpot integration guide](https://knowledge.hubspot.com/ads/create-and-sync-ad-conversion-events-with-your-linkedin-ads-account) explains. Attribution windows answer a different question: how far an eligible outcome can sit after an ad interaction. LinkedIn's [conversion-window guidance](https://www.linkedin.com/help/lms/answer/a426360) allows 180- and 365-day windows for specified CAPI conversion types.

A five-month sales cycle does not mean you should hold an outcome in a queue for five months. Send the newly reached milestone promptly with its real occurrence time. Its potential relationship to an older ad interaction depends on the configured attribution window and other matching conditions.

Inspect the saved rule rather than relying on a general statement about defaults. LinkedIn's API schema lists 30-day click and seven-day view defaults, while HubSpot's integration guide describes a 90-day default for its configuration. HubSpot also directs users to Campaign Manager to adjust eligible longer windows. Those are route-specific instructions, not interchangeable settings. [LinkedIn schema](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api-schema?view=li-lms-2026-09), [HubSpot integration guide](https://knowledge.hubspot.com/ads/create-and-sync-ad-conversion-events-with-your-linkedin-ads-account).

Keep window choices visible in the campaign review. A report using a longer view-through window answers a broader attribution question than a narrowly timed click-only analysis. Neither should quietly replace the company's customer and revenue records.

## Reconcile the integration before judging the campaign

Use four separate checkpoints:

1. Business eligibility: the CRM contains a genuine milestone with the required identity and data-sharing eligibility.
2. Delivery: the sender attempted the event and recorded the response correctly.
3. Platform processing: matching, association, timing and deduplication determine whether the received event becomes attributable.
4. Commercial analysis: the outcome joins to the correct account, opportunity and reporting cohort.

If CRM outcomes exceed reported conversions, identify which checkpoint explains the gap. Inspect individual examples across successful, failed and absent cases. “The API is working” is too vague to distinguish an unauthorised request from a valid event with no eligible ad interaction. Allow for processing: LinkedIn's [Conversions API FAQ](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/conversions-faq) describes up to 24 hours for ingestion and another 48 hours for reporting. Check completed periods before declaring recent events missing.

Useful failure questions include:

- Did the sender read a real transition or repeatedly export the current state?
- Was the person eligible for this destination under the configured sharing rules?
- Did an identifier change or disappear during the CRM-to-warehouse join?
- Does the payload reference the intended account's conversion rule?
- Are the relevant campaigns associated with that rule?
- Is the original time in milliseconds, and does it fall within the accepted range?
- Is the event already represented by a deduplicated browser event?

The rule's attribution model also affects totals. LinkedIn supports crediting each eligible ad set or the last eligible ad set. Inspect that setting before summing reports into a company-wide customer total. For most conversion types, repeated conversions by one member within the window are also counted differently from Purchase and Add to Cart events. These platform counting rules can differ from your CRM's distinct opportunity count. [Attribution models](https://www.linkedin.com/help/lms/answer/a426349/linkedin-conversion-attribution-model?lang=en), [conversion-window counting rules](https://www.linkedin.com/help/lms/answer/a426360).

## Use qualified outcomes to improve decisions

Consider a fictional comparison of two equally mature lead cohorts. Each campaign spent $6,000. Campaign A produced 200 leads and ten qualified opportunities. Campaign B produced 100 leads and 25 qualified opportunities.

Campaign A costs $30 per lead and $600 per qualified opportunity. Campaign B costs $60 per lead and $240 per qualified opportunity. A lead-volume dashboard makes A look cheaper. The qualification definition changes the decision.

This is an arithmetic example, not a claim about LinkedIn performance. Before reallocating budget, check that qualification is applied consistently, the cohorts have had comparable time to mature, follow-up quality is similar and the opportunities are commercially comparable. A campaign targeting larger enterprises may progress more slowly while creating greater value.

Do not attach full opportunity value to every stage and add the results as revenue. Qualification, pipeline creation and a won customer describe different milestones in the same possible purchase. If you assign an estimated value to a qualified lead, label the estimation method and keep it separate from contracted or collected revenue.

CAPI gives you another measurement input. It does not prove the advertising caused every attributed opportunity. Use the [attribution and incrementality guide](https://www.martechdevs.com/blog/attribution-vs-mmm-vs-incrementality) when the decision is whether extra advertising spend creates extra business.

## Define what completion looks like

- [ ] Sales and marketing agree on the outcome, counting unit and requalification rule.
- [ ] The selected integration preserves the original occurrence time.
- [ ] Identity and sharing eligibility are checked before delivery.
- [ ] Conversion rules and campaign associations are verified in the intended account.
- [ ] Duplicate-source events share the correct occurrence ID; different milestones do not.
- [ ] Failed deliveries have an owner, a reason and a safe recovery path.
- [ ] Reporting shows the actual attribution settings and cohort maturity.
- [ ] API versions, credentials and connector changes have an operating owner.

An [analytics and tracking implementation](https://www.martechdevs.com/analytics-tracking) should leave a traceable path from the CRM milestone to the campaign report. That makes the integration useful for a budget decision and maintainable when your sales process changes.

## Frequently asked questions

### Does Conversions API replace the LinkedIn Insight Tag?

It provides another delivery route. Choose the combination required for your measurement and website use cases. When both routes send the same outcome, implement LinkedIn's documented deduplication instead of counting the two representations independently.

### Can I send HubSpot or Salesforce stages to LinkedIn?

HubSpot documents a native lifecycle-stage integration. For Salesforce or a custom CRM, verify the selected connector or implement a supported direct mapping from recorded changes. Define the entity and milestone before turning stage labels into conversion events.

### Can LinkedIn measure a sales cycle longer than 90 days?

Some conversion types support longer attribution windows. The event-ingestion age limit is separate. Check the rule's saved window and send milestones promptly when they occur rather than changing their timestamps to make them fit.

### Why are accepted events missing from campaign reports?

Acceptance is one checkpoint. Matching, eligible ad interactions, campaign associations, attribution settings, timing and deduplication can affect reported credit. Reconcile representative events through those stages before treating the difference as lost delivery.

### Should every CRM stage optimise the campaign?

Choose the outcome that best supports the campaign's purpose and the platform's available configuration. Keep diagnostic stages separate from the commercial outcome you intend to improve. More event types do not automatically create a better optimisation signal.

## Sources

1. [HubSpot: LinkedIn ad conversion events](https://knowledge.hubspot.com/ads/create-and-sync-ad-conversion-events-with-your-linkedin-ads-account)

2. [LinkedIn: Conversions API overview](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/conversions-overview)

3. [LinkedIn: Set up Direct API conversions](https://www.linkedin.com/help/lms/answer/a1711116)

4. [LinkedIn: Conversions API implementation](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api?view=li-lms-2026-09)

5. [LinkedIn: Conversion rule and event schema](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api-schema?view=li-lms-2026-09)

6. [LinkedIn: Browser and server deduplication](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/deduplication?view=li-lms-2026-09)

7. [LinkedIn: Conversion windows and counting](https://www.linkedin.com/help/lms/answer/a426360)

8. [LinkedIn: Attribution models](https://www.linkedin.com/help/lms/answer/a426349/linkedin-conversion-attribution-model?lang=en)

9. [LinkedIn: Conversions API FAQ](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/conversions-faq)