Partager via

Share API (Legacy)

  • Article

Warning

Deprecation Notice
The Marketing Version 202311 (Marketing November 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Network updates serve as a core experience on LinkedIn, enabling members to share rich content to their professional network. Use the Share API in your application to allow members to take full advantage of the share functionality. Use the Share API for:

  • Seamless integrations for user-generated content distribution
  • Custom integrations of sharing and re-sharing read articles
  • Posting user activity and associated content

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.

See Organization Access Control for more information on company page roles.

Note

You may never store profile information, other than person URNs retrieved from the /shares API.

Share Types

The /shares API allows access to both personal shares and organization shares. The type of URN specified in the owner field of a share indicates the share type.

URN Type Share Type Description
urn:li:person Personal Share Share was created by a member. The member is displayed as the publisher.
urn:li:organization Organization Share Share was created by a member for an organizational entity. The organization or brand is displayed as the publisher.

Schema

Field Name Type Description
activity Activity URN URN of the activity associated with this share. Activities act as a wrapper around shares and articles to represent content in the LinkedIn feed. Read only.
agent URN Agent is the Sponsored Ad Account that created the Direct Sponsored Content (DSC) Share on behalf of an organization.
content Share Content Referenced content such as articles and images.
created Audit Stamp Time of creation. Read only.
distribution. linkedInDistributionTarget Share Distribution Target Distribution target for the share.
edited boolean A flag that indicates if this share was edited by a member. Read only.
id string Unique ID for the share. Read only.
lastModified Audit Stamp Time of last modification. Read only.
originalShare Share URN If this share is a reshare, then this is the URN of the original/root share that was reshared.
owner Person or Organization URN Owner of the share. Required on create.
resharedShare Share URN Share being reshared.
subject String Share subject.
text Share Text Text entered by the member for this share, which may contain annotations.
clientApp URN Optional. It is represented as a developerApplication URN. Decoration results in the name of the application.

Retrieve Shares

Look up Share by ID

GET https://api.linkedin.com/v2/shares/{share ID}

Find Shares by Owner

Your application can retrieve the collection of shares owned by a specific member or organization. Use URNs formatted as urn:li:person:{id} , urn:li:organization:{id} , or urn:li:organizationBrand:{id} to retrieve shares for the relevant entity.

Sample Request

GET https://api.linkedin.com/v2/shares?q=owners&owners={URN}&sortBy=LAST_MODIFIED&sharesPerOwner=100

If you don't specify sharesPerOwner, the default is 1. That means that you only get 1 element in your result set. We recommend setting the sharesPerOwner to 1,000 and count to 50, which means the endpoint returns up to 1,000 shares per owner, while the total elements returned per response is 50. To get the next 50 of 1,000, paginate with the start query parameter. Note that the pagination excludes UGC and Direct Sponsored Content (DSC) posts.

The following authorization rules apply when specifying owners :

  • For personal shares, you may only retrieve shares for the authorized members.
  • For organization shares, you may only retrieve shares for organizations for which the authorized member is an administrator. See Organization Access Control for details.
  • To retrieve Direct Sponsored Content shares, the authorized member must have the appropriate Ad Account access to the sponsoring account. The finder only returns Direct Sponsored Content shares where the authorized member has an Account User Role that is higher than VIEWER for the sponsoring Ad Account (not inclusive of VIEWER).

Sample Response

{
    "activity": "urn:li:activity:12345657",
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:article:0",
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "imageSpecificContent": {},
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "description": "content description",
        "title": "Test Share with Content"
    },
    "created": {
        "actor": "urn:li:person:A8xe03Qt10",
        "time": 1471967236000
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "id": "6173878065928642560",
    "lastModified": {
        "actor": "urn:li:person:A8xe03Qt10",
        "time": 1471967237000
    },
    "owner": "urn:li:organization:123456789",
    "text": {
        "text": "Test Share!"
    }
}

Options to Sort Result

You can also pass an optional param sortBy=CREATED or sortBy=LAST_MODIFIED to owner finder which will sort shares 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 shares owned by specified urn sorted by last modified timestamp (most recent to least recent):

GET https://api.linkedin.com/v2/shares?q=owners&owners={URN}&sortBy=LAST_MODIFIED&sharesPerOwner=2

Sample Response

{
    "activity": "urn:li:activity:1255657",
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:article:0",
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "imageSpecificContent": {},
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "description": "content description",
        "title": "Test Share with Content latest"
    },
    "created": {
        "actor": "urn:li:person:A8xe03Qt10",
        "time": 1473967236000
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "id": "6173878065928642560",
    "lastModified": {
        "actor": "urn:li:person:A8xe03Qt10",
        "time": 1476967859000
    },
    "owner": "urn:li:organization:123456789",
    "text": {
        "text": "Test Share latest!"
    }
},
{
    "activity": "urn:li:activity:1245872",
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:article:0",
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "imageSpecificContent": {},
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "description": "content description",
        "title": "Test Share with Content 2nd latest"
    },
    "created": {
        "actor": "urn:li:person:A8xe03Qt10",
        "time": 1471967236000
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "id": "6173878065928642560",
    "lastModified": {
        "actor": "urn:li:person:A8xe03Qt10",
        "time": 1471967237000
    },
    "owner": "urn:li:organization:123456789",
    "text": {
        "text": "Test Share 2nd latest!"
    }
}

Retrieve Multiple Shares

Multiple share posts can be retrieved in a single API call by passing in multiple share post URNs into the ids parameter as an array.

Sample Request

For Restli V1.0

GET https://api.linkedin.com/v2/shares?ids[0]={shareId1}&ids[1]={shareId2}
For Restli V2.0

Pass share post URN parameters in List format.

GET https://api.linkedin.com/v2/shares?ids=List({shareId1},{shareId2})

Sample Response

{ 
   "statuses":{ 

   },
   "results":{ 
      "6579475525855698944":{ 
         "owner":"urn:li:organizationBrand:5025865",
         "activity":"urn:li:activity:6579475526610669568",
         "edited":true,
         "created":{ 
            "actor":"urn:li:person:_Kx_SRl3wr",
            "time":1568669206135
         },
         "id":"6579475525855698944",
         "lastModified":{ 
            "actor":"urn:li:csUser:0",
            "time":1568852267383
         },
         "text":{ 
            "annotations":[ 

            ],
            "text":"https://lnkd.in/gacVuy4 #astronomy "
         },
         "distribution":{ 
            "linkedInDistributionTarget":{ 
               "visibleToGuest":true
            }
         },
         "content":{ 
            "contentEntities":[ 
               { 
                  "description":"Scientists have discovered what could be the largest neutron star on record, according to new research.",
                  "entityLocation":"https://gizmodo.com/extremely-massive-neutron-star-may-be-the-largest-ever-1838146004?utm_medium=paid&utm_source=linkedin&utm_campaign=Lead+generation+-+Sep+4,+2019&hsa_grp=152637344&hsa_cam=502840441&hsa_ver=3&hsa_acc=502840441&hsa_ad=86486114&hsa_net=linkedin",
                  "title":"Extremely Massive Neutron Star May Be the Largest Ever Spotted",
                  "thumbnails":[ 
                     { 
                        "imageSpecificContent":{ 
                           "size":141287,
                           "width":1600,
                           "height":900
                        },
                        "resolvedUrl":"https://i.kinja-img.com/gawker-media/image/upload/s--XBRS9Rt6--/c_fill,fl_progressive,g_center,h_900,q_80,w_1600/zeo7usowdoidkxdmyxw5.jpg"
                     }
                  ],
                  "entity":"urn:li:article:8065153848276925532"
               }
            ],
            "shareMediaCategory":"ARTICLE",
            "description":"Scientists have discovered what could be the largest neutron star on record, according to new research.",
            "title":"Extremely Massive Neutron Star May Be the Largest Ever Spotted"
         }
      },
      "6552852138773495808":{ 
         "owner":"urn:li:organizationBrand:5025865",
         "activity":"urn:li:activity:6552852139327148032",
         "edited":false,
         "created":{ 
            "actor":"urn:li:person:GyRnqga7MU",
            "time":1562321696016
         },
         "id":"6552852138773495808",
         "lastModified":{ 
            "actor":"urn:li:csUser:0",
            "time":1562321696107
         },
         "text":{ 
            "text":"Test"
         },
         "distribution":{ 
            "linkedInDistributionTarget":{ 
               "visibleToGuest":true
            }
         },
         "content":{ 
            "contentEntities":[ 
               { 
                  "description":"",
                  "entityLocation":"https://media.licdn.com/dms/image/C4D22AQFW0BYUKIsfZA/feedshare-shrink_1280/0?e=1571875200&v=beta&t=DqCtbv_T0PkT7oDGd2m_EgeOTVKUA7n8qQujJi_-X-4",
                  "thumbnails":[ 
                     { 
                        "imageSpecificContent":{ 
                           "width":1200,
                           "height":628
                        },
                        "resolvedUrl":"https://media.licdn.com/dms/image/C4D22AQFW0BYUKIsfZA/feedshare-shrink_1280/0?e=1571875200&v=beta&t=DqCtbv_T0PkT7oDGd2m_EgeOTVKUA7n8qQujJi_-X-4"
                     }
                  ],
                  "entity":"urn:li:digitalmediaAsset:C4D22AQFW0BYUKIsfZA"
               }
            ],
            "shareMediaCategory":"RICH",
            "description":""
         }
      }
   },
   "errors":{ 

   }
}

Common Retrieval Errors

The table below lists commonly encountered errors retrieving Shares. It is not meant to be a comprehensive list of all possible Share retrieval errors.

Code Message Description
400 Syntax exception in path variables Indicates incorrect syntax in request URL. Commonly due to using Restli 2.0 and not encoding URNs.
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 {endpoint} Indicates the token used has not been scoped to the correct permissions. Generate a new token with r_organization_social.

Share Comments and Likes

See Social Actions API for details on retrieving share likes and comments.

Post Shares

Your application may post shares in the context of a specific member or organization. Use a URN in the owner field to associate the share with an organization or authenticated member. The valid URN formats are urn:li:person:{id} or urn:li:organization:{id}.

You will need the permission w_member_social to create shares on behalf of a member, or w_organization_social to create shares on behalf of an organization.

Note

As with any API that allows you to post on behalf of a member, always ensure that the member is fully aware that your application is sharing content on their behalf.

The following authorization rules apply when posting a share:

  • For personal shares, you may only post shares as the authorized member.
  • For organization shares, you may only post shares as an organization for which the authorized member is an administrator. See Organization Access Control for details.

Sample Request

POST https://api.linkedin.com/v2/shares

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content"
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "owner": "urn:li:person:324_kGGaLE",
    "subject": "Test Share Subject",
    "text": {
        "text": "Test Share!"
    }
}

Request Body Fields

Field Description Format Required
owner Owner of the share URN Yes
agent Agent is the Sponsored Ad Account that created the Direct Sponsored Content Share on behalf of an organization. This permission has to be delegated. URN Only used for direct sponsored content organization share.
subject Subject of the share string Required for direct sponsored shares.
text Text of the share Share Text Required if content is empty.
content Referenced content such as articles and images Share Content Required if text is empty.
distribution Distribution target for the share Share Distribution Target Required to set the share as publicly visible. For sponsored content where the targeting is defined when it is sponsored, distribution should be null.
resharedShare Share being reshared share URN Required when resharing. Not allowed otherwise.
originalShare The original or root share of what's being reshared. Share URN Required when resharing. Not allowed otherwise.

Response

On success, the newly created share is identified in a header and the response body. See Share Response Body Fields for details on the fields that are returned in the response body.

Sample Response Header

x-linkedin-id: 6275832358189047808
x-resourceIdentity-urn: urn:li:share:6275832358189047808

Sample Response

{
    "activity": "urn:li:activity:6275832358151294976",
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "authors": [],
                        "imageSpecificContent": {},
                        "publishers": [],
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content"
    },
    "created": {
        "actor": "urn:li:person:324_kGGaLE",
        "time": 1496275033520
    },
    "distribution": {
        "linkedInDistributionTarget": {
            "visibleToGuest": false
        }
    },
    "edited": false,
    "id": "6275832358189047808",
    "lastModified": {
        "actor": "urn:li:person:324_kGGaLE",
        "time": 1496275033520
    },
    "owner": "urn:li:organization:123456789",
    "subject": "Test Share Subject",
    "text": {
        "text": "Test Share!"
    }
}

Share Response Body Fields

Field Name Type Description Guaranteed in Response?
activity Activity URN URN of the activity associated with this share. This value is not present for video shares and historic shares. No
agent URN Agent is the Sponsored Ad Account that created the Direct Sponsored Content Share on behalf of an organization. This permission has to be delegated. Returns a sponsored Account URN for Direct Sponsored Content shares. No
content Share Content Referenced content such as articles and images No
created Audit Stamp Time of creation. Yes
distribution. linkedInDistributionTarget Share Distribution Target Distribution target for the share. Yes
edited boolean A flag that indicates if this share was edited by a member. Yes
id string Unique ID for the share. Yes
lastModified Audit Stamp Time of last modification. Yes
originalShare Share URN If this share is a reshare, then this is the URN of the original/root share that was reshared. No
owner URN Owner of the share. Yes
resharedShare Share URN Share being reshared. No
subject String Share subject. Yes
text Share Text Text entered by the member for this share, which may contain annotations. Yes

Common Creation Errors

The table below lists commonly encountered errors creating Shares. It is not meant to be a comprehensive list of all possible Share creation errors.

Code Message Description
400 Request body is structured incorrectly Indicates the request payload is not correctly structured. Review the sample request for the correct structure.
400 Target audience does not meet 300 follower minimum Indicates the audience you are targeting is too small to target. Expand the audience or remove targeting.
401 Sharing entity is not authorized to perform this action 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.
422 Content is a duplicate of {share or UGC URN} Indicates the share is an exact duplicate of a recently created share. Wait 10 minutes for the duplicate restriction to expire or modify the content.
422 Error validating the share Indicates there is an error in the share, 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.

Share Comments and Likes

See /socialActions API for details on creating share likes and comments.

Update Shares

You can only update the text of a share.

Sample Request

POST https://api.linkedin.com/v2/shares/{shareURN}

{
    "patch": {
        "$set": {
            "text": {
                "annotations": [],
                "text": "Edit my share!"
            }
        }
    }
}

Delete Shares

You will need the permission w_member_social to delete shares on behalf of a member, or w_organization_social to delete shares on behalf of an organization.

Deleting a share also deletes the associated activity.

Reshares are deleted when the original share is deleted.

If a sponsored share is deleted while it's being served, the associated creative is marked as Canceled and removed.

Share deletions are idempotent. Deletion requests for a previously deleted share will return 200 OK.

Sample Request

DELETE https://api.linkedin.com/v2/shares/{share ID}

Target Organic Shares

To increase the engagement and impact of your message, you may want to target organizational shares to a subset of your followers. You can select a target audience within your 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 share must be greater than 300 members. Use the audienceCountsV2 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.

The sample request to audienceCountsV2 below shows an example of getting the audience count for all entry level individuals in the software industry in the United States.

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:123456789

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 share with these targeting details in the distribution.linkedInDistributionTarget object.

Sample Request

POST https://api.linkedin.com/v2/shares

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content !!"
    },
    "distribution": {
        "externalEntities": [],
        "linkedInDistributionTarget": {
            "industries": [
                "urn:li:industry:4"
            ],
            "geoLocations": [
                "urn:li:geo:103644278"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ]
        }
    },
    "owner": "urn:li:organization:123456789",
    "subject": "Test Share Subject !!",
    "text": {
        "text": "Test Share created by postman !!"
    }
}

Sample Response

{
    "activity": "urn:li:activity:6306957576181555200",
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "authors": [],
                        "imageSpecificContent": {},
                        "publishers": [],
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ],
                "title": "Test Share with Content !!"
            }
        ],
        "shareMediaCategory": "ARTICLE",
        "title": "Test Share with Content !!"
    },
    "created": {
        "actor": "urn:li:person:pJaBYRT-pa",
        "time": 1503695863777
    },
    "distribution": {
        "linkedInDistributionTarget": {
            "industries": [
                "urn:li:industry:4"
            ],
            "interfaceLocales": [],
            "jobFunctions": [],
            "geoLocations": [
                "urn:li:geo:103644278"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ],
            "staffCountRanges": [],
            "visibleToGuest": false
        }
    },
    "edited": false,
    "id": "6306957576219295744",
    "lastModified": {
        "actor": "urn:li:person:pJaBYRT-pa",
        "time": 1503695863777
    },
    "owner": "urn:li:organization:123456789",
    "subject": "Test Share Subject !!",
    "text": {
        "text": "Test Share created by postman !!"
    }
}

Reshare Shares

A member or organization may reshare previously shared content and include a new title and description to display in the feed. To reshare, post a new share with a POST body including a reference to the parent share using the resharedShare field, and the root share using the originalShare field.

If you know the URN of the share being reshared, you can look up the share by URN and use the same originalShare value. If the retrieved share doesn't have a value for originalShare, you can assume it is a root share and use its URN in the reshare. You need to be an administrator on the company page that contains the share you want to reshare.

Sample Request

POST https://api.linkedin.com/v2/shares

{
    "originalShare": "urn:li:share:12345",
    "resharedShare": "urn:li:share:12345",
    "text": {
        "text": "Test Reshare!"
    },
    "owner": "urn:li:organization:123456789"
}

Note the following when resharing:

  • Share content may not be specified in a reshare. You may only specify annotations and distribution targets.
  • You may only reshare a share that had share content. Attempting to reshare text-only posts results in an error.
  • Reshares do not appear on the Linkedin.com feed if the originalShare is deleted.

Share Text and Mentions

Share text may contain annotations which are mentions or tags of other Linkedin entities such as organizations or members. Specifying an annotation requires providing the URN for the referenced entity, and specifying what part of the share text should be rendered as a link to the entity.

The text linking to the annotated 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.

Annotations 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".

Organizations mentions can be type of schools (such as Universities), organization brands (previously known as Showcase Pages), and Organizations (companies.). Annotations of organizations must match the full name.

If an annotations start or length is invalid, as described below, then the creation or update of the share will be rejected with a 400 error code.

Schema

Field Description Format Required
text The content text String. Max 3000 characters. Yes
annotations Allows links to other entities such as members within share text. Array of annotations. No
annotations[i].entity The entity referred to in the share text. Must either be in the format urn:li:person:{id} or urn:li:organization:{id}. URN Yes
annotations[i].start Starting character index of where in the share text the annotation link should begin. Zero-based index. The start must be greater than or equal to zero and start + length must be less than the text length. int Yes
annotations[i].length The length of the annotation link. The length must be greater than zero and start + length must be less than the text length. int Yes

Sample Objects

Organization URN Examples
  • urn:li:organization:11832 (School - Boise State University)
  • urn:li:organization:2414183 (Organization - Devtestco)

Mention an Organization

In the following example, Devtestco is being tagged.

{
    "annotations": [
        {
            "entity": "urn:li:organization:2414183",
            "length": 9,
            "start": 6
        }
    ],
    "text": "Hello Devtestco world!"
}

Mention a School

To mention a school requires few extra steps. For example, let's assume that the school organization entity that you want to mention is Boise State University. To do this, find the school ID by making the following call:

GET https://api.linkedin.com/v2/organizations?q=vanityName&vanityName=boisestate

Sample Response

At or around line 96 in the response, you will find the key id:11832 which is the organization URN for Boise State and formatted as urn:li:organization:11832.

Boise State ID

In the following example, Boise State University is tagged.

{
    "annotations": [
        {
           "entity": "urn:li:organization:11832",
           "length": 22,
           "start": 0
       }
    ],
       "text": "Boise State University is a Carnegie doctoral research university. With more than 22,000 students, it has the largest graduate school in the state of Idaho and grants about 46 percent of all bachelor’s degrees conferred by Idaho public universities each year."
}

School Mention on Feed

Share Content

Share content represents external articles and media such as images referenced in a share. This includes rich media for images and articles from around the web.

Schema

Field Description Format Required
description Content description. This field is displayed to a small percentage of members on the mobile web version of the site. It is not displayed on the desktop site or native mobile apps. Maximum of 256 characters. String No
title Content title. Maximum of 400 characters; recommended length is <70 characters. String No
landingPageUrl The main landing page URL of the share. Maximum length of 2000 characters URL Required for carousel shares. Optional otherwise.
contentEntities Details of content being shared. Array of contentEntities. No
contentEntities[i].entity URN of the content being shared. Typical URN format is urn:li:digitalmediaAsset:C551DAQFRc4PDJV0OBg or urn:li:richMediaSummary:{id} (deprecated). URN Required for media assets. Not allowed otherwise.
contentEntities[i].entityLocation URL of the content being shared. Maximum length of 8192 characters. URL Required for sharing external articles. Not allowed otherwise.
contentEntities[i].landingPageUrl URL that overrides the landing page. Maximum length of 2000 characters. URL Required for carousel shares. Optional otherwise.
contentEntities[i].thumbnails[j] The thumbnail for the article. Only one thumbnail is used and any thumbnails beyond the first will be removed. No. Only allowed for article shares.
contentEntities[i].thumbnails[j].resolvedUrl URL to a thumbnail image to display for the content. Maximum length of 8192 characters. Maximum of 2MB thumbnail size. URL No. Only allowed for article shares.
shareMediaCategory The type of media represented by contentEntities. Must correspond to the URN types in contentEntities. Valid enums:
  • NONE - Represents shared content that does not contain any media.
  • ARTICLE - Represents shared content that only contains articles.
  • IMAGE - Represents shared content that only contains images.
  • VIDEO - Represents shared content that only contains videos. Not settable through the Shares API. Use UGC Posts
  • CAROUSEL - Represents shared content that should be rendered in carousel format.
 String Optional

Sample Object

{
    "contentEntities": [
        {
            "entity": "urn:li:article:0",
            "entityLocation": "https://www.example.com/content.html",
            "thumbnails": [
                {
                    "imageSpecificContent": {},
                    "resolvedUrl": "https://www.example.com/image.jpg"
                }
            ]
        }
    ],
    "description": "content description",
    "title": "Test Company Share with Content"
}

Using Images for Shares

LinkedIn has launched the Media Assets API to host all media types, including images and videos. Refer to the Media Assets API documentation to learn more about uploading media using the Media Assets API.

How To Use Images In Shares

Image information is part of the schema object contentEntities which includes details of the media URN.

Sample Object Including Image Assets

{
  "owner": "urn:li:organization:123456789",
  "text": {
    "text": "Test Share text"
  },
  "subject": "Test Share Subject",
  "distribution": {
    "linkedInDistributionTarget": {}
  },
  "content": {
    "contentEntities": [
      {
        "entity": "urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ"
      }
    ],
    "title": "Test Share with Content title",
    "shareMediaCategory": "IMAGE"
  }
}

Sample Object Including Externally Hosted Image

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content"
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "owner": "urn:li:organization:123456789",
    "subject": "Test Share Subject",
    "text": {
        "text": "Test Share!"
    }
}

Share Article Content - External Video Links

You can add external video links to the article content with or without captions/thumbnails, which will be rendered in the same way as the native creation (manual posts/shares). Upon successful creation, a response with 201 created will be returned.

Sample Request without Thumbnail

POST https://api.linkedin.com/v2/shares

{
"owner": "urn:li:organization:79988552",
"subject": "LMS Video Samples-1",
"content": {
"contentEntities": [
 
{ "entityLocation": "https://www.youtube.com/watch?v=FFNyvMP_ZEU" }
],
"shareMediaCategory": "ARTICLE"
},
"distribution": {
"linkedInDistributionTarget": {
}
}
}

Sample Response

{
   "owner": "urn:li:organization:79988552",
   "activity": "urn:li:activity:6969923936637632513",
   "edited": false,
   "subject": "LMS Video Samples-1",
   "created": {
       "actor": "urn:li:person:WfkarPnkTO",
       "time": 1661759361406
   },
   "lastModified": {
       "actor": "urn:li:person:WfkarPnkTO",
       "time": 1661759361406
   },
   "text": {
       "text": ""
   },
   "id": "6969923935987515392",
   "distribution": {
       "linkedInDistributionTarget": {
           "visibleToGuest": true
       }
   },
   "content": {
       "contentEntities": [
           {
               "entityLocation": "https://www.youtube.com/watch?v=FFNyvMP_ZEU"
           }
       ],
       "shareMediaCategory": "ARTICLE"
   }
}

Sample Request with Thumbnails

POST https://api.linkedin.com/v2/shares

{
"owner": "urn:li:organization:79988552",
"subject": "LMS Video Samples with recommended payload",
"content": {
"contentEntities": [{
"description": "This video briefly shows LMS.",
"entityLocation": "https://www.youtube.com/watch?v=FFNyvMP_ZEU",
"thumbnails": [{
"imageSpecificContent": {},
"resolvedUrl": "https://i.ytimg.com/vi/FFNyvMP_ZEU/maxresdefault.jpg"
}],
"title": "LinkedIn Marketing Solutions: How does it work? with recommended payload"
}],
"shareMediaCategory": "ARTICLE"
},
"distribution": {
"linkedInDistributionTarget": {
 
}
}
}

Sample Response

{
   "owner": "urn:li:organization:79988552",
   "activity": "urn:li:activity:6970253993088348160",
   "edited": false,
   "subject": "LMS Video Samples with recommended payload",
   "created": {
       "actor": "urn:li:person:WfkarPnkTO",
       "time": 1661838052975
   },
   "lastModified": {
       "actor": "urn:li:person:WfkarPnkTO",
       "time": 1661838052975
   },
   "text": {
       "text": ""
   },
   "id": "6970253992106897408",
   "distribution": {
       "linkedInDistributionTarget": {
           "visibleToGuest": true
       }
   },
   "content": {
       "contentEntities": [
           {
               "description": "This video briefly shows LMS.",
               "entityLocation": "https://www.youtube.com/watch?v=FFNyvMP_ZEU",
               "thumbnails": [
                   {
                       "imageSpecificContent": {},
                       "resolvedUrl": "https://i.ytimg.com/vi/FFNyvMP_ZEU/maxresdefault.jpg"
                   }
               ],
               "title": "LinkedIn Marketing Solutions: How does it work? with recommended payload"
           }
       ],
       "description": "This video briefly shows LMS.",
       "title": "LinkedIn Marketing Solutions: How does it work? with recommended payload",
       "shareMediaCategory": "ARTICLE"
   }
}

The post created should be displayed as follows:

share api output

Making the Most of LinkedIn Shares

The richer the content shared on LinkedIn, the more members will engage with the content. The Share API allows your app to have full control over how the share is displayed on LinkedIn. To maximize engagement, include as much metadata as possible within the contentEntities field (description, title, thumbnail URL, and entity location URL).

Sample Object

{
    "contentEntities": [
        {
            "entityLocation": "https://developer.linkedin.com/documents/share-api",
            "thumbnails": [
                {
                    "imageSpecificContent": {},
                    "resolvedUrl": "https://m3.licdn.com/media/p/3/000/124/1a6/089a29a.png"
                }
            ]
        }
    ],
    "description": "https://developer.linkedin.com/documents/share-api",
    "title": "LinkedIn Developers Documentation On Using the Share API"
}

Fetch Share Content For Article Shares

Make the most of LinkedIn Article Shares by providing metadata for your article share by setting the description, title, and thumbnail URL fields. If your application does not provide any of the metadata, LinkedIn attempts to fetch the missing content using URL Preview of the URL. This functionality is best effort and if the field is not present in the URL Preview then it will not be set. If a specific representation of the post is desired, then it is recommended that partners set the description, title, and/or thumbnail fields rather than rely on this functionality.

See Controlling How Share Content is Displayed for Article Shares for details on how share content is populated from the referenced URL for article shares.

Share Distribution Targets

Share distribution targets specify a share's audience and reach. For example, a share may be limited to only connections of the owner in specific locations.

Schema

Field Description Format Required
linkedinDistributionTarget.connectionsOnly Restrict share to member's connections only. Not applicable to organization shares. boolean No
linkedinDistributionTarget.industries Restrict share to specific industries. Not applicable to member shares. array of Industry URN No
linkedinDistributionTarget.interfaceLocales Restrict share to specific user locales. Not applicable to member shares. array of Locale No
linkedinDistributionTarget.jobFunctions Restrict share to specific functions. Not applicable to member shares. array of Function URN No
linkedinDistributionTarget.locations Deprecated. Please use 'geoLocations' instead. Restrict share to specific locations. Not applicable to member shares. array of Location URN Supported URN types: countryGroup, country, state, and region. No
linkedinDistributionTarget.geoLocations Restrict share to specific geoLocations. Not applicable to member shares. array of Geo URN. Learn more No
linkedinDistributionTarget.seniorities Restrict share to specific seniorities. Not applicable to member shares. array of Seniority URN No
linkedinDistributionTarget.staffCountRanges Restrict share to members working at organizations of specific sizes. Not applicable to member shares. array of StaffCountRange* No
linkedinDistributionTarget.visibleToGuest Make share visible to everyone, even guests on LinkedIn. boolean, default="true" No

Note

Due to change in the UI experience, the visibleToGuest field is now always set to true for all shares. We recommend using the connectionsOnly field to control visibility of personal shares and using targeting facets to control visibility of organization shares. For backwards compatibility, starting January 2019, setting visibleToGuest to false on personal shares will result in setting connectionsOnly to true.

The StaffCountRange represents the number of staff employed by an organization. It must be one of the following 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

Sample Object

{
    "linkedInDistributionTarget": {
        "industries": [
            "urn:li:industry:12",
            "urn:li:industry:37"
        ],
        "seniorities": [
            "urn:li:seniority:4",
            "urn:li:seniority:8"
        ]
    }
}

Note

