Publishing Article Migration Guide

Article
05/08/2023

On June 17, 2019, LinkedIn will begin changing how LinkedIn Publishing Articles are surfaced through the APIs. This migration guide documents the API workflows before and after these changes are made, and how to successfully continue satisfying your Publishing Articles use cases.

Retrieve Publishing Articles
Retrieve Reshares of Publishing Articles
Retrieve Social Actions of Publishing Articles
Social Actions on Publishing Articles

Background

A LinkedIn Publishing Article entity is referenced by Articles API. The entity currently has two identifiers:

Field Name	Type	Description
id	long	Unique identifier for article. Referenced in the {id} portion of `urn:li:linkedInArticle:{id}`
newsArticle	optional URN	The article URN (`urn:li:article:{id}`) referenced to look up comments and likes

As part of the migration, Publishing Articles will start surfacing in both Articles API and UGCPost API. The Articles will be identified by URN_REFERENCE value in the shareMediaCategory field and urn:li:linkedInArticle:{id} in media field:

{
  "specificContent": {
    "com.linkedin.ugc.ShareContent": {
      "shareMediaCategory": "URN_REFERENCE",
      "shareCommentary": {
        "text": "This is a LinkedIn Publishing Article!"
      },
      "media": [
        {
          "media": "urn:li:linkedInArticle:123456789",
          "thumbnails": [],
          "status": "READY"
        }
      ],
      "shareCategorization": {}
    }
  }
}

Articles API will have a new field:

Field Name	Type	Description
ugcPost	optional ugcPost URN	The ugcPost (`urn:li:ugcPost:{id}`) created when the article is initially published. This field only applies to articles created after migration, and is only valid for published articles

Lastly, the entity association for actions taken on an Article entity will change:

Action Taken	Old Entity Association	New Entity Association
Social Actions of a Publishing Article	`urn:li:article:{id}`	`urn:li:ugcPost:{id}`
Reshare of a Publishing Article	`urn:li:share:{id}`	`urn:li:ugcPost:{id}`

Retrieve Publishing Articles

Current Workflow

Currently, the possible ways to retrieve Publishing Articles include:

New Workflow

You can still use the Articles API but Publishing Articles will now surface through UGCPost as well:

Sample Request

GET https://api.linkedin.com/v2/ugcPosts?q=authors&authors=List({encoded personUrn})&projection=(elements*(author,clientApplication,created,distribution,lastModified,lifecycleState,permalinkSuffix,ugcOrigin,visibility,specificContent(*(shareMediaCategory,shareFeatures,media(*(media~linkedInArticle:publishingV2(authors*(author~(vanityName,profilePicture(displayImage~:playableStreams),localizedFirstName,localizedLastName,localizedHeadline),type),content,coverImage~:playableStreams,coverMedia,created,displayImage,id,lastModified,permlink,publishedAt,state,title,version)),thumbnails,description,landingPage,originalUrl,title,status),primaryLandingPageUrl,shareCategorization(skills*),shareCommentary(attributes*(length,start,value(*(*~))),inferredLocale,text))),responseContext(root~,parent~)))

GET https://api.linkedin.com/v2/ugcPosts/{ugcPost Urn}?projection=(author,clientApplication,created,distribution,lastModified,lifecycleState,permalinkSuffix,ugcOrigin,visibility,specificContent(*(shareMediaCategory,shareFeatures,media(*(media~linkedInArticle:publishingV2(authors*(author~(vanityName,profilePicture(displayImage~:playableStreams),localizedFirstName,localizedLastName,localizedHeadline),type),content,coverImage~:playableStreams,coverMedia,created,displayImage,id,lastModified,permlink,publishedAt,state,title,version)),thumbnails,description,landingPage,originalUrl,title,status),primaryLandingPageUrl,shareCategorization(skills*),shareCommentary(attributes*(length,start,value(*(*~))),inferredLocale,text)),responseContext(root~,parent~)))

After June 17, 2019, Compliance Events API will start surfacing Publishing Articles as both ugcPost (new) and originalArticles (old) activities for newly created Publishing Articles. LinkedIn will gradually migrate from the old workflow to the new workflow of ugcPost until it's fully ramped. Below is a sample response of the new activity:

Compliance Events API with ugcPost activity for Publishing Article

{
  "owner": "urn:li:person:yrZCpj2ZYQ",
  "resourceId": "urn:li:ugcPost:123456789",
  "configVersion": 36,
  "method": "CREATE",
  "activity": {
    "lifecycleState": "PUBLISHED",
    "visibility": {
      "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    },
    "specificContent": {
      "com.linkedin.ugc.ShareContent": {
        "shareMediaCategory": "URN_REFERENCE",
        "shareCommentary": {
          "text": "This is a LinkedIn Publishing Article!"
        },
        "media": [
          {
            "media": "urn:li:linkedInArticle:123456789",
            "thumbnails": [],
            "status": "READY"
          }
        ],
        "shareCategorization": {}
      }
    },
    "author": "urn:li:person:yrZCpj2ZYQ",
    "id": "urn:li:ugcPost:123456789",
    ...
  },
  "resourceName": "ugcPosts",
  "resourceUri": "/ugcPosts/urn:li:ugcPost:123456789",
  "actor": "urn:li:person:yrZCpj2ZYQ",
  "activityId": "8561f816-517e-49fb-901d-29c589e3b09f",
  "processedAt": 1552071375435,
  "capturedAt": 1552071345264,
  "processedActivity": {
    "lifecycleState": "PUBLISHED",
    "visibility": {
      "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    },
    "specificContent": {
      "com.linkedin.ugc.ShareContent": {
        "shareMediaCategory": "URN_REFERENCE",
        "shareCommentary": {
          "text": "This is a LinkedIn Publishing Article!"
        },
        "media": [
          {
            "media": "urn:li:linkedInArticle:123456789",
            "media~": {
              "authors": [
                {
                  "author": "urn:li:person:123ABC",
                  "type": "PRIMARY_AUTHOR"
                }
              ],
              "content": {
                "com.linkedin.publishing.HtmlContent": {
                  "htmlText": "<p>And text</p>",
                  "secureHtmlText": "<p>And text</p>"
                }
              },
              "coverImage": {
                "caption": "",
                "croppedImage": {
                  "cropInfo": {
                    "height": 1333,
                    "width": 2000,
                    "x": 0,
                    "y": 0
                  },
                  "cropped": "urn:li:digitalmediaAsset:C5400AQENYhjODZ9eRw",
                  "original": "urn:li:digitalmediaAsset:C5400AQENYhjODZ9eRw"
                }
              },
              "created": 1517248648000,
              "displayImage": "urn:li:digitalmediaAsset:C5400AQENYhjODZ9eRw",
              "id": 123456789,
              "lastModified": 1517253706000,
              "locale": {
                "language": "en"
              },
              "newsArticle": "urn:li:article:7255369085935814179",
              "permlink": "article-with-new",
              "publishCommentary": {
                "attributes": [],
                "text": ""
              },
              "publishedAt": 1517253706000,
              "state": "PUBLISHED",
              "title": "Article with New Media Type",
              "version": 12
            },
            "thumbnails": [],
            "status": "READY"
          }
        ],
        "shareCategorization": {}
      }
    },
    "author": "urn:li:person:yrZCpj2ZYQ",
    "id": "urn:li:ugcPost:123456789",
    ...
  }
}

Retrieve Reshares of Publishing Articles

All Reshares of Publishing Article will surface through UGCPost API. There are two ways to Reshare a Publishing Article:

Share the article URL through the share box
Share the article through the article reader button

For sharing the article URL through the share box, it will have the following changes:

Field Name	Current Value	New Value
id	`urn:li:share:{id}`	`urn:li:ugcPost:{id}`
shareMediaCategory	ARTICLE	URN_REFERENCE
media	`urn:li:article:{id}`	`urn:li:linkedInArticle:{id}`

This is identical to the initial publishing of the article mentioned above. Old Articles will continue to maintain the old reshare flow while the new articles created will go through the new reshare flow. To decorate the media URN field, please refer to the above sample requests' projection.

For sharing the article through the article reader button, it will be a reshare of the initial ugcPost. See below for an example:

Reshare of Publishing Article via Article Reader Button

{
  "lifecycleState": "PUBLISHED",
  "visibility": {
    "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
  },
  "specificContent": {
    "com.linkedin.ugc.ShareContent": {
      "shareMediaCategory": "NONE",
      "shareFeatures": {
        "hashtags": []
      },
      "shareCommentary": {
        "text": "This is a reshare via article reader button"
      },
      "media": [],
      "shareCategorization": {}
    }
  },
  "responseContext": {
    "parent": "urn:li:ugcPost:6521432600718954496",
    "root": "urn:li:ugcPost:6521432600718954496"
  },
  ...
}

For Compliance Events API, Reshare a Publishing Article is currently surfaced as a ugcPost activity. With the migration, it will still be ugcPost activity. Between the two ways to reshare, the first is identical to the creation of a Publishing Article from above. See below for a sample response on the second way to reshare:

Compliance Events API of Reshare a Publishing Article via Article Reader Button

{
  "resourceId": "urn:li:ugcPosts:123456789",
  "resourceName": "ugcPosts",
  "resourceUri": "/ugcPosts/urn:li:ugcPosts:123456789",
  "activity": {
    "lifecycleState": "PUBLISHED",
    "visibility": {
      "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    },
    "specificContent": {
      "com.linkedin.ugc.ShareContent": {
        "shareMediaCategory": "URN_REFERENCE",
        "shareFeatures": {
          "hashtags": []
        },
        "shareCommentary": {
          "text": "This is a reshare via article reader button"
        },
        "media": [],
        "shareCategorization": {}
      }
    },
    "responseContext": {
      "parent": "urn:li:ugcPost:6521432600718954496",
      "root": "urn:li:ugcPost:6521432600718954496"
    },
    ...
  },
  "processedActivity": {
    "specificContent": {
      "com.linkedin.ugc.ShareContent": {
        "shareMediaCategory": "URN_REFERENCE",
        "media": [],
        "shareCategorization": {}
      }
    },
    "id": "urn:li:ugcPost:123456789",
    "responseContext": {
      "parent": "urn:li:ugcPost:6521432600718954496",
      "parent~": {...},
      "root": "urn:li:ugcPost:6521432600718954496",
      "root~": {...}
    },
    ...
  },
  ...
}

Currently, Social Actions of Publishing Article are attributed to the article's newsArticle (urn:li:article:{id}) URN. See here for more information.

With the migration, all new Publishing Articles' Social Actions will be attributed to the ugcPost (urn:li:ugcPost:{id}) URN. The old Publishing Articles will remain on the article's newsArticle URN. See below for sample requests:

Retrieve Comments for an Article

GET https://api.linkedin.com/v2/socialActions/{ugcPost Urn}/comments

Retrieve Likes for an Article

GET https://api.linkedin.com/v2/socialActions/{ugcPost Urn}/likes

The object and $URN field in Social Actions API will return ugcPost related URNs.

For Compliance Events API, Social Actions on a Publishing Article is already being surfaced. With the migration, the object association will change to ugcPost URN. See below for sample responses:

Compliance Events API of Comment on a Publishing Article

{
  "activity": {
    "actor": "urn:li:person:KPA1hpZ1yM",
    "created": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "time": 1492112821044
    },
    "id": "6258374773714362368",
    "lastModified": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "time": 1492112821044
    },
    "likesSummary": {
      "aggregatedTotalLikes": 0,
      "likedByCurrentUser": false,
      "selectedLikes": [],
      "totalLikes": 0
    },
    "message": {
      "attributes": [],
      "text": "This is a comment on a publishing post."
    },
    "object": "urn:li:ugcPost:123456789"
  },
  "processedActivity": {
    "actor": "urn:li:person:KPA1hpZ1yM",
    "actor~": {...},
    "created": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "actor~": {...},
      "time": 1492112821044
    },
    "id": "6258374773714362368",
    "lastModified": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "actor~": {...},
      "time": 1492112821044
    },
    "message": {
      "attributes": [],
      "text": "This is a comment on a publishing post."
    },
    "object": "urn:li:ugcPost:123456789",
    "object~": {
      "specificContent": {
        "com.linkedin.ugc.ShareContent": {
          "shareMediaCategory": "URN_REFERENCE",
          "media": [
            {
              "media~": {...},
              "media": "urn:li:linkedInArticle:123456789",
              "status": "READY"
            }
          ],
          "shareCategorization": {}
        }
      }
    }
  },
  "resourceName": "socialActions/comments",
  "resourceUri": "/socialActions/urn:li:ugcPost:123456789/comments/6258374773714362368",
  ...
}

Compliance Events API of Like on a Publishing Article

{
  "activity": {
    "actor": "urn:li:person:KPA1hpZ1yM",
    "created": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "time": 1492112791993
    },
    "lastModified": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "time": 1492112791993
    },
    "object": "urn:li:ugcPost:123456789"
  },
  "processedAt": 1492112812255,
  "capturedAt": 1492112792032,
  "processedActivity": {
    "actor": "urn:li:person:KPA1hpZ1yM",
    "actor~": {...},
    "created": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "actor~": {...},
      "time": 1492112791993
    },
    "lastModified": {
      "actor": "urn:li:person:KPA1hpZ1yM",
      "actor~": {...},
      "time": 1492112791993
    },
    "object~": {...},
    "object": "urn:li:ugcPost:123456789"
  },
  "resourceName": "socialActions/likes",
  "resourceUri": "/socialActions/urn:li:ugcPost:123456789/likes/urn:li:person:KPA1hpZ1yM",
  "resourceId": "urn:li:ugcPost:123456789"
  ...
}

Currently, Social Actions of Publishing Article are attributed to the article's newsArticle (urn:li:article:{id}) URN. See here for more information on Social Action creation.

Create Comment for an Article (OLD)

POST https://api.linkedin.com/v2/socialActions/{article Urn}/comments

Create Like for an Article (OLD)

POST https://api.linkedin.com/v2/socialActions/{article Urn}/likes

Create Comment for an Article (NEW)

POST https://api.linkedin.com/v2/socialActions/{ugcPost Urn}/comments

Create Like for an Article (NEW)

POST https://api.linkedin.com/v2/socialActions/{ugcPost Urn}/likes

Publishing Article Migration Guide

Background

Retrieve Publishing Articles

Current Workflow

New Workflow

Sample Request

Compliance Events API with ugcPost activity for Publishing Article

Retrieve Reshares of Publishing Articles

Reshare of Publishing Article via Article Reader Button

Compliance Events API of Reshare a Publishing Article via Article Reader Button

Retrieve Comments for an Article

Retrieve Likes for an Article

Compliance Events API of Comment on a Publishing Article

Compliance Events API of Like on a Publishing Article

Create Comment for an Article (OLD)

Create Like for an Article (OLD)

Create Comment for an Article (NEW)

Create Like for an Article (NEW)

Feedback

Feedback

Additional resources

Publishing Article Migration Guide

Background

Retrieve Publishing Articles

Current Workflow

New Workflow

Sample Request

Compliance Events API with ugcPost activity for Publishing Article

Retrieve Reshares of Publishing Articles

Reshare of Publishing Article via Article Reader Button

Compliance Events API of Reshare a Publishing Article via Article Reader Button

Retrieve Social Actions of Publishing Articles

Retrieve Comments for an Article

Retrieve Likes for an Article

Compliance Events API of Comment on a Publishing Article

Compliance Events API of Like on a Publishing Article

Social Actions on Publishing Articles

Create Comment for an Article (OLD)

Create Like for an Article (OLD)

Create Comment for an Article (NEW)

Create Like for an Article (NEW)

Feedback

Feedback

Additional resources