Rich Media Shares

The Rich Media Share API provides the ability to upload images to reference in a personal or organization share. This API lets user create rich and engaging personal or organization shares to be surfaced on various feeds within the LinkedIn ecosystem. 

Creating a rich media share is done in two steps. First, the media is uploaded to LinkedIn's media platform. Then, a personal or organization share referencing that media is created.

After creation, the share may be accessed as outlined in the Retrieving Shares Guide.

Permissions

Permission Description
mgw_w_media Required to upload media
w_share Required to create a personal share
rw_organization Required to create a company share

Upload Rich Media

To upload rich media, attach the media as multipart/form-data. Media formats supported are: jpeg, png. Other media formats are not currently accepted. The media file size should be under 10MB for all file types, all image files have a pixel restriction of 40,000,000, and you may only upload one media object per API call.

All calls to upload rich media must use OAuth 2.0 authentication. Please note that the path to this endpoint is not api.linkedin.com/v1/, but instead api.linkedin.com/media/.

Sample Request

The following sample requests sends sample_image.png to the rich media server:

POST
https://api.linkedin.com/media/upload

Note: The path to this endpoint is not api.linkedin.com/v2/, but instead api.linkedin.com/media/.

Sample Curl request
curl --form "fileupload=@[Path to File]" -H "Authorization: Bearer <access token>" https://api.linkedin.com/media/upload
Sample response
{
  "location": "urn:li:richMediaSummary:PNG-IMG-54f022ae8b3f4d479e925b4df68e19"
}

Upon success, you should receive a rich media URN which uniquely identifies the newly uploaded media. The media will not be displayed on LinkedIn.com until you create a share which references this uploaded media.

Get Rich Media Summary

When you upload an image to LinkedIn, you receive a media urn associated with that image. You can preview the image in your client by using the various URLs provided by the rich media summary.

Each URL is for a different image size. We shrink image to fit the aspect ratio such that width and height do not exceed the values below.

Image Size Width Height
Small 160 px -
Medium 543 px 410 px
Large 1024 px 1024 px

Today, you must parse the url value to check if it ends with -small., -medium., or -large. to determine the size.

GET
https://api.linkedin.com/v2/richMediaSummariesV2/JPEG-IMG-69ef4c1d2ee346a184a665e9595e2f92
Sample Response Body
{
    "id": "JPEG-IMG-69ef4c1d2ee346a184a665e9595e2f92",
    "thumbnails": [
        {
            "mediaType": "image/jpeg",
            "url": "http://image-store.slidesharecdn.com/69ef4c1d-2ee3-46a1-84a6-65e9595e2f92-small.jpeg"
        },
        {
            "mediaType": "image/jpeg",
            "url": "http://image-store.slidesharecdn.com/69ef4c1d-2ee3-46a1-84a6-65e9595e2f92-medium.jpeg"
        },
        {
            "mediaType": "image/jpeg",
            "url": "http://image-store.slidesharecdn.com/69ef4c1d-2ee3-46a1-84a6-65e9595e2f92-large.jpeg"
        }
    ]
}

Batch Get Rich Media Summary

Batch Get
https://api.linkedin.com/v2/richMediaSummariesV2?ids=JPEG-IMG-d1bf4938b968460585c38b615ed5d039&ids=PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ced9&ids=PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ce11
Sample json response
{
    "statuses": {},
    "results": {
        "PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ce11": {
            "id": "PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ce11",
            "thumbnails": [
                {
                    "mediaType": "image/png",
                    "url": "http://image-store.slidesharecdn.com/1b0e1c93-aa0a-441b-bcab-d3ce7986ce11-small.png"
                },
                {
                    "mediaType": "image/png",
                    "url": "http://image-store.slidesharecdn.com/1b0e1c93-aa0a-441b-bcab-d3ce7986ce11-medium.png"
                },
                {
                    "mediaType": "image/png",
                    "url": "http://image-store.slidesharecdn.com/1b0e1c93-aa0a-441b-bcab-d3ce7986ce11-large.png"
                }
            ]
        },
        "JPEG-IMG-d1bf4938b968460585c38b615ed5d039": {
            "id": "JPEG-IMG-d1bf4938b968460585c38b615ed5d039",
            "thumbnails": [
                {
                    "mediaType": "image/jpeg",
                    "url": "http://image-store.slidesharecdn.com/d1bf4938-b968-4605-85c3-8b615ed5d039-small.jpeg"
                },
                {
                    "mediaType": "image/jpeg",
                    "url": "http://image-store.slidesharecdn.com/d1bf4938-b968-4605-85c3-8b615ed5d039-medium.jpeg"
                },
                {
                    "mediaType": "image/jpeg",
                    "url": "http://image-store.slidesharecdn.com/d1bf4938-b968-4605-85c3-8b615ed5d039-large.jpeg"
                }
            ]
        },
        "PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ced9": {
            "id": "PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ced9",
            "thumbnails": [
                {
                    "mediaType": "image/png",
                    "url": "http://image-store.slidesharecdn.com/1b0e1c93-aa0a-441b-bcab-d3ce7986ced9-small.png"
                },
                {
                    "mediaType": "image/png",
                    "url": "http://image-store.slidesharecdn.com/1b0e1c93-aa0a-441b-bcab-d3ce7986ced9-medium.png"
                },
                {
                    "mediaType": "image/png",
                    "url": "http://image-store.slidesharecdn.com/1b0e1c93-aa0a-441b-bcab-d3ce7986ced9-large.png"
                }
            ]
        }
    },
    "errors": {}
}

