Shares & Social Streams Getting Started

  • Article
  • 8 minutes to read

Warning

Deprecation Notice
The unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

LinkedIn offers posts, ugcPosts (Legacy) and shares (Legacy) APIs for sharing media and content on LinkedIn's network. These APIs allow reading and writing of company page posts on behalf of members authorized to manage a company page. This functionality is available to developers approved for the LinkedIn LinkedIn Marketing API Program.

Use this guide for a quick look at some of the core functions of these APIs.

Permissions

The endpoints mentioned in this guide require your application to request 3 permissions. Refer to the table below to understand the mapping between permissions and the endpoints presented in this guide.

Permission Description Endpoints
w_organization_social Perform write actions on behalf of an organization.
  • ugcPosts
  • shares
  • socialActions
r_organization_social Read access for organization shares.
  • ugcPosts
  • shares
  • socialActions
w_member_social Perform write actions on behalf of an authenticated member.
  • ugcPosts
  • shares
  • socialActions
rw_ads Read and write access to ads.
  • adCreativesV2

Share Types

LinkedIn currently offers posts, ugcPosts (Legacy) and shares (Legacy) APIs for sharing content. Posts API is LinkedIn's next generation of share experience encompassing text posts, image posts, video posts, share posts, poll posts, multiImage posts and more. posts API will eventually replace the ugcPosts and shares APIs.

Posts

Use posts to create and fetch various types of organic (non-sponsored) and sponsored posts. For more info, please check the Posts API.

UGC Posts (Legacy)

Use ugcPosts to create and fetch video content for organic posts and video ads for an organization. Video shares return a ugcPost URN. Please check the Posts API which will replace UGC Posts API for more updates.

Shares (Legacy)

Use the shares API to share text posts, articles, and images. Please check the Posts API which will replace Shares API for more updates.

Creating Basic Content

Please refer to the Posts API for the latest information about post content handling. Below (using shares API) shows legacy ways of post content handling.

Text Share (Legacy)

Your application may post shares in the context of an organization. Use a URN in the owner field to associate the share with an organization. The valid URN format is urn:li:organization:{id}.

Sample Request

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

{
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "owner": "urn:li:organization:33218132",
    "subject": "Test text only",
    "text": {
        "text": "Test text only"
      }
}

The response header x-restli-id contains the created share's ID.

Article Share (Legacy)

LinkedIn allows posting of articles to an organization's feed. These external articles can be referenced in a share. entityLocation represents the URL of the content being shared.

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!"
    }
}

The response header x-restli-id contains the created share's ID.

Mentioning Members or Organizations (Legacy)

Share text can mention and link to other LinkedIn entities through annotations. To specify an annotation, you must know the URN for the referenced entity and declare what part of the share text should be rendered as a link to the entity. Provide the starting zero-based index and the character length of the entity's name mentioned in the share text to annotate it.

Sample Request

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

{
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "owner": "urn:li:organization:33218132",
    "subject": "Test annotation",
    "text": {
        "annotations": [
            {
                "entity": "urn:li:organization:0000",
                "length": 8,
                "start": 6
            }
        ],
        "text": "Hello LinkedIn world!"
    }
}

For more information on creating content, see Shares.

Retrieving Content

Retrieving a Share (Legacy)

To retrieve a single share, look up the share by share ID.

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

Sample Response

{
    "owner": "urn:li:organization:33218132",
    "activity": "urn:li:activity:6500807011058405376",
    "edited": false,
    "created": {
        "actor": "urn:li:person:frTwuLigyP",
        "time": 1549913170500
    },
    "clientApp": "urn:li:developerApplication:6590014",
    "serviceProvider": "API",
    "id": "6500807010664136704",
    "lastModified": {
        "actor": "urn:li:csUser:0",
        "time": 1549913307853
    },
    "text": {
        "text": "Test text"
    },
    "distribution": {
        "linkedInDistributionTarget": {
            "visibleToGuest": true
        }
    }
}

For more information on retrieving content, see the Posts API (recommended).

Social Actions

The socialActions API allows you to create and read likes and comments on shares.

