Content API Migration
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.
This topic summarizes the changes between legacy APIs and the Content APIs that replace them.
Share API → Posts API
Workflow Changes
- Find posts by author supports a single author per request. Multi-author finder calls are not supported.
- Direct Sponsored Content are managed by the adContext.dscStatus field.
- Archive direct sponsored content is supported by using the Post API's adContext.dscStatus field.
Schema Changes
Request Schema
| Share API | Posts API |
|---|---|
| activity | removed |
| agent | adContext.dscAdAccount |
| content.title | For articles, content.article.title. For images, content.media.title. |
| content.landingPageUrl | content.article.source |
| content.commentary | commentary |
| contentEntities | Moved to content.carousel |
| shareMediaCategory | Removed, but a similar concept exists under content under the various content types. |
| owner | author |
| subject | removed |
| resharedShare | reshareContext.parent |
| originalShare | reshareContext.root |
UgcPosts API → Posts API
Workflow Changes
- For versions prior to 202301, find Posts by authors is only supported for organization authors. For versions 202301 and above, finding by both person and organization authors are supported.
- Find Posts by container entity is not supported.
- Thumbnails for Article Posts must be fetched and uploaded.
Schema Changes
Request Schema
| UgcPosts API | Posts API |
|---|---|
| clientApplication | removed |
| containerEntity | container |
| contentCertificationRecord | removed |
| AuditStamps (created, deleted, lastModified fields) | Flattened, simplified, and renamed to createdAt, lastModifiedAt, createdBy, lastModifiedBy |
| distribution | See Distribution table |
| responseContext | reshareContext |
| versionTag | removed |
| targetAudience | distribution.targetEntities |
| commentary field using Attributes and attributed text | Flattened to a single string field supporting little text |
| visibility | SponsoredContentVisibility has been removed. SponsoredContentVisibility.DARK is replaced by the setting distribution.NONE and visibility.PUBLIC. |
| specificContent | Renamed to content and support types mentioned in content |
Distribution Data Model
| UgcPosts Distribution Data Model | Posts Distribution Data Model |
|---|---|
| distributedViaFollowFeed | removed |
| externalDistributionChannels | thirdPartyDistributionChannels |
| feedDistribution | feedDistribution |
AdCreativesV2 API→ Creatives API
Workflow Changes
The creatives API simplifies the adCreativesV2 API schema.
- You no longer need to create Direct Sponsored Content before creating a creative.
- You no longer need to specify a
typefield. It is now inferred automatically based oncontent.
Schema Changes
| AdCreativesV2 API | Creatives API | Notes |
|---|---|---|
| id | id | id has changed from a long (123) to a SponsoredCreativeUrn (urn:li:sponsoredCreative:123) |
| status | intendedStatus | Field renamed to clarify the intent |
| servingStatuses | isServing + servingHoldReasons | boolean isServing to convey whether a creative is serving. servingHoldReasons will be present when this field is false. |
| type | N/A | Removed as type is inferred automatically based on the content |
| reference + variables | content | The content field can either be reference to a post or an inline content for dynamic ads, text ads and so on. |
| callToAction | leadgenCallToAction | Field renamed |
AdInMailContentsV2 API → InMailContents API
The InMailContents API simplifies the previous schema by renaming fields to more closely reflect their purpose, removing deprecated fields/types, and flattening the structure for better ease-of-use.
Schema Changes
Request Schema
| AdInMailContentsV2 API | InMailContents API |
|---|---|
legalText.rawText field |
Renamed to customFooter |
sender field |
Sender only contains MemberUrn who has permissions on the account |
| Standard SubContent field | - com.linkedin.ads.AdInMailStandardSubContent renamed to regular- Removed deprecated field adUnit- Action renamed to landingPageUrl- adUnitV2 renamed to landingPageUrl and only supports Image URN- Introduced nesting for better clarity |
| Form SubContent field | - com.linkedin.ads.AdInMailFormSubContent renamed to form- removed deprecated field adUnit - action renamed to landingPageUrl- adUnitV2 renamed to rightRailAdPicture and only supports Image URN- introduced nesting for better clarity |
| GuidedReplies SubContent field | - com.linkedin.ads.AdInMailFormSubContent renamed to guidedReplies- rightRailAdPicture only supports Image URN |
| LeadGen SubContent field | Deprecated |
editable field |
Removed |
Response Schema
| AdInMailContentsV2 API | InMailContents API |
|---|---|
| changeAuditStamps fields | Flattened and renamed to lastModifiedAt/lastModifiedBy/createdAt/createdBy |
sponsoredConversations API → conversationAds API
Schema Changes
| sponsoredConversations API | conversationAds API |
|---|---|
editable field |
removed (inferred) |
| sponsoredConversations/SponsoredMessageContents API | conversationAds/SponsoredMessageContents API |
|---|---|
body field |
removed (deprecated) |
type field |
removed (inferred) |
bodySource.Attachment and bodySource.AttachmentAndText fields |
Changed to bodySource.MediaAttachment with an optional text field |
SponsoredMessageOption.type |
Renamed to SponsoredMessageOption.replyType |
SponsoredMessageOption.landingPage |
Flatter structure, duplicate landingPage removed from SponsoredMessageContent.ActionTarget field |
SponsoredMessageOption.ActionTarget field |
Removed field, including both duplicate child fields leadGenerationForm and landingPage fields |
Assets API → Images API
Workflow Changes
You are no longer required to provide an upfront recipe when uploading images (for example feedshare-image etc.)
Schema Changes
| Assets API | Images API | Notes |
|---|---|---|
| Requires recipe names (eg: feedshare-image) | Does not require any upfront statement of recipe or image usage intent | You do not need to input recipe names and can reuse images across different image ad placements (single image ad, dynamic ad, etc) |
| Returns generic digitalMediaAsset URN for all content | Returns specific URN (e.g. urn:li:image:C4D10AQFjGx47bqmcTA) |
Purpose-built response URN rather than generic asset URN |
Returns mediaArtifact field with superfluous details |
Does not return mediaArtifact field. Simplified response structure |
|
| Headers for AWS S3 Upload for backward compatibility (LinkedIn has storage capability) | No unnecessary headers | Simplified response structure |
| Action Purpose | Assets API Action Name | Images API Name |
|---|---|---|
| Initialize Image Upload | registerUpload | initializeUpload |
Assets API → Videos API
Workflow Changes
The following steps are no longer required to create a video ad with the Videos API:
- Verify access to create a video ad using
organizationalEntityCreateShareAuthorizations- Then access check that the video creation is done by the underlying services. - Create AdDirectSponsoredContent - The adDirectSponsoredContent option is set at the posts API request payload.
Schema Changes
| Assets API | Videos API | Benefit |
|---|---|---|
| All assets are managed through a single API | Video specific actions and fields like aspect ratio, captions, etc. | Better defined models, extended features/ |
| Action Purpose | Assets API Action Name | Videos API Name |
|---|---|---|
| Initialize video upload | registerUpload | initializeUpload |
| Complete video upload | completeMultiPartUpload | finalizeUpload |
Request Schema
| Assets API | Videos API | Notes |
|---|---|---|
| Requires recipe names (e.g., feedshare-video, feedshare-image) | No recipe or intent needed | Do not have to know internal recipe names |
| Provide service relationships during upload | Do not need to provide service relationship | Internal UGC relationships inferred by LinkedIn |
| Figure out which request schema to use based on the file size | Single request schema with multi-part upload option as default | Consistent schema for all file sizes |
| File-size param optional for a single part but mandatory for multi-part uploads | File-size param mandatory | Determine file sizes to figure out the upload option |
| Single part or multi part upload | Multi part upload by default | Single upload mode |
| Nested field relationships | Plain schema | Simplified schema structure |
Improvements with Request Schema to complete Upload
| Assets API | Videos API | Notes |
|---|---|---|
| Nested field relationships required in the request schema | Plain schema | Simplified Request structure |
| Metadata, mediaArtifact, ETags, status fields required in request schema | Requires only ETags and upload token (previously metadata) Simplified request structure | Simplified Request structure |
Response Schema
| Assets API | Videos API | Notes |
|---|---|---|
| Returns generic digitalMediaAsset URN for all content | Returns specific URN (e.g. video:C4E05AQEw_VQIt69CrA) |
Purpose-built response URN rather than generic asset URN |
| Returns mediaArtifact field with superfluous details | Does not return mediaArtifact fieldSimplified response structure | |
| Headers for AWS S3 Upload for backward compatibility (LinkedIn has storage capability) | No headers | Simplified response structure |
| urlExpiresAt param present in multi-part even with consistent value | urlExpiresAt param outside nested structure for a single value Simplified response structure | |
| Nested field relationships | Plain schema | Simplified response structure |
| Supplemental assets like captions and thumbnails are not available | Can upload captions and thumbnails | More features |