Rich Media Shares

The Rich Media Share API allows you to upload images to reference in a personal or organization share. With this API, you can create rich and engaging personal or organization shares that appear on various feeds within the LinkedIn ecosystem. 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 personal or organization share referencing that media.

After you create a rich media share, see Retrieve Shares for steps to access it.

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>
w_member_social Post, comment and like posts on behalf of an authenticated member.

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.

Upload Rich Media

To upload rich media, attach the media as multipart/form-data. Currently, only jpeg and png formats are supported. The media file size should be under 10 MB 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.

Sample Request

The following example sends sample_image.png to the rich media server.

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

Sample curl Request

curl --form "fileupload=@sample_image.png" -H "Authorization: Bearer <access token>" https://api.linkedin.com/media/upload

Sample Response

{
    "location": "urn:li:richMediaSummary:PNG-IMG-54f022ae8b3f4d479e925b4df68e19"
}

On success, you will receive a rich media URN which uniquely identifies the newly uploaded media. The media is not displayed on LinkedIn until you create a share that references this uploaded media.

Get Rich Media Summary

When you upload an image to LinkedIn, you receive a media URN associated with that image. Parse the ID from the URN to fetch the URLs for the image.

Each URL is for a different image size. LinkedIn shrinks images to fit the aspect ratio so that the width and height do not exceed the following values. In the response, you must parse the URL value to check if it ends with -small., -medium., or -large. to determine the size.

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

Sample Request

GET https://api.linkedin.com/v2/richMediaSummariesV2/JPEG-IMG-69ef4c1d2ee346a184a665e9595e2f92

Sample Response

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

GET https://api.linkedin.com/v2/richMediaSummariesV2?ids=JPEG-IMG-d1bf4938b968460585c38b615ed5d039ids=PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ced9ids=PNG-IMG-1b0e1c93aa0a441bbcabd3ce7986ce11

Sample Response

{
    "errors": {}, 
    "results": {
        "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-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"
                }
            ]
        }, 
        "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"
                }
            ]
        }
    }, 
    "statuses": {}
}

Post Rich Media Shares

Sharing rich media is very similar to creating shares. The one 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 media in the previous step.

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

For details on creating shares, see Post Shares.

Note

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

Sample Request

To post a share that includes rich media:

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

To post a multi-image share, upload multiple images to be specified in contentEntities:

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

Sponsoring a rich media share is similar to sponsoring a regular organization share.

Optimize Rich Media Shares for Mobile

We recommend that you upload rich media in 1200 x 627 aspect ratio. Images uploaded in the recommended 1200 x 627 ratio are automatically displayed on the mobile app with white padding on the top/bottom or sides of the image, to fit the ratio without being cropped. Although a 3:2 aspect ratio, or 1200 x 800, displays fully without padding, we recommend using the industry-standard 1200 x 627 ratio. Link share thumbnail image uploads are displayed in a 2:1 ratio. Limit text in rich media images to the center of the image in a title-safe area, as shown in the following image:

Title Safe Area

Introduction text is truncated to show “... see more” at around 128-130 characters depending on the mobile device size. Title text is truncated 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 in the following section.
  • 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.

See Share and Share Content schema for more details.

Image Specifications

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

Access Requirements

  • The authenticated user must be the ADMINISTRATOR of the company page or DIRECT_SPONSORED_CONTENT_POSTER with access to the Campaign Manager.

Sample Request

POST https://api.linkedin.com/v2/shares
{
    "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"
            }
        ], 
        "landingPageUrl": "https://www.example.com", 
        "shareMediaCategory": "CAROUSEL"
    }, 
    "distribution": {
        "linkedInDistributionTarget": {}
    }, 
    "owner": "urn:li:company:1234", 
    "subject": "Carousel Test through API", 
    "text": {
        "text": "Test Carousel Share!"
    }
}

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

Additional Access Requirements

Note

The authenticated user must have a role higher than VIEWER for the Ad Account to create Direct Sponsored Content (DSC). For more information on DSC, see FAQs.

Sample Request

POST https://api.linkedin.com/v2/shares
{
    "agent": "urn:li:sponsoredAccount:2342", 
    "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"
            }
        ], 
        "landingPageUrl": "https://www.example.com", 
        "shareMediaCategory": "CAROUSEL"
    }, 
    "distribution": {
        "linkedInDistributionTarget": {}
    }, 
    "owner": "urn:li:company:1234", 
    "subject": "Carousel Ads Test through API", 
    "text": {
        "text": "Test Carousel Share!"
    }
}