Share API

Introduction

Network updates serve as one of the core experiences on LinkedIn, giving users the ability to share rich content to their professional network. Through the Share API, you can enable users take full advantage of this functionality within your application. 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

We suggest providing as much content as possible to your share. This ensures the better engagement of the shared content on LinkedIn. Details on how to maximize the completeness of your share are described later in this document.

Usage

You must use an access token to make an authenticated call on behalf of a user

Permissions
This API requires the following permission (see Member Permissions)

Permission Description
rw_nus Required to retrieve and post updates to LinkedIn as authenticated user

Throttle Limits
Please reference the limits applied to this API

Posting Shares

As with any API that allows you to post on behalf of a member, always ensure that the user is fully aware that your application is sharing content on their behalf. Simply make a POST call passing the share content to the following endpoint: URL

Share Input Fields

Node Parent Node Value Notes
share Yes Child nodes of share Parent node for all share content
comment share Text of member's comment. (Similar to deprecated current-status field.) Post must contain comment and/or (content/title and content/submitted-url). Max length is 700 characters (bytes).
content share Parent node for information on shared document  
title share/content Title of shared document Post must contain comment and/or (content/title and content/submitted-url). Max length is 200 characters (bytes).
submitted-url share/content URL for shared content Post must contain comment and/or (content/title and content/submitted-url).
submitted-image-url share/content URL for image of shared content Invalid without (content/title and content/submitted-url).
description share/content Description of shared content Max length of 256 characters (bytes).
visibility share Parent node for visibility information  
code share/visibility One of anyone: all members or connections-only: connections only.  

Sample Request

<share>
  <comment>Check out the LinkedIn Share API!</comment>
  <content>
    <title>LinkedIn Developers Documentation On Using the Share API</title>
    <description>Leverage the Share API to maximize engagement on user-generated content on LinkedIn</description>
    <submitted-url>https://developer.linkedin.com/documents/share-api</submitted-url>
    <submitted-image-url>https://m3.licdn.com/media/p/3/000/124/1a6/089a29a.png</submitted-image-url> 
  </content>
  <visibility> 
    <code>anyone</code> 
  </visibility>
</share>
puts "\nAdd Share" 

# Create new share, passing the Share XML input into the header 
response = @access_token.post("https://api.linkedin.com/v1/people/~/shares" 
                                  , share_xml 
                                  , {'Content-Type'=>'application/xml'}) 

# Put body of response 
puts response.body

Response
Returns 201 Created on success. Upon success, the body of the response will contain the following:

1
2
3
4
<update>
  <update-key>UNIU-8219502-5705061301949063168-SHARE</update-key>
  <update-url>https://www.linkedin.com/updates?discuss=&amp;scope=8219502&amp;stype=M&amp;topic=5705061301949063168&amp;type=U&amp;a=aovi</update-url>
</update>

You can use the update key to request the XML or JSON representation of the newly created share. This can be achieved by making a GET call to https://www.linkedin.com/v1/people/~/network/updates/key={update_key} (setting {update_key} to the value you received in the previous response)

Alternatively, you can choose to to use the update url to redirect the user to the newly created share. This URL serves as a direct link to the posted share on LinkedIn.com so they can view the share in the browser.

Making the most of LinkedIn Shares

The richer the content shared on LinkedIn, the more engagement it will create among members. This also allows your application to have full control over how the share is displayed on LinkedIn. Complete shares use the 'Content' element to fill all the metadeta related to the share being posted (title, thumbnail url, submitted url, description). For example:

Sample Request

<?xml version="1.0" encoding="UTF-8"?> 
<share>  
  <comment>Check out the LinkedIn Share API!</comment>  
  <content> 
     <title>LinkedIn Developers Documentation On Using the Share API</title>  
    <description>Leverage the Share API to maximize engagement on user-generated content on LinkedIn</description> 
    <submitted-url>https://developer.linkedin.com/documents/share-api</submitted-url> 
    <submitted-image-url>https://m3.licdn.com/media/p/3/000/124/1a6/089a29a.png</submitted-image-url> 
  </content> 
  <visibility> 
    <code>anyone</code> 
  </visibility>  
</share>
The successfully shared content:

Fetching Content for Shares

Providing all metadata for your share (title, description, submitted url, etc) gives your application full control over how the share is previewed on the LinkedIn network updates stream. If your application can't provide all the metadata, LinkedIn will attempt to fetch the missing content for you. For example, let's say your share only consists of a 'Comment' and 'Submitted URL':
<?xml version="1.0" encoding="UTF-8"?> 
<share> 
  <comment>Check out the LinkedIn Share API! https://example.com</comment> 
  <content> 
    <submitted-url>https://developer.linkedin.com/documents/share-api</submitted-url> 
  </content> 
  <visibility> 
    <code>anyone</code> 
  </visibility> 
</share>
LinkedIn will take the Submitted URL in the comment field and fetch the content directly from the link (title, description, thumbnail url, submitted url)
 

Alternatively, if you only provide a link in the 'Comment' field:

<?xml version="1.0" encoding="UTF-8"?>
<share>
  <comment>Check out the LinkedIn Share API! https://bit.ly/wf5Mpd</comment>
  <visibility>
	 <code>anyone</code>
  </visibility>
</share>

LinkedIn will fetch the content (title, description, thumbnail url, submitted url) from the first URL in the 'Comment' field

The successfully shared content:

 

In the example share above, the content of the share preview was fetched directly from the URL in the 'Comment' field since the metadata wasn't explicitly provided in the share.

Controlling How Shares Are Displayed

In cases where you're unable to provide a complete share with all metadata, LinkedIn will fetch the content directly from the page. To best facilitate this, you should set Open Graph tags (https://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 LinkedIn Today requires images to be at least 80 x 150 pixels. If your images does not meet this minimum size, LinkedIn picks an appropriate image of the correct size. The image rules are:
if (og:image width > 150 && og:image height > 80) use it
else linkedin picks image

Note: Facebook also uses Open Graph tags, but does not require og:image sizes as large as LinkedIn. If you use the image size required by LinkedIn, the image is scaled down to work for Facebook.

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 will attempt to fetch the content automatically by determining the title, description, thumbnail image, etc.

Attribution

If your application has generated content that's been shared, giving attribution offers users discoverability and awareness of your app within the network updates stream on LinkedIn.

Currently, the attribution program is in beta. Applications must meet the following requirements to be considered for the program. Final approval is subject to LinkedIn:

  • Your application has a minimum of 1,000,000 users
  • Your application gives users the option to Sign in with LinkedIn or bind their LinkedIn account
  • Your application does at least 1 of the following 3 things:
    • Allows users to create diverse and high quality content
    • Allows users to share high quality content
    • Allows users to post high quality status updates or comments

If you're interested to include attribution in your application, we encourage you to apply to our Partners Program