LinkedIn Marketing API Versioning Documentation

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Overview

At LinkedIn, we’re continuously evolving our product offerings. And it’s important that our API partners are supported in that journey with the tools and experiences that enable them to continue to innovate and deliver the best solutions to our mutual customers.

We know you value stable API integrations. We also know that it’s important to have clear guidance on how to plan and make changes to your integrations. You experiment, build, test, and deploy new products all the time.

Because of this, we’re introducing API versioning across our LinkedIn Marketing API Program. We’ll be ensuring your active integrations continue working while you’re working on integrating our latest changes.

What’s changing?

LinkedIn’s Marketing APIs first versioned API release was June 2022 under a new base path: https://api.linkedin.com/rest/

Our versioned API releases are on a monthly cycle. There are several subtleties that will be different from the former release cycle:

Legacy (unversioned) Marketing APIs using the base path https://api.linkedin.com/v2/ will be available until June 30, 2023 when they will be sunset. Some of our legacy APIs (V2) have also been renamed and will be published according to the following table:

Legacy endpoint	Versioned endpoint
/adInMailContentsV2	/adInMailContents
/audienceCountsV2	/audienceCounts
/adSegmentsV2	/adSegments
/adAnalyticsV2	/adAnalytics
/sharesV2	/posts
/ugcPosts	/posts
/adAccountsV2	/adAccounts
/adAccountUsersV2	/adAccountUsers
/adCampaignGroupsV2	/adCampaignGroups
/adCampaignsV2	/adCampaigns
/adCreativesV2	/creatives
/insightTagDomainsV2	/insightTagDomains
/adCampaignInsightsV2	/adCampaignInsights

API clients will use HTTP headers to indicate the API version. Releases are titled according to the month in which the development work commenced - again, similar to the way we have pushed releases in the past. Comprehensive documentation and change guides will accompany each release. Our versioned Marketing APIs will be supported and stable for a minimum of one year before sunset.

Technical documentation

LinkedIn’s LinkedIn Marketing API Program supports versioning so API partners can release changes over time. This document explains how to use versioned APIs.

Why are our APIs versioned?

LinkedIn makes continuous improvements to our products, and thus our APIs must change too. But we want our API partners to have trust in stable integrations with reliable change schedules so that they can plan and execute better over time.

That’s why we’ve created a stable supported window of one (1) year (minimum) for our Marketing APIs.

How your API client should use versioning

HTTP headers will be used for clients to indicate which API version implementation they expect. Include a request header with the key “LinkedIn-Version” and set the value to the version (format: YYYYMM) to correspond with the documentation version you’re referencing, for example - “LinkedIn-Version: 202304” would indicate that you are using the version published in the month of April.

curl -X POST 'https://api.linkedin.com/rest/adCampaigns' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Linkedin-Version: 202304’ \
--data '{
    "account": "urn:li:sponsoredAccount:123212321",
    "audienceExpansionEnabled": false,
...

Version Headers

In many cases, the URL resource paths your integration uses may not change across versions, but the behavior of the individual API methods will. For example, there may be new parameters required or new fields available on the response schemas.

The API changes must include the Version Header for the version (release) that needs to be adopted. For example, for the April 2023 LMS Release, the versioned header would be: "LinkedIn-Version": "202304"

Version headers are tied to the LMS Release date:

Version	Version Header Values
February 2023	"LinkedIn-Version": "202302"
March 2023	"LinkedIn-Version": "202303"
April 2023	"LinkedIn-Version": "202304"

Versioned API Docs

Each version of the LinkedIn Marketing API Program has distinct and comprehensive documentation covering all supported APIs. It also includes a changelog indicating all changes from the previous version indicating which resources have been updated or added. Initially, users will have the option on each page in the marketing folder to view: Versioned content: “Marketing {Month} 202X”, or Unversioned content (prior to June 2022) using the dropdown selector.

Version Cadence

LinkedIn Marketing API Program will publish new versions monthly, and those versions will be supported for a minimum of one (1) year.

Individual API resources may evolve at different times (e.g. a reporting API may be updated one quarter a year). And each API resource will have its own migration guide to help you navigate major updates.

You could choose to integrate with the newest API changes as soon as they’re released or wait until you’re ready - as long as it’s within the one year change API support window.

Expectations

Keep up with us

LinkedIn expects that our LinkedIn Marketing API Program API partners work to deliver the latest and most valuable experiences to our customers within a reasonable time of their availability. As a result, we will sunset our API versions as early as one (1) year after release.

No unversioned calls

LinkedIn expects every versioned API call to specify a version; we will not default you to the latest version. It’s important to us that customers have the best possible experience with LinkedIn integrations. And it’s more likely that customers have a great experience when the integration is being regularly maintained (at least once per year).

Breaking Change Exceptions

At times, LinkedIn may need to change APIs within the supported stable window.

LinkedIn reserves the right to release a patch version to any API if required for any critical security or privacy issues or bug fixes. While the likelihood of these scenarios is minimal, we will work closely with partners to minimize the impact of any breaking changes.

FAQ

Which versions can I use?

You can use any version that hasn’t been sunset. The documentation will reflect all available API versions. Migrating to the latest version, however, comes with two important benefits:

• You can take advantage of all of our latest features.
• You have the option to wait up to a full year before having to migrate again.

What about other LinkedIn APIs outside of Marketing?

At present these APIs are unversioned, which may be subject to change at any time at the discretion of product ownership teams.

How do I migrate from an older API version to a later version?

To migrate your app from an older version to a later version, simply update the older version‘s YYYYMM formatted value in the header to the later version’s value. For example, here’s how you’d migrate from the June 2022 version to the June 2023 version.

-H ‘Linkedin-Version: 202206’  to  -H ‘Linkedin-Version: 202306’

Reasons for migrating to a later version include:

• Avoiding service disruptions; it's important to upgrade to a newer supported version before the older version is no longer supported (we’ve committed to supporting each version for a minimum of one year).
• Utilizing new features that are not accessible in the older version.

Which version of the API should I migrate to?

While you can migrate to any later version of the API, migrating to the latest version comes with two important benefits:

• You can take advantage of all of our latest features.
• You have the option to wait up to a full year before having to migrate again.