Partager via

Recent Marketing API Changes

  • Article

Warning

Deprecation Notice
The Marketing Version 202311 (Marketing November 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will 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.

November 2024 - Version 202411 (Latest)

Product & Platform Announcements

  • Conversions API: External IDs Support

    Starting with the 202410 version, we’ve introduced an optional externalIds field to the user object in the request payload for POST /conversionEvents. This allows you to send unique custom identifiers (such as user IDs, loyalty membership IDs, and external cookie IDs) to improve signal quality, identity resolution, and match rates—all without repeatedly sending the same PII. If we match a LinkedIn member from user attributes in the event, the ‘externalIds’ provided will be associated with that member. For future events, simply sending ‘externalIds’ will enable us to match based on that identifier alone.

  • Ad Previews API: Live Preview for Ad Creatives

    Starting with the 202411 version, partners can preview ad creatives before the ads are created, through the Live Preview feature. We have introduced two new methods on /adPreviews endpoint: action=livePreviewForCreative and action=livePreviewForCreativeInline to support previews for both creatives and creative inline content. You can embed the HTML iFrame tag returned in the response to render live preview for both Desktop and Mobile placements. This feature supports the following ad formats: Single image ad, Carousel ad, Video ad, Single job ad and Event ad.

  • Ad Analytics API: New Metrics audiencePenetration and averageDwellTime

    We are introducing two new metrics via Ad Analytics API:

    • Audience Penetration: This measures the approximate number of unique members reached by the advertiser divided by the approximate total target audience. Currently, this metric is not available at the creative level. Read more.
    • Average Dwell Time: This measures the average time (in seconds) that users spend viewing the ad when at least 50% of the pixels are present on the screen. Learn more.

  • Insight Tag Conversion Tracking API & Conversions API: New valueType Field

    Starting with the 202411 version, we have added an optional field valueType in request payload for POST /conversions. This allows you to specify whether the conversion value is fixed from the conversion rule config (FIXED) or dynamic from the conversion events streaming (DYNAMIC) to ensure accurate reporting and inform performance optimization.

  • Events API: Updated Schema

    Starting with the 202411 version, we've made significant improvements to the Events schema to enhance and streamline the developer experience. Please ensure to use the updated schema to prevent any issues with event lead syncing.

  • Matched Audiences API: Updated endpoint for DMP Segment List Uploads

    Starting with the 202411 version, the CSV List File Upload endpoint used for audience creation has migrated from POST /media/upload to POST /dmpSegments?action=generateUploadUrl endpoint. This is now a two-step process to first generate an upload URL and then upload a CSV file on the generated URL returned in the value field in the response body of POST /dmpSegments?action=generateUploadUrl. To avoid service interruption, partners using older versions of the DMP Segment List Uploads API should migrate to version 202411. More information can be found here.

  • Media Planning API: Save and Retrieve Media Plans

    Starting with the 202411 version, Media Planning API will support saving and retrieving media plans via a new endpoint /mediaPlans. Use this endpoint to create and fetch media plans within an ad account. More details can be found here.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched today.

  • 202306 - Dec 16, 2024
  • 202307 - Dec 16, 2024
  • 202311 - Nov 15, 2024
  • 202312 - Dec 16, 2024
  • 202401 - Jan 15, 2025

Reminders

  • Sponsored Messaging in the European Union (EU)

    Starting October 2024, we enabled EU targeting for Sponsored Messaging campaigns including Message Ads & Conversation Ads, helping partners reach the target audience for their customer campaigns more effectively in the EU. Only EU members who agreed to receive Sponsored Messaging ads in their LinkedIn inbox, will be eligible to receive this ad type. Campaign setup, delivery, and reporting will function the same as all other Sponsored Messaging campaigns, now with the option to target within the EU. Learn more.

    While serving to eligible EU members is enabled automatically by LinkedIn, please ensure to update any platform validations or tooltips and external articles on your end to reflect this change.

    We encourage you to plan for Sponsored Messaging EU targeting with a test-and-learn approach. Because EU members can choose/update how they’d like to receive ads in their inbox at any time, you may find differences in audience size when using Sponsored Messaging ads compared to other formats.

October 2024 - Version 202410

Product & Platform Announcements

  • Upcoming changes to Sponsored Messaging in the European Union (EU)

    Starting mid-October 2024, we will enable EU targeting for Sponsored Messaging campaigns including Message Ads & Conversation Ads, helping partners reach the target audience for their customer campaigns more effectively in the EU. Only EU members who agreed to receive Sponsored Messaging ads in their LinkedIn inbox, will be eligible to receive this ad type. Campaign setup, delivery, and reporting will function the same as all other Sponsored Messaging campaigns, now with the option to target within the EU. Read more.

    While serving to eligible EU members is enabled automatically by LinkedIn, please ensure to update any platform validations or tooltips and external articles on your end to reflect this change.

    We encourage you to plan for Sponsored Messaging EU targeting with a test-and-learn approach. Because EU members can choose/update how they’d like to receive ads in their inbox at any time, you may find differences in audience size when using Sponsored Messaging ads compared to other formats.

  • Creatives API : Creative Naming Support

    Starting with the 202410 version, you can add creative names to your ads using the new name field in the Creatives API. This field is supported across all creative formats. We recommend adopting this approach as we plan to deprecate the legacy options like InMailContents API or the AdDirectSponsoredContents API in the near future.

  • Ad Analytics API: Event Stage Reporting

    In order to enable more granular reporting for Event Ads, the Analytics and Statistics finders now support EVENT_STAGE as a new ad analytics pivot to get analytics data for Event Ads based on the Event stage.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched today.

  • 202306 - Dec 16, 2024
  • 202307 - Dec 16, 2024
  • 202308 - Aug 16, 2024
  • 202309 - Sep 16, 2024
  • 202310 - Oct 15, 2024
  • 202311 - Nov 15, 2024
  • 202312 - Dec 16, 2024

Reminders

  • Associate and Verify your App: LinkedIn Company Page

    Please ensure that your developer app is associated with a LinkedIn Company Page to have access to the necessary features and functionality of LinkedIn Marketing API products. The organization that owns the Page you select will function as the publisher of the app. If you don’t have a Page, you have the option to create a Page. As a developer, you must send an app verification request to your organization’s Page super admin, who is responsible for approving or denying the request to associate an app with a LinkedIn Page. Read more.

  • AdAccounts, Campaign Groups, Campaigns, Creative API: Adopt Cursor-based Pagination

    Starting with the January 2024 version (202401) we moved from index-based to cursor-based pagination for better scalability of our platform. To properly paginate you will need to use the pageSize and pageToken query parameters.

September 2024 - Version 202409

Product & Platform Announcements

  • Connected TV (CTV) Campaigns: Brand Safety Capabilities

    Last month, we shared that our partners can now use the new boolean field connectedTelevisionOnly in Campaign API and Ad Supply Forecasts API to create and run Connected TV (CTV) video ad campaigns. LinkedIn Connected TV (CTV) ads help your customers reach their audience on a large-screen experience, using first-party data from our community of one billion professionals.

    Starting with the 202409 version, we are extending the brand safety capabilities for CTV via Publisher Lists. We have introduced a new field publisherListType in the request body schema for POST /globalPublisherList to specify CONNECTED_TELEVISION as a separate category from WEB_AND_APP for the type of publisher list to be downloaded. This enables your customers to download the list of Connected TV apps directly in your UI and access information such as Bundle ID, Publisher Name, Platform URL (when available), and IAB Categories.

    Please note, this new capability is available in addition to the following features for LAN that are available for CTV by default. Read more about the definitions and different use cases of these lists here.

    • Creating and uploading a blocklist or allowlist
    • Applying a blocklist or allowlist
    • Applying IAB categories

  • Media Planning API: Forecast CTV Campaign Delivery

    Partners now have access to a new capability in LinkedIn’s Media Planning API to forecast CTV-only campaign delivery. You can add an optional ctvOnly field in the API request to forecast CTV-only campaigns in your media plans.

  • Conversions API: Auto-campaign Association:

    A new field autoAssociateCampaigns has been added to the request query parameters for POST /conversions. This field enables automatic association of all ACTIVE, PAUSED, and DRAFT campaigns with a conversion rule, ensuring only these associated campaigns are considered for reporting and optimization.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched today.

  • 202306 - Dec 16, 2024
  • 202307 - Dec 16, 2024
  • 202308 - Aug 16, 2024
  • 202309 - Sep 16, 2024
  • 202310 - Oct 15, 2024
  • 202311 - Nov 15, 2024

Reminders

  • Offline Conversions API Sunset:
    Last October, we launched the Conversions API, allowing our partners and customers to seamlessly connect both online and offline conversions directly to LinkedIn, replacing the legacy Offline Conversions API. If you are still integrated with the legacy Offline Conversions API, please migrate to the new Conversions API before October 15, 2024.

  • AdCampaignRecommendation API Sunset:
    The AdCampaignRecommendation API endpoint was deprecated in July 2023 and has been sunset with no alternative endpoint. Please note any future calls to this API will return an error.

August 2024 - Version 202408

Product & Platform Announcements

  • Campaign API and Ad Supply Forecasts API: Connected TV (CTV) Only Campaigns
    We are excited to share that starting with the 202408 version, we have introduced a new boolean field connectedTelevisionOnly in the Campaign API and Ad Supply Forecasts. This new field enables the creation and delivery of Connected TV (CTV) video ad campaigns. LinkedIn Connected TV (CTV) ads help your customers reach their audience on a large-screen experience using first-party data from our community of one billion professionals. CTV campaign metrics are identical to existing video campaign metrics.

    Please note the requirements below and check out our recommendations to make the most out of LinkedIn CTV campaigns here.

    • Ad Format: Video only
    • LinkedIn Placement: LAN (LinkedIn Audience Network)
    • Campaign Objective: Brand Awareness
    • Geo Eligibility: US & Canada
    • Language: English only

  • Campaign API: Frequency Cap Customization
    You can now use a new field optimizationPreference in the Campaign API to set a maximum campaign-level frequency to better manage reach and frequency outcomes. Frequency is defined as the number of times an ad is served to a LinkedIn member over a specific time period. Research has shown that frequency is a key factor in improving brand awareness from advertising campaigns and positively influences ad recall and purchase intent.

    With this new frequency control, you can set a maximum frequency value between 3 to 30 within a 7-day window. This capability is available for CTV campaigns with the brand awareness objective and is accessible via a limited beta for LinkedIn Feed and LAN (LinkedIn Audience Network) campaigns.

  • Conversions API: Deprecating MQL and SQL Conversion Types
    Starting with the 202408 version, we will no longer support MARKETING_QUALIFIED_LEAD and SALES_QUALIFIED_LEAD conversion types when creating a new conversion rule. We recommend using QUALIFIED_LEAD as the conversion type, which has been available since version 202405.

Breaking Changes

The monthly API versions listed below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched(202308) today. For more information on the latest version, see here.

  • 202306 - Dec 16, 2024
  • 202307 - Dec 16, 2024
  • 202308 - Aug 16, 2024
  • 202309 - Sep 16, 2024
  • 202310 - Oct 15, 2024
  • 202311 - Nov 15, 2024

Reminders

  • AdAnalytics API: Reporting Changes to In-Feed Video & Sponsored Messaging
    Starting in July, we enhanced our measurement methodology for Video and Sponsored Messaging campaigns on LinkedIn.com and the LinkedIn mobile app to align more closely with industry standards. As a result, you may observe changes in your overall campaign reports.

  • Video Campaigns Video ads that serve on LinkedIn.com and in the LinkedIn mobile app now report impressions and clicks only when they start to play. This may lead to a decrease in Video ad impressions, clicks, and CTRs reported for your customer campaigns, and CPMs, CPCs, and Video View Rates may increase. These changes apply to videos that run on LinkedIn feed only; campaigns utilizing LAN/CTV are not impacted.

  • Sponsored Messaging Impressions, clicks, and related metrics (such as CPM and CPC) from Sponsored Messaging campaigns are no longer reported. However, historical data from your customer campaigns delivered before late July is not impacted. You can continue to review sends and opens metrics under the “sends” and “opens” columns, respectively. We recommend that you utilize sends and opens metrics moving forward versus the historical data for impressions, clicks, and derived metrics.

July 2024 - Version 202407

Product & Platform Announcements

  • AdAnalytics API: Reporting changes to In-Feed Video & Sponsored Messaging
    At LinkedIn, we are committed to delivering measurement solutions that meet or exceed industry standards. We are pleased to share that we have improved our measurement methodology for Video and Sponsored Messaging campaigns that serve on LinkedIn.com and in the LinkedIn mobile app to better align with the industry standards. Due to these changes you may see a change in your holistic campaign reports.

  • Video Campaigns
    Beginning July 11, Video ads that serve on LinkedIn.com and in the LinkedIn mobile app will begin reporting impressions and clicks only when they begin to play. This may result in a decrease of Video ad impressions, clicks, and CTRs reported for your customer campaigns, and CPMs, CPCs and Video View Rates may increase. These changes apply to videos that run on LinkedIn feed only, campaigns utilizing LAN/CTV will not be impacted.

  • Sponsored Messaging
    Starting July 30, impressions, clicks, and related metrics (such as CPM and CPC) for Sponsored Messaging campaigns will no longer be reported. Historical data from campaigns prior to late July 2024 will remain unaffected. You can still access sends and opens metrics under the "sends" and "opens" columns, respectively. We recommend using sends and opens metrics for future analysis instead of relying on historical data for impressions, clicks, and derived metrics.

  • AdAnalytics API: New metrics available for Sponsored Newsletter Articles
    We are introducing two new metrics to the API: subscriptionClicks and viralSubscriptionClicks. The subscriptionClicks metric measures the number of members whose first click on the ad in the feed is the Subscribe button. Any clicks on +Subscribe on subsequent pages, for example, the newsletter article page or the newsletter landing page, aren’t counted as part of this metric. The viralSubscriptionClicks metric measures the number of members whose first click on the post is the Subscribe button that resulted from other members sharing a sponsored newsletter article with their network.

  • Matched Audiences API and Conversions API: Email hashing guideline
    To ensure the best audience match rates the following guidelines must be followed for email hashing:

    • Convert all the email addresses to lowercase before hashing
    • Remove any whitespace in the email address and then generate appropriate hash

  • Leadgen Forms: Ability to apply custom Images
    We have introduced an enhancement to Leadgen Forms that allows advertisers to personalize their Leadgen Form backgrounds with custom images (for sponsored content only), instead of the form automatically defaulting to the ad image. However, please note that at the time of the initial rollout, partners or advertisers will not be able to edit custom images via API. If you would like to explore or leverage this new feature, we recommend utilizing LinkedIn Campaign Manager to create and edit your Leadgen Forms and offer a more tailored experience for your target audience.

  • AdCampaignGroups API: Objective Type for Campaign Group
    Campaign groups may now be created with objective type. If created with an objective type, then all campaigns in the group will share the same objective type. This field is optional and immutable once created.

  • Engagement Retargeting API: New engagement source types
    We are introducing the ability to build retargeting audiences based on their engagement with the Document and Conversation ad formats. Once an engagement rule is created, these audiences will refresh automatically based on the trigger and time frame selected. Advertisers can use audience retargeting to stay top of mind and move their target audiences through the funnel.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched today. For more information on the latest version, see here.

  • 202308 - Aug 16, 2024
  • 202309 - Sep 16, 2024
  • 202310 - Oct 15, 2024

Reminders

  • AdAnalytics API: Reminder to switch to approximateMemberReach field
    As communicated in January 2024, approximateUniqueImpressions field has been deprecated and is replaced by the new API field approximateMemberReach. If you are still utilizing the old field, please note that we will be updating the approximateUniqueImpressions measurement methodology to align more closely with approximateMemberReach. When this transition takes place in July, you may notice a change in the approximateUniqueImpressions field and we recommend that you switch to approximateMemberReach as soon as possible.

June 2024 - Version 202406

Product & Platform Announcements

  • DMP Segments API: Field Removal We have removed the accessPolicy field due to low usage. Please note that including this in your create or update requests will fail and the field will no longer be returned in the response from READs (e.g. GET, BATCH_GET, FINDER).

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched today.

  • 202306 - December 16, 2024
  • 202307 - Dec 16, 2024
  • 202308 - Aug 16, 2024
  • 202309 - Sep 16, 2024

Reminders

  • Changes to Member Groups’ Targeting in the EEA and Switzerland As part of our ongoing efforts to provide a safe and trusted platform for members, we disabled Member Groups’ targeting within the European Economic Area (EEA) and Switzerland (CH) as of May 15, 2024. Our global advertising policies do not allow targeting sensitive groups on our platform, and this change further helps protect LinkedIn members, customers, and partners, as well as clarify LinkedIn's compliance with applicable laws in the region.

As a reminder, if you have created campaigns before May 15 that target the EEA or CH using Member Groups’ targeting, they will continue to deliver unless you make any edits. However, you will not be able to use this targeting facet for new campaigns targeting members residing in these regions. If your campaigns only target countries outside the EEA and Switzerland, you are not impacted by this change.

There are multiple ways advertisers can reach their desired audiences on LinkedIn and meet their marketing goals. We encourage you to review our targeting best practices to learn more about optimizing your campaigns.

May 2024 - Version 202405

Product & Platform Announcements

  • Changes to Member Groups’ targeting in the EEA and Switzerland starting May 15, 2024
    As part of our ongoing efforts to provide a safe and trusted platform for members, we have decided to disable Member Groups’ targeting within the European Economic Area (EEA) and Switzerland (CH). We have global advertising policies in place that do not allow targeting sensitive groups on our platform. This decision helps protect LinkedIn members, customers, and partners as well as clarify LinkedIn's compliance with applicable laws in the region.
    Starting May 15, 2024, you may experience changes in the LinkedIn campaign creation process if you run campaigns targeting members residing in the European Economic Area (EEA) and Switzerland (CH). Please review the following to understand how this change impacts your customer campaigns:
Campaigns Description
Campaigns created before May 15 that target the EEA or CH AND Member Groups - Campaigns will continue to deliver and edits can continue to be made.
- On or after May 15: Edits to these campaigns will require the removal of Member Groups or EEA & CH targeting to be able to save and activate.
Campaigns created on or after May 15 that target the EEA or CH Member Groups’ targeting will no longer be available.

If campaigns only target countries outside the EEA and Switzerland, these changes do not apply. There are multiple ways advertisers can reach their desired audiences on LinkedIn and meet their marketing goals. We encourage you to review our targeting best practices to learn more.

  • Conversions API: New Conversion Type
    Partners can access a new conversion type that has been added for creating conversion rules: QUALIFIED_LEAD with LinkedIn’s Conversions API.

  • Ad Analytics API

    • Reporting for Connected TV Ads
      We have introduced CONNECTED_TV as an additional value supported on the IMPRESSION_DEVICE_TYPE pivot for both the analytics finder and the statistics finder. When this pivot is used, ad performance metrics will be grouped by the device type the ad made an impression on, such as DESKTOP_WEB, MOBILE_WEB, MOBILE_APP, CONNECTED_TV, and UNDETECTED. Learn more about the reporting by impression device type in Campaign Manager here.

    • Reporting for New Qualified Leads Conversion Rule
      We have introduced new metrics qualifiedLeads and costPerQualifiedLead to the statistics finder. The qualifiedLeads metric will show the total count of qualified leads attributed to the entities in the given time range and costPerQualifiedLead will return the number of qualified leads divided by spend. Partners can now submit this new conversion rule, QUALIFIED_LEAD, through the Conversions API as noted above.

  • Media Planning API: Forecast Lead Generation
    Partners now have access to a new capability in LinkedIn’s Media Planning API to forecast lead generation. With a deeper insight into forecasted leads you can now plan and launch more effective campaigns on LinkedIn. With this release version, we now also support negative targeting(exclude section) in our Media Planning targeting input. Get started today.

  • Creatives API & Legacy Creatives API: Updates to Ad Creative Rejection Reasons
    The description for a few existing rejection reasons have been updated along with a new rejection reason symbol, which could be returned as rejection reasons from the API: MISSING_UK_FCA_FINANCIAL.

  • Campaign API: Updates to the Brand Safety Feature
    The publisher blocklists and allowlists under the Brand Safety feature have been updated to include a validation logic to prevent incorrect application of blocklists and allowlists during the campaign creation or update process. For example, allowlists can only be applied as an allowlist. Read more about the definitions and different use cases of these lists here.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202306 - December 16, 2024
  • 202307 - December 16, 2024
  • 202308 - Aug 16, 2024

Reminders

AdAccounts, Campaign Groups, Campaigns, Creative API: Adopt cursor-based pagination by May 31, 2024 to improve scalability of our platform
We are moving from index-based to cursor-based pagination. You will need to use pageToken returned in the previous call to get to the next set of results, instead of accessing a random page using start and count.

  • Instead of start & count, pageToken and pageSize will be used for pagination.
  • PageSize will be used to specify the number of entities to be returned.
  • NextPageToken is an opaque string that will be returned in the metadata and it represents the last entity in the response. It can be used to fetch the next set of results by passing it in “pageToken” in the next api call.
  • Sorting will only be supported by ID. SortOrder will define the sorting order (Ascending/ Descending) of the results.
  • Totals will no longer be supported as a query parameter.

April 2024 - Version 202404

Product & Platform Announcements

Posts API: Capability to Fetch Celebration Posts
API partners can now fetch celebration content type posts by using the latest 202404 version. Learn more here.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate to the latest API version launched today.

  • 202305 - May 15, 2024
  • 202306 - December 16, 2024
  • 202307 - December 16, 2024

Reminders

AdAccounts, Campaign Groups, Campaigns, Creative API: Adopt cursor-based pagination by May 31, 2024 to improve scalability of our platform
We are moving from index-based to cursor-based pagination. You will need to use pageToken returned in the previous call to get to the next set of results, instead of accessing a random page using start and count.

  • Instead of start & count, pageToken and pageSize will be used for pagination.
  • PageSize will be used to specify the number of entities to be returned.
  • NextPageToken is an opaque string that will be returned in the metadata and it represents the last entity in the response. It can be used to fetch the next set of results by passing it in “pageToken” in the next api call.
  • Sorting will only be supported by ID. SortOrder will define the sorting order (Ascending/ Descending) of the results.
  • Totals will no longer be supported as a query parameter.

Migrate to the new Lead Sync API by December 16, 2024: Collect leads from ads, events, and other organic sources via a single API
The new Lead Sync API simplifies and enhances LinkedIn lead syncing capabilities by consolidating the legacy Ads Lead Sync and Events Lead Sync APIs into a single API. It provides the ability to collect leads from additional organic sources and offers customized form field mapping to ensure lead information gets mapped to the right system fields. If you’re integrated with any of the legacy APIs, you will automatically have access to the new API and will need to migrate to the new API using the migration guide before December 16, 2024 when versions 202306 and 202307 will sunset. See our YouTube video covering the high level requirements of the migration.

March 2024 - Version 202403

Product & Platform Announcements

Media Planning API: Improve Campaign Results by Optimizing Audiences and Budgets
LinkedIn’s Media Planning API enables marketers to have a better understanding of investment delivery against valuable audiences and objectives. With a deeper insight into forecasted reach, impressions, and frequency by audience, along with the ability to compare reach & frequency across multiple channels and partners ​you can now plan and launch more successful campaigns on LinkedIn.​ Get started today.

Campaign Recommendations: Endpoints to be Deprecated
The adCampaignRecommendations and adCampaignInsights APIs let advertisers determine if active LinkedIn campaigns are achieving the desired reach and impact. Starting 202403 these API endpoints will be deprecated but you can continue to use 202402 or earlier versions until it is sunset in a year.

LeadGenNotificationSubscription API: New Associated Entity Type
You can now access a new field LeadGenNotificationAssociatedEntity to support LeadGenNotificationSubscription creation by campaign. This would allow advertisers to receive lead notifications at a campaign level.

Breaking Changes

The monthly API versions below will be sunset and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202304 - April 15, 2024
  • 202305 - May 15, 2024
  • 202306 - December 16, 2024

Reminders

LinkedIn in Europe: Changes for the Digital Markets Act
Starting in February, LinkedIn made changes for members in the EEA and Switzerland to comply with new requirements imposed on us by the Digital Markets Act (DMA). We are providing the ability for members in these regions to choose whether to connect their core LinkedIn experience with LinkedIn marketing products and services in order to better tailor their experiences to their professional interests. As this new experience ramps to members, your customers may notice changes in LinkedIn campaign performance. For example, if you use LinkedIn Reporting API, they may notice fewer conversions reported based on how we apply modeling to report conversions from members residing in the EEA and Switzerland. Or if they use certain targeting facets such as inferred targeting or retargeting from company Page visits and events, they may observe decreased audience sizes that could result in changes to ROI.

The changes you observe are a reflection of members in the EEA and Switzerland who have either not yet engaged with the new consent experience or have chosen not to connect their Marketing Solutions feature to their core LinkedIn experience. The impact is highly variable based on DMA consent rates, targeting usage & behaviors (e.g. AND vs OR, hyper targeting), budgets, and more. Read more about our approach to DMA here and how this may change our marketing solutions products and services here.

AdAccounts, Campaign Groups, Campaigns, Creative API: Adopt cursor-based pagination by May 31, 2024 to improve scalability of our platform
We are moving from index-based to cursor-based pagination. You will need to use pageToken returned in the previous call to get to the next set of results, instead of accessing a random page using start and count.

  • Instead of start & count, pageToken and pageSize will be used for pagination.
  • PageSize will be used to specify the number of entities to be returned.
  • NextPageToken is an opaque string that will be returned in the metadata and it represents the last entity in the response. It can be used to fetch the next set of results by passing it in “pageToken” in the next api call.
  • Sorting will only be supported by ID. SortOrder will define the sorting order (Ascending/ Descending) of the results.
  • Totals will no longer be supported as a query parameter.

February 2024 - Version 202402

Product & Platform Announcements

Conversions API (CAPI): Attribute LinkedIn campaigns to business outcomes Help your customers navigate measurement uncertainty and impending cookie deprecation with a solution designed to improve full funnel measurement and unlock optimization by connecting online and offline conversions to LinkedIn and using those insights to power campaign optimization. Explore CAPI benefits.

New Lead Sync API: Collect more leads The Lead Sync API is easier to access than ever before and includes both organic and paid leads in a single API to help your customers collect leads from more LinkedIn sources. Check out what you can do with the new API.

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202303 - March 15, 2024
  • 202304 - April 15, 2024
  • 202305 - May 15, 2024

Reminders

AdAccounts, Campaign Groups, Campaigns, Creative API: Adopt cursor-based pagination by May 31, 2024 to improve scalability of our platform We are moving from index-based to cursor-based pagination. You will need to use pageToken returned in the previous call to get to the next set of results, instead of accessing a random page using start and count.

  • Instead of start & count, pageToken and pageSize will be used for pagination.
  • PageSize will be used to specify the number of entities to be returned.
  • NextPageToken is an opaque string which will be returned in the metadata and it represents the last entity in the response. It can be used to fetch the next set of results by passing it in “pageToken” in the next api call.
  • Sorting will only be supported by id. SortOrder will define the sorting order (Ascending/ Descending) of the results.
  • Totals will no longer be supported as a query parameter.

Lookalike Audiences API: Sunset on February 29 On February 29, 2024, we will sunset the ability to create new Lookalike Audiences in both Campaign Manager and via API, as we evolve our audience solutions and invest in new solutions to help scale marketers’ first- and third-party data. Existing Lookalike Audiences can still be used in campaigns but will not be updated when the seed audience updates. Additionally, the following changes will impact existing audiences:

  • If the LaL audience is not used in a draft or active campaign for 30 days, it will be ARCHIVED.
  • If an LaL audience is ARCHIVED but added to a draft or active campaign, it will go back to BUILDING but it will not be regenerated. It will reflect the original state of the LaL as it was prior to February 29.
  • If an ARCHIVED LaL audience is EXPIRED, it is purged and can never be used again.

Migrate to the new Lead Sync API: Collect leads from ads, events, and other organic sources via a single API The Ads Lead Sync and Events Lead Sync APIs will be deprecated and replaced with the new Lead Sync API. If you’re integrated with any of the legacy APIs, you will automatically have access to the new API and will need to migrate to the new API using the migration guide before July 2024 when version 202307 sunsets. See our YouTube video covering the high level requirements of the migration.

January 2024 - Version 202401

Product & Platform Announcements

AdAccounts, Campaign Groups, Campaigns, Creative API: Adopt cursor-based pagination by May 31, 2024
We are moving from index-based to cursor-based pagination. You must use pageToken returned in the previous call to get to the next set of results, instead of accessing a random page using start and count.

  • Instead of start & count, pageToken and pageSize will be used for pagination.
  • PageSize will be used to specify the number of entities to be returned.
  • NextPageToken is an opaque string which will be returned in the metadata and it represents the last entity in the response. It can be used to fetch the next set of results by passing it in “pageToken” in the next API call.
  • Sorting will only be supported by ID. SortOrder will define the sorting order (Ascending/ Descending) of the results.
  • Totals will no longer be supported as a query parameter.
  • We will soon sunset index-based pagination from all API versions prior to 2024, so you need to migrate to any 2024 API version before then.

Ad Preview API: Migrate to Latest Version
On February 29, 2024 we will sunset ads preview from all API versions before 202311. To continue to support ads preview, make sure to migrate to the latest version.

Ad Analytics API: Upcoming Reach Metric Changes
Starting in January 2024, approximateUniqueImpressions will be deprecated and the new API field will be called approximateMemberReach. As we move to a new metric measurement methodology, you may see some deviation between upcoming approximateMemberReach and old approximateUniqueImpressions for the same creative/campaign/campaign group with the same date range. Additionally, we will be restricting the availability of approximateMemberReach metrics in the following ways:

  • approximateMemberReach will only be supported with pivot(s): CREATIVE, CAMPAIGN, CAMPAIGN_GROUP, CAMPAIGN_TYPE, OBJECTIVE_TYPE and/or SERVING_LOCATION. All requests which supply additional pivot(s) will not include approximateMemberReach in the response.
  • approximateMemberReach can be requested for date ranges with a maximum range of 92 days.
  • approximateMemberReach will not be available for the current UTC day. The expected delay for current UTC day will be 24-48 hours. Requests which include today in the date range will only return reach for days where data exists.

Page Statistics API: Improving location standardization for professional demographic analytics
We will replace the Page professional demographic breakdown by legacy geo region and country with the Bing Geo market area and country. This will provide more accurate and comprehensive geographical data. As a result, pageStatisticsByRegion and pageStatisticsByCountry will be replaced with pageStatisticsByGeo and pageStatisticsByGeoCountry.

Creatives API & Legacy Creatives API: Updates to Ad Creative Rejection Reasons

  1. We have added a new rejection reason symbol, which could be returned as rejection reasons from the API: MISINFORMATION
  2. We have updated the description for below existing rejection reasons
    • PRESCRIPTION_DRUGS
    • OVER_THE_COUNTER_DRUGS
    • MEDICAL_DEVICES_AND_TREATMENTS
    • ILLICIT_OR_RECREATIONAL_DRUGS_AND_RELATED_PRODUCTS
    • LEGITSCRIPT_APPROVAL_MISSING
    • PHARMACY_AND_TELEHEALTH

Lookalike Audiences API: Sunset on February 29
On February 29, 2024, we will sunset the ability to create new Lookalike Audiences in both Campaign Manager and via API, as we evolve our audience solutions and invest in new solutions to help scale marketers’ first- and third-party data. Existing Lookalike Audiences can still be used in campaigns but will not be updated when the seed audience updates. Additionally, the following changes will impact existing audiences:

  • If the LaL audience is not used in a draft or active campaign for 30 days, it will be ARCHIVED.
  • If an LaL audience is ARCHIVED but added to a draft or active campaign, it will go back to BUILDING but it will not be regenerated. It will reflect the original state of the LaL as it was prior to February 29.
  • If an ARCHIVED LaL audience is EXPIRED, it is purged and can not be reused.

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched.

  • 202302 - February 15, 2024
  • 202303 - March 15, 2024
  • 202304 - April 15, 2024

Reminders

Migrate to the new Lead Sync API: Collect leads from ads, events, and other organic sources via a single API
The Ads Lead Sync and Events Lead Sync APIs will be deprecated and replaced with the new Lead Sync API. If you’re integrated with any of the legacy APIs, you will automatically have access to the new API and will need to migrate to the new API using the migration guide before July 2024 when version 202307 sunsets. See our YouTube video covering the high-level requirements of the migration.

November 2023 - Version 202311

Product & Platform Announcements

Ad Preview API: Ad account URN required to generate creative preview. Starting with the 202311 version, you need to pass the Creative URN and Ad account URN to generate a preview of the creative in your platform.

Offline Conversion API: Sunsetting Offline Conversions. In October 2023, we launched the Conversions API, which connects both online and offline conversions directly to LinkedIn, and replaces the Offline Conversions API. If you have integrated with Offline Conversions API, migrate to the new Conversions API before October 2024.

Brand Lift Testing API: New question type is now available. You can now use a new brand lift metric ‘Top-of-mind Awareness’, for example "What [brand / product / service / employer] comes to mind when you think of [user input]?", in Brand Lift Testing to prove how your brand efforts are moving the needle to keep your brand top of mind.

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202212 - December 15, 2023
  • 202301 - January 15, 2024
  • 202302 - February 15, 2024

October 2023 - Version 202310

Documentation Changes

New Marketing APIs Landing Page: A brand new landing page has been added to the Marketing APIs section that provides a detailed view of the API products offered with a fresh look and feel.

Product & Platform Announcements

Conversions API: Build a server-to-server integration to strengthen both performance and privacy.
Leverage LinkedIn's Conversions API to build a solution that connects marketing data, like online and offline conversions, directly to LinkedIn. Conversions API enables full-funnel measurement and powers campaign optimization while providing a secure, reliable data connection. Get started by reviewing the prerequisites and application process here.

Creatives API: New call to action types
We've expanded the call to action types for a lead generation form creative to include: JOIN, SIGNUP, REQUEST DEMO.

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202211 - November 15, 2023
  • 202212 - December 15, 2023
  • 202301 - January 15, 2024

September 2023 - Version 202309

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version (202309) launched today.

  • 202210 to be deprecated on October 16, 2023
  • 202211 to be deprecated on November 15, 2023
  • 202212 to be deprecated on December 15, 2023.

See Versioning Guide for more.

August 2023 - Version 202308

Product & Platform Announcements

  • Conversation Ads API: Add subject to a Conversation Ad
    You can now add a subject to a Conversion Ad which will appear as the first line in the member’s inbox. Previously it was auto populated with the first conversation message.

  • mediaArtifactPublicUrls API: API is deprecated
    Additional fields have been added to Assets API to support the mediaArtifactPublicUrls use case.

  • Creatives API & Legacy Creatives API: Updates to Ad Creative Rejection Reasons

    • We have added six new rejection reason symbols, which could be returned as rejection reasons from the API:

      • ILLICIT_OR_RECREATIONAL_DRUGS_AND_RELATED_PRODUCTS
      • LEGITSCRIPT_APPROVAL_MISSING
      • MEDICAL_DEVICES_AND_TREATMENTS
      • OVER_THE_COUNTER_DRUGS
      • PHARMACY_AND_TELEHEALTH
      • PRESCRIPTION_DRUGS

    • We have updated the description of the HEALTH_MATTERS symbol explaining the current policy for rejecting Ads with this reason.

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202209 - September 15, 2023
  • 202210 - October 16, 2023
  • 202211 - November 15, 2023

Starting with the 202307 version, API decoration will not be supported for any API. We’ve created this video to assist you with this change.

Reminders

Message Ads to be sunset on August 31, 2023 On August 31, 2023, we will be sunsetting Message Ads and recommend switching to Conversation Ads. The ability to create a Message Ad will be sunset across all API versions. Delivery for existing Message Ads campaigns will be reduced, and we recommend notifying your clients to stop creating new Message Ads.

July 2023 - Version 202307

Product & Platform Announcements

  • Post API: More images allowed in multi-image posts.

We have increased the max number of images you can include in a multi-image post from 9 to 20. To know more, go to Post API page.

  • Comments API: Update to $URN field and digitalmediaAsset field

We have replaced the following: - $URN field with the id field. - digitalmediaAsset field with the image field. To know more, go to Comments API page.

  • Reactions API: Updates to MAYBE reaction and $URN field.

The following updates are made to the Reactions API: - The MAYBE reaction is no longer supported. Any write with the MAYBE reaction will be rejected with a 400 error. - The $URN field is replaced with the id field.

  • New Lead Sync API: Collect leads from ads, events, and other future marketing cases via a single API
    The Ads Lead Sync and Events Lead Sync APIs will be deprecated and replaced with the new Lead Sync API. If you’re integrated with any of the legacy APIs, you will automatically have access to the new API and will need to migrate to the new API using the migration guide before July 2024 when version 202307 sunsets. If you’re interested in accessing the new API for the first time, learn about the qualifications, and application steps here.

  • Creatives API and the Legacy Creatives API: Updates to Ad Creative Rejection Reasons

We have added six new rejection reason symbols, which could be returned as rejection reasons from the API: - ILLICIT_OR_RECREATIONAL_DRUGS_AND_RELATED_PRODUCTS - LEGITSCRIPT_APPROVAL_MISSING - MEDICAL_DEVICES_AND_TREATMENTS - OVER_THE_COUNTER_DRUGS - PHARMACY_AND_TELEHEALTH - PRESCRIPTION_DRUGS

We have updated the description of the HEALTH_MATTERS symbol explaining the current policy for rejecting Ads with this reason.

The timeFrame field will accept timeSpan instead of com.linkedin.common.timeSpan.

Breaking Changes

The monthly API versions below will be deprecated and removed from the platform on the dates listed. To avoid disruptions to your platform, please migrate the latest API version launched today.

  • 202207 - July 25, 2023
  • 202208 - August 15, 2023
  • 202209 - September 15, 2023

Starting with the 202307 version, API decoration will not be supported for any API. We’ve created this video to assist you with this change.

Reminders

  • Message Ads to be sunset on August 31, 2023
    On August 31, 2023, we will be sunsetting Message Ads and recommend switching to Conversation Ads. The ability to create a Message Ad will be sunset across all API versions. Delivery for existing Message Ads campaigns will be reduced, and we recommend notifying your clients to stop creating new Message Ads.

June 2023 - Version 202306

Migrations

Critical API migrations must be completed by June 30, 2023.

  • API Versioning and new Content APIs: We will sunset unversioned APIs and legacy Content APIs (Shares API, UGCAPI) on June 30, 2023. Migrate to versioned APIs and new Content APIs to avoid any disruptions.

  • New Community Management API*: We introduced a new Community Management API in January 2023 to offer more functionality to enable your customers to grow their professional communities. Apply and migrate to the new API to keep your community management integration active. Legacy community management permissions will sunset and be removed on June 30, 2023

Product & Platform Announcements

  • Audience Insights API: Make it easier to plan and understand professional audiences We are introducing the Audience Insights API, which provides aggregated insights into the professional demographic and firmographic details, and interests of a target audience. These insights help you understand more about “who” the audience is and can be leveraged to discover new audiences, plan & optimize your strategy, and build new audiences to seamlessly start your campaign. This is a private API and requires additional approval to access. Learn more on how to apply here.

  • Ad Analytics API: B2B query templates make it easy to get relevant reporting metrics
    Templated, B2B-focused queries are now available via Postman collection to enable quick access to B2B-relevant metrics that can be used to build insightful reports and inform optimization. We are starting with 3 focused bundles - Performance Overview, ABM Performance Overview, Conversions Deep Dive - and will continue to evolve our templates library, so please take advantage and share feedback here for future updates.

  • Response format change for thirdPartyTrackingTags API
    Starting with version 202306, we're making changes to the response format of the thirdPartyTrackingTags API. The GET and FINDER APIs will now return changeTimeStamps instead of changeAuditStamps in their responses. The new changeTimeStamps will still include the created, lastUpdated, and deleted fields, but they will now directly contain the timestamp value instead of being nested within another object with a time field.

  • Query params changes: Enabling unwrapped query params
    We previously announced that certain query params had to be wrapped - e.g. we required intendedStatuses=(value:List(ARCHIVED,CANCELED)) rather than intendedStatuses=List(ARCHIVED,CANCELED). Based on your feedback and to create a better experience, we’ve decided to revert this decision and enable you to make requests without wrapping the query params. We will support both wrapped and unwrapped query params until the 202305 version. From 202306 onwards only unwrapped query params are allowed. The APIs that are affected by this change are: Ad Analytics API, Creatives API, Posts API, Saved Audience Template API, Videos API.

Breaking Changes

  • 202207 version will be deprecated and removed from the platform on July 17, 2023. Be sure to update your apps to the latest version before then.

  • Message Ads will be sunset and removed across all versions starting August 31, 2023.

  • Starting with the 202305 and 202306 versions, API decoration will not be supported for certain APIs. See the Recent Changes page in documentation for the complete list of impacted APIs. We’ve created this video to assist you with this change.

    From 202305:

    /adPageSets
    /adSegmentSources
    /adSegments
    /dmpSegments/{dmpSegmentId}/companies
    /dmpSegments/{dmpSegmentId}/destinations
    /dmpSegments/{dmpSegmentId}/lookalikes
    /dmpSegments
    /dmpSegments/{dmpSegmentId}/users
    /adAccounts/{id}/creatives
    /posts
    /adInMailContents
    /inMailContents
    /conversationAds
    /conversationAds/{conversationId}/sponsoredMessageContents
    /adAccounts/{id}/adCampaignGroups/
    /adAccounts/{id}/adCampaigns
    /adLiftTests
    /adLiftTests/{id}/adLiftTestSurveys
    /adSupplyForecasts
    /networkSizes
    /adPublisherRestrictions
    /videoAnalytics
    /brandPageStatistics
    /organizationAcls
    /organizationalEntityFollowerStatistics
    /organizationalEntityNotifications
    /organizationalEntityShareStatistics
    /organizationPageStatistics
    /organizationShareAuthorizations
    /adInMailMemberSenderPermissions
    /adBudgetPricing
    /documents

    From 202306:

    /shortlink
    /conversions
    /thirdPartyTrackingTags
    /socialActions/{target}/likes
    /socialActions
    /socialActions/{target}/comments
    /socialMetadata
    /assets
    /people
    /me
    /dmpEngagementSourceTypes
    /dmpEngagementSourceTypes/{engagementSourceType}/dmpEngagementTriggers

Reminders

  • Access and refresh token requests after June 30, 2023
    Make access token and refresh token requests using the POST method to /accessToken endpoint with the request header “Content-Type”: “x-www-form-urlencoded” and all required parameters in the request body. Using the GET /accessToken endpoint after June 30, 2023 will result in a 400 error.

  • Message Ads to be sunset on August 31, 2023
    On August 31, 2023, we will be sunsetting Message Ads and recommend switching to Conversation Ads. The ability to create a Message Ad will be sunset across all API versions. Delivery for new Message Ads campaigns will be reduced, and we recommend notifying your clients to stop creating new Message Ads.

May 2023 - Version 202305

Migrations & Breaking Changes

  • Critical API migrations must be completed by June 30, 2023.
    Please review details below for recent API enhancements that may impact your apps.

If you have impacted apps, please make the necessary changes immediately or set aside time/resources to complete updates before June 30th 2023.

  • Migrate June 2022 versioned APIs to the latest version prior to June 15, 2023
    Beginning June 2022, we introduced monthly versioning of our APIs and committed to supporting each monthly version for 12 months. Applications using the 202206 version of any versioned APIs must migrate to the latest version before June 15, when we will release the June 2023 versions of our APIs.

  • Reminder about access and refresh token requests after June 30, 2023
    All access token and refresh token requests should be made using only the POST method to /accessToken endpoint with the request header “Content-Type”: “x-www-form-urlencoded” and all required parameters in the request body. We will start returning 400 errors on the GET /accessToken endpoint after June 30, 2023.

  • Update to adCreativesV2 deco Starting May, all deco calls for creative URN will resolve via the /creatives endpoint instead of the /adCreativesV2 endpoint. Partners who use the adAnalytics endpoint and other endpoints that use deco calls to fetch creatives need to update their calls.

  • Message Ads API We’re sunsetting Message Ads API starting May 22, 2023. New campaign creation will be disabled on June 19, 2023. We strongly encourage switching from the legacy Message Ads API to Conversation Ads API by June 19th to avoid disruption of campaign delivery.

  • Updates to Base URLs Starting with the 202305 version, all API calls to the following endpoints will be modified to include advertiser Account ID in the URL path:

Endpoint Changed Previous Base URL New Base URL
/adCampaignGroups https://api.linkedin.com/rest/adCampaignGroups https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups
/adCampaigns https://api.linkedin.com/rest/adCampaigns https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns
/creatives https://api.linkedin.com/rest/creatives https://api.linkedin.com/rest/adAccounts/{adAccountId}/creatives

What this means:

  • Finder functionality will now be limited to a single account. Currently, we can search for campaign groups, campaigns and creatives across accounts using finders. Adding advertiser account ID to the URL would limit the ability to do this. Any calls from now on need to be made per account.

  • In addition, we will be removing the ability to filter by account predicate from campaign group, campaign and creative finders. As we are already limiting the finder functionality to a single account, it doesn’t make sense to have it as a filter predicate. Similarly, we can no longer sort by Account field since the search results are being limited to an advertiser account.

  • The new URLs will be active from the May version. This means that all APIs using version header 202304 or earlier will need to call the old URLs. And all APIs using version headers 202305 or above will need to call the new API URLs.

  • With the new APIs, applications will always need to pass an advertiser account ID in the URL path.

  • Ad Analytics API

    • Deprecate API Decoration starting with the June 2023 version: Starting with the 202306 version, we will remove API Decoration from the Ad Analytics API. As an alternative, individual requests can be made to access the corresponding entity associated with a URN. More information can be found in URN Resolution. For eligible pivots of the Ad Analytics API, we are adding a note that indicates which type of URN will be returned for each pivot. For example, if the MEMBER_COMPANY pivot is used with an analytics finder, then the response will contain a pivot value in the format urn:li:organization:<organizationId>.
    • Remove support for pivot and pivotValue fields: Starting with the 202305 version, we will no longer support the pivot and pivotValue fields in the returned entities of the Ad Analytics API. Requests with these fields in the field projections will be rejected. We will continue to support pivotValues, which provides more accurate and comprehensive information about the values of the pivots requested.

Product & Platform Announcements

  • Content API: Externalizing Document Ads In September 2022, we rolled out a new ad format, Document Ads, which allows advertisers to share ungated and gated documents, such as case studies, white papers, or research reports, directly in the LinkedIn feed. With Document Ads, target audiences can read or download documents without leaving the feed. Advertisers can choose to share their content freely to build awareness and grow thought leadership or gate their documents with a Lead Gen Form.

  • Document Ads API Prior to today, creating a Document Ad was only available to advertisers through Campaign Manager. The new Document Ads API allows advertisers to now have access to a new format during ad creation on partner platforms. To learn more, see the Document Ads API page.

  • Ad Analytics API: New metrics for Conversation Ads We’re launching a new & improved version of Conversation Ads on May 22nd, with availability increasing over time. Alongside this product change, we will introduce two new reporting metrics for Conversation Ads - headlineImpressions and headlineCTR - to help you measure campaign performance for new & improved Conversation Ads. These new metrics will measure the number of times members are shown the headline of the Conversation Ad and the number of times members clicked on it to start a conversation. To learn more, see this article.

April 2023

Migrations & Breaking Changes

  • Critical API migrations must be completed by June 30, 2023.

Please review details below for recent API enhancements that may impact your apps.

If you have impacted apps, please make the necessary changes immediately or set aside time/resources to complete updates before June 30th 2023.

  • Migrate June 2022 versioned APIs to the latest version prior to June 15, 2023
    Beginning June 2022, we introduced monthly versioning of our APIs and committed to supporting each monthly version for 12 months. Applications using the 202206 version of any versioned APIs must migrate to the latest version before June 15, when we will release the June 2023 versions of our APIs.

  • Reminder about access and refresh token requests after June 30, 2023
    All access token and refresh token requests should be made using only the POST method to /accessToken endpoint with the request header “Content-Type”: “x-www-form-urlencoded” and all required parameters in the request body. We will start returning 400 errors on the GET /accessToken endpoint after June 30, 2023.

  • Ad Segments API: find by account requests without start or count parameters are now paginated according to the standard pagination behavior.

Schema changes

  • Ad Targeting, Ad Targeting Entities API: Starting with the 202304 version, we're changing the format of certain query parameters in the adTargetingFacet finder, the similarEntities finder, the typeahead finder and the urns finder. In the finders, entityType, queryVersion, and fetchType would be records containing the expected values instead of directly accepting values. For example, entityType=SENIORITY would become entityType=(value:SENIORITY).

  • Ad Targeting, Ad Targeting Facets API: Starting with the 202304 version, we're changing the $URN field of type urn in the GET_ALL method to adTargetingFacetUrn of type AdTargetingFacetUrn.

Deco Updates

Product & Platform Announcements

  • Images API & Videos API: Beginning with the 202304 release, we are removing a role check for company URN owners and member URN owners when retrieving an image and/or video. For partners using a combination of /posts and /images or /videos, if /post API viewability checks are satisfied (e.g. you need to own the post as a member or company admin or be a role in AdAccount) you will be able to access images through /images and videos through /video.

  • Ad Analytics API:

    • Introducing IMPRESSION_DEVICE_TYPE pivot: Starting with the 202304 version, we are introducing the IMPRESSION_DEVICE_TYPE pivot for both the statistics finder and the analytics finder. When this pivot is used, the results will be grouped by the device type the ad made an impression on, such as MOBILE_APP and DESKTOP_WEB.
    • Deprecate API Decoration starting from the June 2023 version: Starting with the 202306 version, we are removing API Decoration from the Ad Analytics API. As an alternative, individual requests can be made to access the corresponding entity associated with a URN. More information can be found in LinkedIn Marketing API URN Resolution. For eligible pivots of the Ad Analytics API, we are adding a note that indicates which type of URN will be returned for each pivot. For example, if the MEMBER_COMPANY pivot is used with an analytics finder, then the response will contain a pivot value in the format urn:li:organization: <organizationId>

  • Ad Publisher Restrictions API: Externalizing the type field Starting with the 202304 version, we are introducing a new field type. This field can be used to create allowlist by passing type as ALLOWLIST in create method. This is an optional field having a default value as BLOCKLIST for backward compatibility since in earlier versions we supported only creation of BLOCKLIST from API. For example, “type”: “ALLOWLIST” can be used to create allowlist.

  • New training videos To support our developer community, we've started to produce training videos on topics we think you'll find helpful. Our first two cover:

March 2023

Product & Platform Announcements

  • Ad Analytics API: Introducing validWorkEmailLeads metric and PLACEMENT_NAME pivot Starting with the 202303 version, we are introducing the following:

    • validWorkEmailLeads: This metric represents the count of leads with a valid work email that does not use an established free or personal email domain.
    • PLACEMENT_NAME: This pivot enables grouping of metrics by placement. The pivot values are: LINKEDIN, OFFSITE and OFFSITE_IN_STREAM. Only LAN(Linkedin Audience Network) enabled video campaigns are eligible to deliver on offsite in-stream inventory. When video campaigns deliver on offsite in-stream inventory, you will see the metrics available for "OFFSITE_IN_STREAM" placement.

  • Image API & Videos API: Externalizing the Media Library In October 2022, we rolled out the media library in the Campaign Manager UI. The media library provides one location where advertisers can upload, manage, and select images and videos for single image ads and video ads. We are externalizing the media library for our API partners so that advertisers can use the same media library during ad creation on partner platforms.

    This will allow API partners to perform the following actions:

    • initializeUpload (existing method): This is an existing method for asset upload; the update in the release would be parallel registration under the Media Library

    • findByAssociatedAccount (new method): Return all media library assets under a specific account and asset type

    • partialUpdate (new method): Update an existing media library asset- specifically to rename an asset or to archive it

      We will enable findByIdsAndAssociatedAccount to return specific media library assets based on ID in a future release.

  • Saved Audience Template API: Save Audience Criteria
    We are introducing a new API to enable the following:

    • Save audiences, including targeting attributes and/or existing matched audiences, for easy re-use in campaigns. This is especially valuable for users who build audiences via the Audience Insights and wish to apply those audiences to a campaign.

    • Fetch audiences to access audience insights when used in tandem with the Audience Insights saved via the Campaign Manager UI.

  • Ads A/B Testing API: Test Campaign Performance
    We have launched A/B Testing to help our advertisers optimize their ROI with rigorous testing. A/B Testing measures the performance of two campaigns with equal audiences and budgets to test one variable, such as creative content / ad format, targeting, or placement. The testing tool then selects a winner (if any), or verifies that the performance difference between the variants is insignificant or inconclusive.

Breaking Changes

Starting with the 202303 version, we will change the format of certain query parameters in both the analytics finder and the statistics finder. In both finders, pivot, pivots, timeGranularity, campaignType, and objectiveType would be records containing the expected values instead of directly accepting values. For example, pivot=CAMPAIGN would become pivots=(value:List(CREATIVE,CAMPAIGN)) would become pivots=List((value:CREATIVE),(value:CAMPAIGN)).

Reminders

  • Migrate to the new Community Management API before June 30, 2023
    We’re accelerating our push to release more functionality that enables your customers to know and grow their professional communities — starting with a new Community Management API. Existing community management partners must migrate to the new API by June 30, 2023. Check out this article to learn more about our plans for community management.

  • All access and refresh token requests should only be made using the POST method after June 30, 2023
    This is a reminder that access token and refresh token requests should be made using only the POST method to /accessToken endpoint with the request header Content-Type: x-www-form-urlencoded and all required parameters in the request body. We will start returning 400 errors on the GET /accessToken endpoint after June 30, 2023.

February 2023

Product & Platform Announcements

  • Posts API: Specify the sort order for finder results
    We’re introducing an optional sortBy parameter to the posts author finder to enable you to specify the sort order for finder results. You can sort by either last modified time or created time, in descending order. The default sort order is by last modified time in descending order.

Breaking Changes

  • Ad Account Users API: API decoration deprecation
    In November 2022, we began deprecating API decoration for some APIs. Starting with the 202302 version, we will no longer support decoration on the adAccountUsers API.

Reminders

  • Migrate to versioned APIs and new Content APIs by February 28, 2023
    In June 2022, we introduced API Versioning and new Content APIs to make it easier for you to build with ease and manage API changes with predictability. With the new APIs, we plan to sunset the unversioned APIs and legacy Content APIs ( Shares API, UGC API) on February 28, 2023.
    Migrate to the latest versioned API (February 2023) and the new Content APIs using this migration guide.
    You can learn more about API versioning at LinkedIn and the new Content APIs through these videos: Versioning, Content APIs.

  • Migrate to the new Community Management API before the end of June 2023
    We’re accelerating our push to release more functionality that enables your customers to know and grow their professional communities — starting with a new Community Management API. Existing community management partners must migrate to the new API by June 30, 2023. Check out this article to learn more about our plans for community management.

January 2023

Product & Platform Announcements

  • LinkedIn Marketing Developer Products refreshed with 2 API products LinkedIn Marketing Developer Products now has 2 API products the Advertising API to build paid marketing solutions and Community Management API to build organic marketing solutions. Check out the updated Developer Portal to learn more on what you can build, with which API, and how it benefits your customers. If you have a paid marketing integration, no action is required. If you have an organic marketing integration, you will need to migrate to the new Community Management API by June 2023 to keep your integration active.

  • Posts API: Find posts authored by a specified member
    Starting with the 202301 version, we’re introducing a member author finder to enable you to fetch post contents authored by specified members. Results for all /posts finders (findByDscAccount and findByAuthor) will be sorted by last modified time in descending order (latest -> oldest) by default. This will help you manage post contents more efficiently.

  • Ad Analytics API: Sort reporting metrics
    The finder methods, Analytics and Statistics, of the adAnalytics endpoint now support two additional optional parameters: sortBy.field and sortBy.order. These parameters allow the results of these endpoints to be sorted in an ascending or descending order by one of the following fields: costInLocalCurrency, impressions, clicks, oneClickLeads, opens, sends, externalWebsiteConversions.

Breaking Changes

Content APIs: New batch size limit To handle batch requests more effectively, batch calls to the following endpoints: /creatives, /inMailContents, /posts, /videos, /images, /conversationAds, will only support 100 requests in a single batch, starting January 18, 2023. This change will apply to all versions.

Reminders

  • Migrate to versioned APIs before the end of February 2023 We now support API versioning for all LinkedIn Marketing APIs – giving you the power to decide when to adopt API changes. We will release a new version every month and intend to support each version for a full year with its own set of documentation that covers all Marketing APIs. Continue to check the Recent Changes page to stay up to date on the latest releases.

  • Make sure when calling an API version to include the request header with key “LinkedIn-Version” and set the value to correspond with the version you’re referencing using the YYYYMM format. Get started with this blog post, walk through video, or versioning documentation. Make sure to migrate before February 2023 when we will sunset unversioned APIs.

  • New Content APIs that simplify the content creation experience and save you time We introduced four new Content APIs that enable you to build quicker and to adopt the latest formats easier: Images, Videos, Post, and Creatives. With the new APIs, we’ve reduced the steps to upload creative assets and create posts; and the APIs are built to support your workflow. Get started with the new migration guide. Make sure to migrate to the new APIs before February 28, 2023 when we will sunset the Shares and UGC APIs.

Archived Marketing API Changes

To learn more about the Marketing API changes from November 2022 and earlier, refer to: