Share API

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 resharing 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/li>
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 permission is granted to select developers only.

If you are using legacy permissions, please refer to this page for requesting legacy permissions.

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 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.
serviceProvider String Optional. Deprecated This field will be removed on January 10, 2020. Name of service provider from which the share creation was requested. Can be the following enum values:
  • LINKEDIN - The share originated from the LinkedIn web app.
  • INSHARE - The share originated from the inShare button.
  • SLIDESHARE - The share originated from the Slideshare mobile/web app.
  • PULSE - The share originated from the Pulse mobile/web app.
  • FLAGSHIP - The share originated from the LinkedIn Flagship mobile app.
  • LSS - The share originated from the LSS mobile/web app.
  • ELEVATE - The share originated from the Elevate mobile/web app.
  • FIREFOX_ACTIVATION - The share originated from the Firefox Activation extension.
  • API - The share originated from an externalized API.
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}&sharesPerOwner=100

Shares are ordered by creation time with the most recent share being the first.

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.

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:1000",
    "text": {
        "text": "Test Share!"
    }
}

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"
                     },
                     { 
                        "imageSpecificContent":{ 
                           "size":58808,
                           "width":800,
                           "height":450
                        },
                        "resolvedUrl":"https://i.kinja-img.com/gawker-media/image/upload/s--q9NM_U64--/c_scale,f_auto,fl_progressive,q_80,w_800/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. If you are using legacy permissions, please refer to this page for requesting legacy permissions.

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:2414183",
    "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.

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. If you are using legacy permissions, please refer to this page for requesting legacy permissions.

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 company 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:country:us&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 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"
            ],
            "locations": [
                "urn:li:country:us"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ]
        }
    },
    "owner": "urn:li:organization:2414183",
    "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": [],
            "locations": [
                "urn:li:country:us"
            ],
            "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:2414183",
    "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.

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:2414183"
}

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

Annotations of organizations must match the full name.

Schema

Field Description Format Required
text The content text String. Max 1300 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:company:{id}. URN Yes
annotations[i].start Starting character index of where in the share text the annotation link should begin. Zero-based index. int Yes
annotations[i].length The length of the annotation link. int Yes

Sample Object

In the following example, LinkedIn is being tagged.

{
    "annotations": [
        {
            "entity": "urn:li:organization:1337",
            "length": 8,
            "start": 6
        }
    ],
    "text": "Hello LinkedIn world!"
}

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
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 rich media shares and media assets. Not allowed otherwise.
contentEntities[i]. entityLocation URL of the content being shared. URL Required for sharing external articles. Not allowed otherwise.
contentEntities[i]. thumbnails[j].resolvedUrl URL to a thumbnail image to display for the content. 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.
  • RICH - Represents shared content that only contains rich media .
  • VIDEO - Represents shared content that only contains videos.
  • 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. The Rich Media Platform currently used to upload images and create rich media shares has been marked for deprecation by January 30, 2020. 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:company:5597072",
  "text": {
    "text": "Test Share text"
  },
  "subject": "Test Share Subject",
  "distribution": {
    "linkedInDistributionTarget": {}
  },
  "content": {
    "contentEntities": [
      {
        "entity": "urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ"
      }
    ],
    "title": "Test Share with Content title",
    "landingPageUrl": "https://www.linkedin.com/",
    "shareMediaCategory": "IMAGE"
  }
}

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 (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"
                }
            ]
        }
    ],
    "title": "LinkedIn Developers Documentation On Using the Share API"
}

Fetch Share Content

Make the most of LinkedIn Shares by providing all metadata for your share (title, entity location, etc.). If your application can't provide all the metadata, LinkedIn attempts to fetch the missing content for you.

LinkedIn fetches share content when entityLocation is not specified, and share text contains a URL. See Controlling How Share Content is Displayed for details on how share content is populated from the referenced URL.

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 Restrict share to specific locations. Not applicable to member shares. array of Location URN Supported URN types: countryGroup, country, state, and region. 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

If you're unable to provide a complete share with all metadata, LinkedIn fetches the content directly from the page. To best facilitate this, set [Open Graph tags][http://ogp.me/] if you have control over the published content that's being shared.

Tag Description
og:title Set the title tag 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.
og:url The URL tag is recommended to provide the best URL link for LinkedIn to use to point to your web page.

If you're unable to set Open Graph tags within the page that's being shared, LinkedIn attempts to fetch the content automatically by determining 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:12345",
    "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:6177438",
                "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"
        }
    }
}