Post Rich Media Shares

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

When sharing an image, even though the fields title and description are accepted in the API call, it will be omitted from the post on LinkedIn.  The title field must be included for the share to be displayed.

You should reference the Post Shares Guide for more details on creating shares.

Note: Rich media is deleted when a member deletes all shares referencing the media. Attempting to post a share referencing deleted media will result in an error.

Sample Request

The following request posts a share that includes rich media:

POST
https://api.linkedin.com/v2/shares
sample request body
{
  "text": {
    "text": "Test Share!"
  },
  "subject": "Test Share Subject",
  "distribution": {
    "linkedInDistributionTarget": {}
  },
  "content": {
    "contentEntities": [
      {
        "entity": "urn:li:richMediaSummary:PNG-IMG-54f022ae879e925b4df68e19"
      }
    ],
    "description": "content description",
    "title": "Test Share with Content"
  }
}

Sponsor Rich Media Shares

There is no difference when sponsoring a rich media share vs. a regular organization share.

Optimize Rich Media Shares for Mobile

We recommend to upload rich media in 1200x627 aspect ratio. Images uploaded in the recommended 1200x627 ratio will automatically display on the new mobile app with white padding on the top/bottom or sides of the image, which will allow them to fit the ratio without cropping. A 3:2 aspect ratio, or 1200x800, will display fully without such padding. However, we recommend using 1200x627 because it is an industry-standard size. Link share thumbnail image uploads will still display in a 2:1 ratio. Please limit text in rich media images to the center of the image in a title-safe area, as described below:

  • rms-recommend-mobile

Introduction Text will now be truncated to show “... see more” at around 128-130 characters depending on the mobile device size. Title Text will still truncate at around 38-46 characters depending on the mobile device size.

Post Carousel Shares using Rich Media

The process of creating a carousel share is similar to creating a rich media share. The main differences are:

  • shareMediaCategory of the share content should be set to "CAROUSEL"
  • Each content entity in the content.contentEntities array represents an individual card of the Carousel share.
  • The Rich Media URNs for each card image should be set in the content.contentEntities.entityLocation field. For best results, the image used must conform to the image specifications defined below.
  • When creating a carousel share, you must specify the landingPageUrl for the share, as well as the landingPageUrl for each card in the content.contentEntities.landingPageUrl field. You can use the same URL for all cards or use different URLs. 
  • You can also optionally add a descriptive title for each card in the content.contentEntities.title field.

Please refer to the Share and Share Content schema for more details.

Image Specifications

  • The recommended size for card images is 1080 x 1080
  • Images not conforming to spec may still run with gray letterboxing around them. This can create a less optimal member experience and impact performance.
  • You must provide between 2 to 10 images

Access Requirements

  • Authenticated user must be the Company Page Admin or Sponsored Content Poster with user access to the Campaign Manager

Sample Request

POST
https://api.linkedin.com/v2/shares
sample request body
{  
   "owner":"urn:li:company:1234",
   "text":{  
      "text":"Test Carousel Share!"
   },
   "subject":"Carousel Test through API",
   "distribution":{  
      "linkedInDistributionTarget":{  
      }
   },
   "content":{  
      "contentEntities":[  
         {  
            "entity":"urn:li:richMediaSummary:PNG-IMG-e0ebe04da30e49e7930943d7683a41c4",
            "landingPageUrl":"https://www.example.com/product1",
            "title":"ABC"
         },
         {  
            "entity":"urn:li:richMediaSummary:PNG-IMG-48120a7db96b421c8ef47dfa82f243c8",
            "landingPageUrl":"https://www.example.com/product2",
            "title":"XYZ"
         },
         {  
            "entity":"urn:li:richMediaSummary:PNG-IMG-8cfeeb67c1af444cb33950449cbf166c",
            "landingPageUrl":"https://www.example.com/product3",
            "title":"DEF"
         }
      ],
      "shareMediaCategory":"CAROUSEL",
      "landingPageUrl":"https://www.example.com"
   }
}

Sponsor Carousel Shares

You can sponsor a Carousel Share by setting the agent field to the sponsoring ad account URN.

Additional Access Requirements

  • The authenticated user must have a role higher than “Viewer” for the Ad Account to create DSC

Sample Request

POST
https://api.linkedin.com/v2/shares
sample request body
{  
   "owner":"urn:li:company:1234",
   "agent":"urn:li:sponsoredAccount:2342",
   "text":{  
      "text":"Test Carousel Share!"
   },
   "subject":"Carousel Ads Test through API",
   "distribution":{  
      "linkedInDistributionTarget":{  
      }
   },
   "content":{  
      "contentEntities":[  
         {  
            "entity":"urn:li:richMediaSummary:PNG-IMG-e0ebe04da30e49e7930943d7683a41c4",
            "landingPageUrl":"https://www.example.com/product1",
            "title":"ABC"
         },
         {  
            "entity":"urn:li:richMediaSummary:PNG-IMG-48120a7db96b421c8ef47dfa82f243c8",
            "landingPageUrl":"https://www.example.com/product2",
            "title":"XYZ"
         },
         {  
            "entity":"urn:li:richMediaSummary:PNG-IMG-8cfeeb67c1af444cb33950449cbf166c",
            "landingPageUrl":"https://www.example.com/product3",
            "title":"DEF"
         }
      ],
      "shareMediaCategory":"CAROUSEL",
      "landingPageUrl":"https://www.example.com"
   }
}