UGC Post API (Legacy)
Warning
Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
Important
The above deprecation is applicable for partners with Marketing permissions only.
UGC Post is a content API best suited for creating and retrieving posts for organic video posts and video ads. For other media types, it is advised to use the Shares API.
As of now, you cannot retrieve the actual video content of a video post.
Organic video statistics are available. For more detail, see Organization Share Statistics
Note
The Posts API replaces the ugcPosts API for creating posts (User Generated Content) on behalf of an organization or member.
Permissions
| Permission | Description |
|---|---|
| w_organization_social | Post, comment and like posts on behalf of an organization. Restricted to organizations in which the authenticated member has one of the following company page roles.
|
| r_organization_social | Retrieve organizations' posts, comments, and likes. Restricted to organizations in which the authenticated member has one of the following company page roles.
|
| w_member_social | Post, comment and like posts on behalf of an authenticated member. |
| r_member_social | Restricted Retrieve posts, comments, and likes on behalf of an authenticated member. This is a private permission. |
| r_compliance | Retrieve posts, comments, and likes on behalf of an authenticated member for compliance monitoring and archiving. This is a private permission and access is granted to select developers. |
| w_compliance | Manage and delete data on behalf of an authenticated member for compliance requirements. This is a private permission and access is granted to select developers. |
See Organization Access Control for more information on company page roles.
Note
All API requests require the header X-Restli-Protocol-Version: 2.0.0.
Schema
| Field | Description | Format | Required |
|---|---|---|---|
| author | Author URN for this content | Person or Organization URN | Yes |
| clientApplication | For posts from API creation only | Developer Application URN | Optional |
| containerEntity | URN of container entity that contains the user generated content such as a Group or a Story | URN | Optional |
| contentCertificationRecord | The content certification record associated with this content. Used to maintain information about the content's visibility and spam status. | String | Optional |
| created | An AuditStamp corresponding to the creation of this resource. | AuditStamp | Yes |
| deleted | An AuditStamp corresponding to the deletion of this resource. | AuditStamp | Optional |
| distribution | LinkedIn and external destinations where the UGC post will be distributed. | Distribution | Optional |
| firstPublishedAt | The time at which this content was first published. Represented in epoch time. | long | Optional |
| id | Unique ID for this object | ugcPostURN or shareURN | Yes |
| lastModified | An AuditStamp corresponding to the last modification of this resource. | AuditStamp | Yes |
| lifecycleState | The state of this content. PUBLISHED is the only accepted field during creation. The following values can be returned in responses:
|
Enum String | Yes |
| responseContext | The context in which this content was created. Represents concepts such as reshare and reshare attribution. | ResponseContext | Optional |
| specificContent | Represents type-specific content of this object. For a share this is the share text and media, and for an article it is the article contents. | ShareContent | Yes |
| targetAudience | Intended audience or best fit audiences for this content as decided by the owner. | TargetAudience | Optional |
| versionTag | Version tag of the entity. | String | Optional |
| visibility | Visibility restrictions on content. Can be: com.linkedin.ugc. MemberNetworkVisibility which has the values of:
|
Union [MemberNetwork Visibility, SponsoredContent Visibility] | Yes |
Distribution
| Field | Sub-Field | Description | Format |
|---|---|---|---|
| distributedVia FollowFeed | Whether UGC post is distributed to follow-feed or not. | boolean | |
| externalDistribution Channels | External distribution channels that this content is distributed to. | Array | |
| externalDistribution ChannelType | Can be the following values:
|
Enum Values | |
| feedDistribution | Specifies the type of feed distribution. Does not distribute to feed when missing. Can be the following values:
|
optional enum |
ResponseContext
| Field | Description | Format |
|---|---|---|
| parent | The content that a piece of content is a response to. Currently, the only supported URN is ugcPost URN. | URN |
| parent | Response content. ugcPost URN supported | URN |
| root | The initiation or origination of the response content. ugcPost URN supported | URN |
ShareContent
| Field | Sub-Field | Description | Format | Required |
|---|---|---|---|---|
| media | The media shared in this share. Can be videos, images, or articles. | Array of ShareMedia | Yes | |
| primaryLandingPageUrl | The main landing page URL of the share. Maximum length is 2000 characters. | String | Optional | |
| shareCommentary | The message content of this share. | |||
| attributes | User generated attributes in the text. | Array of Attribute | Default to empty array | |
| inferredLocale | The locale that may have be inferred for this text. | String | Optional | |
| text | The text content that may be attributed. Defaults to "" NOTE: The maximum length of the text of a UGC Post is 3000 characters. |
String | Yes | |
| shareMediaCategory | The type of media contained within the media field of this object. Can be the following enum values:
|
Enum string | Yes |
ShareMedia
| Field | Sub-Field | Description | Format | Required |
|---|---|---|---|---|
| description | The description of this media. | Optional | ||
| attributes | User generated attributes in the text. | Array of Attribute | Default to empty array | |
| inferredLocale | The locale that may have be inferred for this text. | String | Optional | |
| text | The text content that may be attributed. Defaults to "" | String | Yes if providing description | |
| landingPage | Url that overrides the landing page. | Optional | ||
| landingPageTitle | If present, this content entity will be rendered as a CTA with landingPageTitle as the CTA text and landingPageUrl as the click through url. | String | Optional Possible values are- LEARN_MORE APPLY_NOW DOWNLOAD GET_QUOTE SIGN_UP SUBSCRIBE REGISTER | |
| landingPageUrl | The click through url. Maximum length is 2000 characters. | String | Yes if landing page present | |
| media | Shared media URN. Can be: |
URN | Yes | |
| mediaOverlay | An overlay associated with a media(video, image etc). | Optional | ||
| overlay | Union of possible MediaOverlay model, could be media frame, stickers etc. | MediaFrame object | ||
| originalUrl | URL whose content is summarized; content may not have a corresponding url for some entities. Maximum length is 8192 characters. | String | Optional | |
| status | The status of the availability of this media. Can be the following values:
|
Enum String | Yes | |
| thumbnails | The thumbnail saved from the ingestion of this article. If provided, only one thumbnail is used and any thumbnails beyond the first will be removed. Video thumbnails are not retrievable. | Optional, only allowed for article posts. | ||
| altText | The alternate text of this thumbnail. Used for screen reader accessibility. Maximum length is 4086 characters, recommended length is less than 120 characters. | String | Optional | |
| height | Height of the media in pixels. | int | Optional | |
| size | Size of the media in bytes. | long | Optional | |
| url | The url of this media. Maximum length is 8192 characters. | String | Yes if providing thumbnail | |
| width | Width of the media in pixels. | int | Optional | |
| title | The title of this media. | |||
| attributes | User generated attributes in the text. | Array of Attribute | Default to empty array | |
| inferredLocale | The locale that may have be inferred for this text. | String | Optional | |
| text | The text content that may be attributed. Defaults to "" | String | Yes |
Attribute
| Field | Sub-Field | Description | Format |
|---|---|---|---|
| length | The length of the range within the referenced ordered collection. Must be greater than zero and start + length must be less than the length of the referenced ordered collection. | int | |
| start | Starting position of the range within the referenced ordered collection. Must be greater than or equal to zero and start + length must be less than the length of the referenced ordered collection. Zero-based index. | int | |
| value | The value of the attribute that applies to given range. | Union [MemberAttributedEntity, CompanyAttributedEntity] | |
| com.linkedin.common. MemberAttributedEntity | Contains a member field that points to a personUrn | personUrn | |
| com.linkedin.common. CompanyAttributedEntity | Contains a company/school field that points to a company/school organization URN. You can retrieve company/school organization Urn using Organization Lookup API | organizationUrn | |
| com.linkedin.common. SchoolAttributedEntity | DEPRECATED. Please use CompanyAttributedEntity instead. Contains a school field that points to an organization URN | organizationURN |
TargetAudience
| Field | Sub-Field | Description | Format |
|---|---|---|---|
| targetedEntities | The entities targeted for distribution. Structured as an object containing multiple arrays of targeting entity URNs that functions like a series of OR conditionals. | Array of Targets (see below) | |
| degrees | Targeted standardized degrees | Array of Degree URN | |
| fieldsOfStudy | Targeted standardized fields of study | Array of FieldOfStudy URN | |
| industries | Targeted industries | Array of Industry URN | |
| interfaceLocales | Interface locales to be targeted. | Array of Locale | |
| jobFunctions | Targeted top level groupings of supertitles | Array of Function URN | |
| locations | Deprecated. Please use geoLocations field instead. Location to be targeted. The URNs do not need to all be of the same type. The permitted URN types are: 'countryGroup', 'country', 'state', and 'region' |
Array of Location URN | |
| geoLocations | Targeted GeoLocations | Array of Geo URN. Learn more | |
| schools | Deprecated. Please use organizations field instead. Standardized schools to be targeted. |
Array of School URN | |
| organizations | School Organizations to be targeted. You can retrieve school organization URN using Organization Lookup API | Array of Organization URN | |
| seniorities | Seniorities to be targeted | Array of Seniority URN | |
| staffCountRanges | Organization sizes to be targeted. Can be the following enum values:
|
Array of StaffCountRange |
Note
The audience you target for your share must be greater than 300 members. See Target Organic UGC Posts for more information
Create UGC Posts
Creating UGC Posts with video requires uploading a video asset to get a digitalmediaAsset URN to be used in creating the UGC Post. See the Vector Assets API for instructions on how to do this.
Note
The maximum length of the text of a UGC Post is 3000 characters.
- Create Organic UGC Posts
- Create Targeted Organic UGC Posts
- Create Dark UGC Posts
- Mention Organizations and Members
- Reshare UGC Posts
- Common Creation Errors
Create Organic UGC Posts
Sample Request
Make sure to set the Content-Type header to application/json.
If you plan to sponsor this post later, make sure you set shareContent.ShareMedia.landingPage and shareContent.ShareMedia.title when you create the post.
POST https://api.linkedin.com/v2/ugcPosts
{
"author": "urn:li:organization:5590506",
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [
{
"media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
"status": "READY",
"title": {
"attributes": [],
"text": "Sample Video Create"
}
}
],
"shareCommentary": {
"attributes": [],
"text": "Some share text"
},
"shareMediaCategory": "VIDEO"
}
},
"targetAudience": {
"targetedEntities": [
{
"geoLocations": [
"urn:li:geo:103644278"
],
"seniorities": [
"urn:li:seniority:3"
]
}
]
},
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
}
}
The UGC Post is created with a 201 Created response and the response header x-restli-id contains the ugcPost ID.
Create Targeted Organic UGC Posts
To increase the engagement and impact of your message, you may want to target organizational UGC Posts to a subset of your followers. You can select a target audience within your company's existing follower base by using predefined criteria known as targeting facets.
Examples of targeting facets include geography, job function, industry, and seniority level. See Ads Targeting and Standardized Data to create a segment of a specific audience you may want to target.
The audience you target for your UGC Post must be greater than 300 members. Use the Audience Counts API to calculate the approximate size of your audience. Make sure to pass in your organization URN in the followedCompanies field of the targetingFacet parameter so your audience count will be filtered down to only members who follow your company.
Sample Request
GET https://api.linkedin.com/v2/audienceCountsV2?q=targetingCriteria&target.includedTargetingFacets.industries[0]=urn:li:industry:4&target.includedTargetingFacets.seniorities[0]=urn:li:seniority:3&target.includedTargetingFacets.locations[0]=urn:li:geo:103644278&target.includedTargetingFacets.followedCompanies[0]=urn:li:organization:2414183
Sample Response
{
"elements": [
{
"active": 0,
"total": 380
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
Since this audience size is above 300, we can create a targeted organic UGC Post with these targeting details in the targetAudience.targetedEntities object. The targetAudience.targetedEntities object is structured as an array that accepts a single object. That object contains multiple targeting entity arrays. Each targeting facet array accepts targeting entity URNs. See the sample request below for an example.
Do not send null-equivalent targetAudience.targetedEntities objects where no targeting entity URNs are provided. If you do not want to target a UGC post, do not include the targetAudience field. See the following examples for null-equivalent targeting that is not supported.
"targetAudience": {"targetedEntities":[{"industries":[]},{"jobFunctions":[]}"targetAudience": {"targetedEntities":[{}]}"targetAudience": {"targetedEntities":[]}"targetAudience": {}
Sample Request
POST https://api.linkedin.com/v2/ugcPosts
{
"author": "urn:li:organization:2414183",
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [
{
"media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
"status": "READY",
"title": {
"attributes": [],
"text": "Sample Video Create"
}
}
],
"shareCommentary": {
"attributes": [],
"text": "Some share text"
},
"shareMediaCategory": "VIDEO"
}
},
"targetAudience": {
"targetedEntities": [
{
"geoLocations": [
"urn:li:geo:103644278"
],
"seniorities": [
"urn:li:seniority:3"
],
"industries": [
"urn:li:industry:4"
]
}
]
},
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
}
}
Create Dark UGC Posts
Dark UGC Posts are used to create content that will not appear as organic content on a LinkedIn company page. Dark posts can be used in Ad Campaigns as Direct Sponsored Content (DSC). See our Direct Sponsored Content Overview for more information.
You can create a dark UGC Post using an author as the organization urn:li:organization:{id} and setting visibility.com.linkedin.ugc.SponsoredContentVisibility = DARK.
Dark posts have additional required steps to be used in an Ad Campaign. See our additional documentation on Video Ads for those steps.
Sample Request
Make sure to set the Content-Type header to application/json.
POST https://api.linkedin.com/v2/ugcPosts
{
"author": "urn:li:organization:5590506",
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [
{
"landingPage": {
"landingPageTitle": "LEARN_MORE",
"landingPageUrl": "https:linkedin.com"
},
"media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
"status": "READY",
"title": {
"attributes": [],
"text": "Sample Video Create"
}
}
],
"shareCommentary": {
"attributes": [],
"text": "Some share text"
},
"shareMediaCategory": "VIDEO"
}
},
"visibility": {
"com.linkedin.ugc.SponsoredContentVisibility": "DARK"
}
}
The UGC Post is created with a 201 Created response and the response header x-restli-id contains the ugcPost ID.
To prevent failures, make sure to verify the following:
- The
registerUploadRequest.ownerfield of the referenced asset is the same as theauthorfield when you create the UGC Post. ShareContent.shareMediaCategorymatches the same category as the media URN.visibilitycan be set asSponsoredContentVisibilityonly whenauthoris anorganizationURN.shareContent.ShareMedia.landingPage.landingPageUrlis a required field for Video Dark Posts.- The member must have the role of Company Page
ADMINISTRATORorDIRECT_SPONSORED_CONTENT_POSTER.
When a UGC Post is published ("lifecycleState": "PUBLISHED"), an authorized member can view the post using:
https://www.linkedin.com/feed/update/urn:li:ugcPost:<id>/
Mentions in UGC Posts
You may create UGC Posts with mentions or tags of other Linkedin entities such as organizations or members. This requires providing the URN for the referenced entity, and specifying what part of the UGC Post's text should be rendered as a link to the entity.
The text linking to the entity must match the name of the member or organization to be converted into a link. Matching is case sensitive. If there is no match, that part will appear as normal text. This includes cases where the length provided is longer or shorter than the name of the member or organization. The exception to this for member annotations is described next.
Mentions of members only need to match one name in the full name. For example, take a member named "Jane Smith". A share can match on "Jane", "Smith", or "Jane Smith".
Mentions of organizations must match the full name.
If a mentions start or length is invalid, as described both in Attribute and below, then the creation or update of the share will be rejected with a 400 error code.
Schema
| Field | Description | Format |
|---|---|---|
| attributes | Allows links to other entities such as members within share text. | Array of attributes. |
| attributes[i].start | Starting character index of where in the text the annotation link should begin. Zero-based index. Must be greater than or equal to zero and start + length must be less than the length of the text. | int |
| attributes[i].length | The length of the text of be linked. Must be greater than zero and start + length must be less than the length of the text. | int |
| attributes[i].value | Describes the type of entity being mentioned. Possible values are:
|
Union CompanyAttributedEntity, MemberAttributedEntity ] |
CompanyAttributedEntity
| Field | Description | Format |
|---|---|---|
| company | The URN of organization being mentioned. | Organization URN |
MemberAttributedEntity
| Field | Description | Format |
|---|---|---|
| member | The URN of the person being mentioned. | Person URN |
Sample Object
The sample below mentions a company called Acme Corp. start=6 because Acme Corp starts on the sixth character of the text using a zero-based index. length=9 because "Acme Corp" is 9 characters long.
{
...
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"shareCommentary": {
"attributes": [
{
"length": 9,
"start": 6,
"value": {
"com.linkedin.common.CompanyAttributedEntity": {
"company": "urn:li:organization:1234"
}
}
}
],
"text": "Hello Acme Corp"
},
"shareMediaCategory": "NONE"
}
},
...
}
Reshare UGC Posts
UGC Posts can be reshared by setting the responseContext.parent field with the UGC Post URN you want to reshare.
POST https://api.linkedin.com/v2/ugcPosts
{
"lifecycleState": "PUBLISHED",
"visibility":{
"com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
},
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"shareMediaCategory": "NONE",
"shareCommentary":{
"text": "Test reshare text"
},
"media": [],
"shareCategorization": {}
}
},
"author": "urn:li:organization:789",
"responseContext":{
"parent": "urn:li:ugcPost:1234"
}
}
Common Creation Errors
The table below lists commonly encountered errors creating UGC Posts. It is not meant to be a comprehensive list of all possible UGC Post creation errors.
| Code | Message | Description |
|---|---|---|
| 400 | urn:li:developerApplication:{developer application ID} does not have permission to create ugc posts | Indicates your developer application is not allowlisted to create video UGC Posts. UGC Post video creation is restricted to approved applications only. |
| 400 | Error parsing request body to json Unrecognized character escape | Indicates your request payload is escaping characters it shouldn't. For example, escaping apostrophes such as "It\'s a test" will trigger this error. Review your payload for escaped characters and remove those escapes. |
| 400 | Post should only contain 1 set of targeting criteria | Indicates the targetedEntities field has more than 1 targeting object. See Create Targeted Organic UGC Posts for the correct structure. |
| 400 | Target audience does not meet 300 follower minimum | Indicates the targeted audience is too small to target. Audiences must have at least 300 members to be targeted. See Create Targeted Organic UGC Posts for how to calculate audience counts upfront. |
| 401 | Member is unauthorized to create UserGeneratedContent | Indicates the authenticated member does not have permission to create content on the given company page. |
| 403 | Not enough permissions to access: POST {endpoint} | Indicates the token used has not been scoped to the correct permissions. Generate a new token with w_organization_social or w_member_social. |
| 409 | Write conflict due to an internal UGC error. Please retry the create operation. | |
| 422 | Content is a duplicate of {share or UGC URN} | Indicates the UGC Post is an exact duplicate of a recently created UGC Post. Wait 10 minutes for the duplicate restriction to expire or modify the content. |
| 422 | Error validating the post | Indicates there is an error in the post, e.g. a required field is not present, a field with a length limit is too long, etc. The error message will contain the reason. |
| 429 | UGC action was blocked because a share limit has been reached | Indicates the author has reached a maximum daily share limit. |
| 429 | Resource level throttle {period} limit for calls to this resource is reached. | Indicates that the developer application has reached the maximum limit against this resource |
| for the given time period. |
Retrieve UGC Posts
- Get UGC Posts by URN
- Find UGC Posts by Authors
- Find UGC Posts by Container Entities
- Requesting Playable Video Streams
- Common Retrieval Errors
Note that URNs included in the URL params must be URL encoded when using Restli 2.0. For example, urn:li:ugcPost:12345 would become urn%3Ali%3AugcPost%3A12345. Other parts of the params should not be encoded. Postman or similar API tools may not support these types of calls. Testing with curl is recommended if you encounter a 400 error with message Invalid query parameters passed to request.
Note
All API requests are represented in protocol 2.0.0 and require the header X-Restli-Protocol-Version: 2.0.0.
Get UGC Posts by URN
To retrieve a UGC Post, provide the context in which the user generated content is being viewed. ViewContext can be either AUTHOR or READER. You can retrieve UGC posts by URNs: ugcPostUrn (urn:li:ugcPost:{id}) or shareUrn (urn:li:share:{id}).
Sample Request
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts/{encoded ugcPostUrn|shareUrn} \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'viewerContext=AUTHOR&projection=(...)'
Sample Response
{
"author": "urn:li:person:123ABC",
"contentCertificationRecord": "{\"originCountryCode\":\"us\",\"modifiedAt\":1500590592795,\"spamRestriction\":{\"classifications\":[],\"contentQualityClassifications\":[],\"systemName\":\"MACHINE_SYNC\",\"lowQuality\":false,\"contentClassificationTrackingId\":\"B6A8B437D1D5E59D123455F6DCE5B\",\"contentRelevanceClassifications\":[],\"spam\":false}}",
"created": {
"actor": "urn:li:person:123ABC",
"time": 1500590543962
},
"firstPublishedAt": 1500590592702,
"id": "urn:li:ugcPost:123456",
"lastModified": {
"actor": "urn:li:person:123ABC",
"time": 1500590592806
},
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [
{
"media": "urn:li:digitalmediaAsset:123ABDEFHAG",
"status": "READY",
"thumbnails": []
}
],
"shareCommentary": {
"attributes": [
{
"length": 35,
"start": 66,
"value": {
"com.linkedin.common.CompanyAttributedEntity": {
"company": "urn:li:organization:12345"
}
}
}
],
"text": "Testing a UGC Post!"
},
"shareMediaCategory": "VIDEO"
}
},
"versionTag": "2",
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
}
}
Video thumbnails are not retrievable.
Batch Get UGC Posts
Multiple UGC Posts can be retrieved in a single API call by passing in multiple UGC Post URNs into the ids parameter. The UGC Post URNs should be passed in List format and should be encoded as shown in the examples below. Note that the , in the List separating each URN does not need to be encoded.
Sample Request
GET https://api.linkedin.com/v2/ugcPosts?ids=List({encoded ugcPostUrn},{encoded ugcPostUrn})
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'ids=List({encoded ugcPostUrn},{encoded ugcPostUrn})&projection=(results*(...))'
curl -X POST 'https://api.linkedin.com/v2/ugcPosts \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'ids=List(urn%3Ali%3AugcPost%3A6380472009834450944,urn%3Ali%3AugcPost%3A6380472009834450944)&projection=(results*(...))'
Sample Response
{
"errors": {},
"results": {
"urn:li:ugcPost:638047200983445094": {
"author": "urn:li:person:Qih6zGPNUX",
"contentCertificationRecord": "{\"originCountryCode\":\"us\",\"modifiedAt\":1500590592795,\"spamRestriction\":{\"classifications\":[],\"contentQualityClassifications\":[],\"systemName\":\"MACHINE_SYNC\",\"lowQuality\":false,\"contentClassificationTrackingId\":\"B6A8B437D1D5E59DCB4D00C95F6DCE5B\",\"contentRelevanceClassifications\":[],\"spam\":false}}",
"created": {
"actor": "urn:li:person:Qih6zGPNUX",
"time": 1500590543962
},
"firstPublishedAt": 1500590592702,
"id": "urn:li:ugcPost:6293932920864212345",
"lastModified": {
"actor": "urn:li:person:Qih6zGPNUX",
"time": 1500590592806
},
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [
{
"media": "urn:li:digitalmediaAsset:123ABDEFHAG",
"status": "READY",
"thumbnails": []
}
],
"shareCommentary": {
"attributes": [
{
"length": 35,
"start": 66,
"value": {
"com.linkedin.common.CompanyAttributedEntity": {
"company": "urn:li:organization:12345"
}
}
}
],
"text": "Testing a post!"
},
"shareMediaCategory": "VIDEO"
}
},
"versionTag": "2",
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
}
}
},
"statuses": {}
}
Find UGC Posts by Authors
You can retrieve all UGC posts for a member or an organization. Use authors=List(person Urn) or authors=List(organization Urn) as the query parameter.
Even though authors is structured as an Array, you can currently only pass one value for authors. You will get a 400 Bad Request error with the message "Multi author finder not implemented, please make separate requests per author" if you pass more than one value.
URNs included in the URL params must be URL encoded. For example, urn:li:organization:12345 would become urn%3Ali%3Aorganization%3A12345. Other parts of the params do not need to be encoded. Postman or similar API tools may not support these types of calls. Testing with curl is recommended if you encounter a 400 error with message Invalid query parameters passed to request.
Sample Request
To retrieve all posts for a member. The r_member_social permission is required.
GET https://api.linkedin.com/v2/ugcPosts?q=authors&authors=List({encoded personUrn})&sortBy=LAST_MODIFIED
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'q=authors&authors=List({encoded personUrn})&sortBy=LAST_MODIFIED&projection=(elements*(...))'
To retrieve all posts for an organization. The r_organization_social permission is required.
GET https://api.linkedin.com/v2/ugcPosts?q=authors&authors=List({encoded organizationUrn})&sortBy=LAST_MODIFIED
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'q=authors&authors=List({organizationUrn})&sortBy=LAST_MODIFIED&projection=(elements*(...))'
Sample Response
{
"elements": [
{
"author": "urn:li:person:V9W_L_bioc",
"created": {
"actor": "urn:li:csUser:4",
"time": 1438989838000
},
"id": "urn:li:share:6035560836041302016",
"lastModified": {
"actor": "urn:li:csUser:4",
"time": 1438989838000
},
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [],
"shareCommentary": {
"attributes": [],
"text": ""
},
"shareMediaCategory": "NONE"
}
},
"versionTag": "0",
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "LOGGED_IN"
}
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
Options to Sort Result
You can also pass an optional param sortBy=CREATED or sortBy=LAST_MODIFIED to author finder which will sort UGC posts based on created timestamp field (created.time) or lastModified timestamp field (lastModified.time) in descending order (most recent to least recent). Without this param, by default, it is set to sortBy=LAST_MODIFIED.
Sample Request
To retrieve 2 posts for a member/organization sorted by its last modified timestamp (most recent to least recent):
GET https://api.linkedin.com/v2/ugcPosts?q=authors&authors=List({encoded personUrn/organizationUrn})&sortBy=LAST_MODIFIED&count=2
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'q=authors&authors=List({encoded personUrn|organizationUrn})&sortBy=LAST_MODIFIED&count=2&projection=(elements*(...))'
Sample Response
{
"elements": [
{
"author": "urn:li:person:V9W_L_bioc",
"created": {
"actor": "urn:li:csUser:4",
"time": 1438989838000
},
"id": "urn:li:share:6035560836041302016",
"lastModified": {
"actor": "urn:li:csUser:4",
"time": 1439989838000
},
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [],
"shareCommentary": {
"attributes": [],
"text": ""
},
"shareMediaCategory": "NONE"
}
},
"versionTag": "0",
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "LOGGED_IN"
}
},
{
"author": "urn:li:person:V9W_L_bioc",
"created": {
"actor": "urn:li:csUser:4",
"time": 1426576538000
},
"id": "urn:li:share:624460845041303116",
"lastModified": {
"actor": "urn:li:csUser:4",
"time": 1426576538000
},
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [],
"shareCommentary": {
"attributes": [],
"text": ""
},
"shareMediaCategory": "NONE"
}
},
"versionTag": "0",
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "LOGGED_IN"
}
}
],
"paging": {
"count": 2,
"links": [],
"start": 0
}
}
Find UGC Posts by Container Entities
You can retrieve all UGC posts of a group using containerEntities.
Note that URNs included in the URL params must be URL encoded. For example, urn:li:group:12345 would become urn%3Ali%3Agroup%3A12345. Other parts of the params do not need to be encoded. Postman or similar API tools may not support these types of calls. Testing with curl is recommended if you encounter a 400 error with message Invalid query parameters passed to request.
Sample Request
GET https://api.linkedin.com/v2/ugcPosts?q=containerEntities&containerEntities=List({encoded groupUrn}, {encoded groupUrn})
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'q=containerEntities&containerEntities=List({encoded groupUrn}, {encoded groupUrn})&projection=(elements*(...))'
Sample Response
{
"elements": [
{
"author": "urn:li:person:V9W_L_bioc",
"created": {
"actor": "urn:li:csUser:4",
"time": 1438989838000
},
"id": "urn:li:share:6035560836041302016",
"lastModified": {
"actor": "urn:li:csUser:4",
"time": 1438989838000
},
"lifecycleState": "PUBLISHED",
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"media": [],
"shareCommentary": {
"attributes": [],
"text": ""
},
"shareMediaCategory": "NONE"
}
},
"versionTag": "0",
"visibility": {
"com.linkedin.ugc.MemberNetworkVisibility": "LOGGED_IN"
}
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
Requesting Playable Video Streams
UGC Posts of type video can be decorated through playableStreams to return playable video URLs. For example:
GET https://api.linkedin.com/v2/ugcPosts/urn%3Ali%3AugcPost%3A6382695519264866304?viewContext=AUTHOR&projection=(specificContent(com.linkedin.ugc.ShareContent(media(*(media~:playableStreams)))))
If your request exceeds the maximum length requirement, please utilize query tunneling:
curl -X POST 'https://api.linkedin.com/v2/ugcPosts/urn%3Ali%3AugcPost%3A6382695519264866304 \
-H 'X-HTTP-Method-Override: GET' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer redacted' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
--data 'viewContext=AUTHOR&projection=(specificContent(com.linkedin.ugc.ShareContent(media(*(media~:playableStreams)))))'
Common Retrieval Errors
The table below lists commonly encountered errors retrieving UGC Posts. It is not meant to be a comprehensive list of all possible UGC Post retrieval errors.
| Code | Message | Description |
|---|---|---|
| 400 | Invalid query parameters passed to request | Occurs when using Restli 2.0 and the query parameters are not encoded properly. See Protocol Version for more on Restli 2.0 encoding. Calls with Postman and some other HTTP clients can trigger this error. Try using curl or another client when testing. |
| 401 | Member does not have author access to view UserGeneratedContent | Indicates the requested content is not viewable to the authenticated member requesting it. |
| 403 | Not enough permissions to access: GET-authors /ugcPosts | Indicates token used in the call has not been authorized with r_organization_social. Refer to Permissions for more information. |
Delete UGC Posts
Note that URNs included in the URL params must be URL encoded. For example, urn:li:ugcPost:12345 would become urn%3Ali%3AugcPost%3A12345.
UGC Post deletions are idempotent. Deletion requests for a previously deleted UGC Post will return 204 No Content.
Sample Request
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for