UGC Post API (Legacy)

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.

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.
  • ADMINISTRATOR
  • DIRECT_SPONSORED_CONTENT_POSTER
  • RECRUITING_POSTER
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.
  • ADMINISTRATOR
  • DIRECT_SPONSORED_CONTENT_POSTER
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:
  • DRAFT - Represents content that is accessible only to the author and is not yet published.
  • PUBLISHED - Represents content that is accessible to all entities. This is the only accepted field during creation.
  • PROCESSING - Represents content that has been submitted for publish but is not yet ready for rendering. The content will be published asynchronously once the processing has successfully completed.
  • PROCESSING_FAILED - Represents content that has been submitted for publish but a processing failure caused the publish to fail. An edit is required in order to re-attempt the publish.
  • DELETED - Represents content that was once in another state, but has been deleted.
  • PUBLISHED_EDITED - Represents content that was published and later edited.
  • ARCHIVED - Represents content that was published, then later archived. This content is no longer distributed and only retrievable by the author. Archived content can return to a published state upon update.
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:
  • CONNECTIONS - Represents 1st degree network of owner.
  • PUBLIC - Anyone can view this.
  • LOGGED_IN - Viewable by logged in members only.
  • CONTAINER - Visibility is delegated to the owner of the container entity. For example, posts within a group are delegated to the groups authorization API for visibility authorization.
com.linkedin.ugc. SponsoredContentVisibility which has the value of:
  • DARK - Represents a dark post, which is only distributed as part of a sponsored campaign.
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:
  • TWITTER- Distribute content to Twitter
  • TENCENT- Distribute content to Tencent
  • WEIBO - Distribute content to Weibo
Enum Values
feedDistribution Specifies the type of feed distribution. Does not distribute to feed when missing. Can be the following values:
  • NONE- Do not distribute within LinkedIn via feed.
  • MAIN_FEED- Distribute to the flagship feed, and container entity feed if applicable.
  • CONTAINER_ONLY - Distribute only to the container entity feed. The container is specified in the top level containerEntity field and is only valid when containerEntity exists. An example of a container entity feed is the LinkedIn Group feed.
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:
  • ARTICLE - Content containing articles
  • IMAGE - Content containing images
  • NONE - Content containing media
  • RICH - Content containing rich media
  • VIDEO - Content containing videos
  • LEARNING_COURSE - Content containing learning courses
  • JOB - Content contains jobs
  • QUESTION - Content containing questa questions
  • ANSWER - Content containing questa answers.
  • CAROUSEL - Various types of content rendered in carousel format
  • TOPIC - Content containing topics
  • NATIVE_DOCUMENT - Content file types that are uploaded natively
  • URN_REFERENCE - Media URN for the content category; except when URN type is digital media asset. Use mediaType in ShareMedia when disambiguation is required
  • LIVE_VIDEO - Video content streamed live - ugcPost may be consumed during recording. The resource serving the media is the source of truth for whether the video is currently live.
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:
  • IngestedVideoMetadata URN
  • IngestedImageMetadata URN
  • IngestedArticleMetadata URN
  • IngestedContent URN
  • IngestedRichMedia Metadata URN
  • DigitalmediaAsset URN
  • Content URN
  • 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:
    • PROCESSING - This ShareMedia is processing and not yet available.
    • READY - This ShareMedia is immediately available.
    • FAILED - This ShareMedia is not available and no further processing is being done.
    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:
    • SIZE_1
    • SIZE_2_TO_10
    • SIZE_11_TO_50
    • SIZE_51_TO_200
    • SIZE_201_TO_500
    • SIZE_501_TO_1000
    • SIZE_1001_TO_5000
    • SIZE_5001_TO_10000
    • SIZE_10001_OR_MORE
    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

    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.owner field of the referenced asset is the same as the author field when you create the UGC Post.
    • ShareContent.shareMediaCategory matches the same category as the media URN.
    • visibility can be set as SponsoredContentVisibility only when author is an organization URN.
    • shareContent.ShareMedia.landingPage.landingPageUrl is a required field for Video Dark Posts.
    • The member must have the role of Company Page ADMINISTRATOR or DIRECT_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:
    • com.linkedin.common.CompanyAttributedEntity
    • com.linkedin.common.MemberAttributedEntity
    This field accepts an object containing the referenced entity. See CompanyAttributedEntity, MemberAttributedEntity, and the sample request body for more information.
    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

    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

    GET https://api.linkedin.com/v2/ugcPosts/{encoded ugcPostUrn|shareUrn}?viewContext=AUTHOR
    

    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

    DELETE https://api.linkedin.com/v2/ugcPosts/{encoded ugcPostUrn|shareUrn}