Omitting distribution.linkedInDistributionTarget during share creation creates a dark or hidden share which is not shown publicly on LinkedIn.com. Specify the field as an empty object to make the share publicly viewable.

Controlling How Share Content is Displayed for Article Shares

If you're unable to provide the metadata for an article share (description, title, and thumbnail URL), LinkedIn attempts to fetch the content directly from the page. Post Inspector is a tool that is available to determine what the content looks like for a specific page. The tool provides guidance on how the value for each property was chosen and how to set them if you have control over the page. This is summarized below for the relevant fields for article shares.

Tag Description
og:title Set the title tag section to control how your web page's title displays on LinkedIn.
og:description Set the description tag to control how the shared link is described on LinkedIn.
og:image Set the image tag to control which image is displayed on LinkedIn.

Even if the Open Graph tags within the page that's being shared are not set, LinkedIn will attempt to determine the title, description, thumbnail image, etc.

Direct Sponsored Content Share

To create a direct sponsored content share, reference the agent field with your sponsoredAccount URN. This is only valid with an organization share.

Sample Request

POST https://api.linkedin.com/v2/shares

{
    "agent": "urn:li:sponsoredAccount:123456789",
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share for Sponsored Content"
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "owner": "urn:li:organization:123456789",
    "subject": "Test Share Subject",
    "text": {
        "text": "Test Share!"
    }
}

Archive Direct Sponsored Content

You may discover that you posted too many Direct Sponsored Content (DSC) instances, creating clutter on your site. LinkedIn enables you to remove existing DSC instances to manage your posted content more effectively by updating your DSC instances, using a POST request.

POST https://api.linkedin.com/v2/adDirectSponsoredContents/urn:li:share:12345

{
    "patch": {
        "$set": {
            "status": "ARCHIVED"
        }
    }
}

A successful response returns a 204 No Content status.

Migrate from Update Keys to Share URNs

Update keys that were previously used to uniquely identify shares can be converted into shares URN using the activities API. Update keys are formatted as follows:

UPDATE-c{entityid}-{activityid}

An example of an update key:

UPDATE-c6177438-6252923622642540544

To transform the activityid into a share URN, prepend urn:li:activity to activityid and retrieve activities as shown in the following section.

Retrieve Activities and Their Shares

The Activities API allows you to pass in one or more activity URNs to get the associated share URNs stored in the domainEntity field. Use it only for updates of type SHAR.

Sample Request

GET https://api.linkedin.com/v2/activities?ids=urn:li:activity:6252923622642540544

Sample Response

{
    "errors": {},
    "results": {
        "urn:li:activity:6252923622642540544": {
            "domainEntity": "urn:li:share:6252923622768377856"
        }
    },
    "statuses": {}
}

To convert multiple activity IDs into share URNs, pass multiple ids parameters.

The maximum number of ids you can pass is dependent on the URL length. We allow a maximum of 2,000 characters per request.

Sample Request

GET https://api.linkedin.com/v2/activities?ids=urn:li:activity:6252923622642540544&ids=urn:li:activity:5895320715594330112

Sample Response

{
    "errors": {},
    "results": {
        "urn:li:activity:5895320715594330112": {
            "domainEntity": "urn:li:share:6018535483385077760"
        },
        "urn:li:activity:6252923622642540544": {
            "domainEntity": "urn:li:share:6252923622768377856"
        }
    },
    "statuses": {}
}

The most efficient way to get more information on the returned share URNs is to use decoration on the domainEntity field. This will return the share's data without having to make an additional call to the Shares API.

Sample Request

GET https://api.linkedin.com/v2/activities?ids=urn:li:activity:6252923622642540544&projection=(results(*(domainEntity~)))

Sample Response

{
    "results": {
        "urn:li:activity:6252923622642540544": {
            "domainEntity~": {
                "owner": "urn:li:organization:123456789",
                "activity": "urn:li:activity:6252923622642540544",
                "edited": false,
                "created": {
                    "actor": "urn:li:person:4Hhl5NW9LX",
                    "time": 1490813165000
                },
                "id": "6252923622768377856",
                "lastModified": {
                    "actor": "urn:li:person:4Hhl5NW9LX",
                    "time": 1490813166000
                },
                "text": {
                    "text": "Testing a full university share!"
                },
                "distribution": {
                    "linkedInDistributionTarget": {
                        "visibleToGuest": true
                    }
                }
            },
            "domainEntity": "urn:li:share:6252923622768377856"
        }
    }
}