Create a Like on a Share

Use the object field in the request body to specify the URN of the entity that is being liked. This could be a share or comment.

The actor field in the request body is used to specify the entity performing the like. It should be represented by a urn:li:person:{id} or urn:li:organization:{id} URN.

Sample Request

POST https://api.linkedin.com/v2/socialActions/{shareUrn|ugcPostUrn|commentUrn}/likes

{
    "actor": "urn:li:person:0XV6h162Ub",
    "object": "urn:li:share:6280442346811207680"
}

Retrieve a Summary of Social Actions

GET https://api.linkedin.com/v2/socialActions/{shareUrn|ugcPostUrn|commentUrn}

Sample Response

{
    "commentsSummary": {
        "totalFirstLevelComments": 4,
        "aggregatedTotalComments": 9
    },
    "$URN": "urn:li:activity:6296748651834277888",
    "likesSummary": {
        "likedByCurrentUser": false,
        "totalLikes": 226
    }
}

Note

Shares without likes or comments do not show likesSummary or commentsSummary respectively. A share without social action activity returns an empty JSON response.

For more information on creating, retrieving, and managing social actions, see Network Update Social Actions.

Creating Content with Media

Image

The Rich Media Share API allows you to upload images to reference in a share. You must be a company administrator to create an organization share.

To create a rich media share:

  1. Upload the media to LinkedIn's media platform.
  2. Make a share referencing that media.

See Media upload for how to upload images to LinkedIn.

Sharing rich media is very similar to creating shares. The main difference is how the share content is constructed. The only required values to be passed in are entity and title. The value of entity is the URN that was created when uploading the media.

Sample Request

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

{
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:richMediaSummary:PNG-IMG-54f022ae879e925b4df68e19"
            }
        ],
        "description": "content description",
        "title": "Test Share with Content"
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "subject": "Test Share Subject",
    "text": {
        "text": "Test Share!"
    }
}

For more information, see Media Upload.

Video

Creating a video post requires using the ugcPosts API. The shares API does not support video.

Create an Organic UGC Post

Sample Request

Make sure to set the Content-Type header to application/json.

If you plan to sponsor this post later, make sure you set shareContent.ShareMedia.landingPage and shareContent.ShareMedia.title when you create the post.

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

{
    "author": "urn:li:organization:5590506",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "description": {
                        "attributes": [],
                        "text": "Sample Description"
                    },
                    "media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
                    "status": "READY",
                    "thumbnails": [],
                    "title": {
                        "attributes": [],
                        "text": "Sample Video Create"
                    }
                }
            ],
            "shareCommentary": {
                "attributes": [],
                "text": "Some share text"
            },
            "shareMediaCategory": "VIDEO"
        }
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

The UGC Post is created with a 201 Created response and the response header x-restli-id contains the ugcPost ID.

For more information, see UGC Post.

Target Shares

To share organizational shares to a target audience, specify share distribution targets when posting a share. Share distribution targets represent the categories by which the audience is segmented. See Ads Targeting to create a segment of a specific audience you may want to target.

You must have a minimum of 300 members as the target audience for your share. Use the audienceCountsV2 API first to calculate the approximate size of your audience.

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 !!"
    }
}

For more information, see Targeting Organic Shares.

Organic shares can be sponsored to reach members who are not following your company's page. This requires having an ad account and campaign to manage your sponsored content ad. See the Ads Getting Started Guide to create those.

Assuming you have an ad account and campaign, you may begin sponsoring shares by creating an ad creative of type SPONSORED_STATUS_UPDATE. The share to be sponsored should be provided in the reference field of the creation payload.

Sample Request

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

{
    "campaign": "urn:li:sponsoredCampaign:10879951",
    "reference": "urn:li:share:1234567890",
    "status": "ACTIVE",
    "type": "SPONSORED_STATUS_UPDATE",
    "variables": {
        "data": {
            "com.linkedin.ads.SponsoredUpdateCreativeVariables": {}
        }
    }
}

The response header x-restli-id contains the ad creative's ID.

For more information on creating sponsored content shares and other ad creative types, see Create and Manage Creatives.