Rich Media Shares

LinkedIn provides media platform for you to upload images to reference in a personal or organization share. With this platform, 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
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

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.

LinkedIn's media platform has following APIs to upload images.

To upload rich media, follow the below steps that uses assets API for uploading images. Further details can be found with assets API doc. The response from the assets API is of type urn:li:digitalmediaAsset:{ID}. An example is: urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ

Register an Upload For Image

Use the registerUpload action to register the image upload. When you register, you declare the upcoming upload. Use the HTTP URL that's returned to upload the image. The recipes field shown below is specific to type of content being created. To decide what recipe to use, check the details with assets API doc.

Sample Request

POST https://api.linkedin.com/v2/assets?action=registerUpload

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

{
    "registerUploadRequest": {
        "owner": "urn:li:organization:10000",
        "recipes": [
            "urn:li:digitalmediaRecipe:feedshare-image"
        ],
        "serviceRelationships": [
            {
                "identifier": "urn:li:userGeneratedContent",
                "relationshipType": "OWNER"
            }
        ]
    }
}

Sample Response

{
    "value": {
        "uploadMechanism": {
            "com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest": {
                "headers": {
                    "media-type-family": "STILLIMAGE"
                },
                "uploadUrl": "https://api.linkedin.com/mediaUpload/C5522AQHn46pwH96hxQ/feedshare-uploadedImage/0?ca=vector_feedshare&cn=uploads&m=AQLKRJOn_yNw6wAAAW2T0DWnRStny4dzsNVJjlF3aN4-H3ZR9Div77kKoQ&app=1983914&sync=0&v=beta&ut=1Dnjy796bpjEY1"
            }
        },
        "mediaArtifact": "urn:li:digitalmediaMediaArtifact:(urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ,urn:li:digitalmediaMediaArtifactClass:feedshare-uploadedImage)",
        "asset": "urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ"
    }
}

Upload the Image

Use the uploadUrl from the previous step to upload the image.

Sample curl Request

curl -i --upload-file ~/Desktop/Myimage.jpg -H 'Authorization: Bearer Redacted' "https://api.linkedin.com/mediaUpload/C5522AQHn46pwH96hxQ/feedshare-uploadedImage/0?ca=vector_feedshare&cn=uploads&m=AQLKRJOn_yNw6wAAAW2T0DWnRStny4dzsNVJjlF3aN4-H3ZR9Div77kKoQ&app=1983914&sync=0&v=beta&ut=1Dnjy796bpjEY1"

Sample Response

HTTP/2 201 
server: Play
set-cookie: lang=v=2&lang=en-us; Path=/; Domain=api.linkedin-ei.com
date: Wed, 16 Oct 2019 06:25:12 GMT
content-length: 0
x-li-proto: http/2
report-to: {"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}
nel: {"report_to":"network-errors","max_age":1296000,"success_fraction":0.0001,"failure_fraction":1,"include_subdomains":true}
x-li-uuid: slguD4sMzhUwATrTkisAAA==
set-cookie: lidc="b=ETB86:g=301:u=12:i=1571207079:t=1571261189:s=AQGEngFr_Vc-bGAR4gREsIou-eLZon31"

Upload Images Using Media Upload API (To be deprecated by January 30, 2020)

To upload rich media, attach the media as multipart/form-data. The response from the media upload API is of type urn:li:richMediaSummary:{ID}. An example is: urn:li:richMediaSummary:PNG-IMG-54f022ae8b3f4d479e925b4df68e19

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

This API will be deprecated by January 30, 2020.

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

This API will be deprecated by January 30, 2020.

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 media asset URN that was created using assets API from the previous step.

Note

Uploading image using https://api.linkedin.com/media/upload is being deprecated. Partners are recommended to use assets API that returns response such as urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ to post shares.

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.

To post a share that includes rich media:

POST https://api.linkedin.com/v2/shares
{
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ"
            }
        ],
        "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:digitalmediaAsset:C5522AQHn46pwH96hxQ"
            },
            {
                "entity": "urn:li:digitalmediaAsset:C551DAQEO3lh6Wa6Yng"
            },
            {
                "entity": "urn:li:digitalmediaAsset:C550EAQH7NHQ5NY0_EQ"
            }
        ],
        "description": "content description",
        "title": "Test Share with Content"
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "subject": "Test Share Subject",
    "text": {
        "text": "Test Share!"
    }
}

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 Using Rich Media Summary URN (To be deprecated by January 30, 2020)

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.
POST https://api.linkedin.com/v2/shares
{
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ",
                "landingPageUrl": "https://www.example.com/product1",
                "title": "ABC"
            },
            {
                "entity": "urn:li:digitalmediaAsset:C551DAQEO3lh6Wa6Yng",
                "landingPageUrl": "https://www.example.com/product2",
                "title": "XYZ"
            },
            {
                "entity": "urn:li:digitalmediaAsset:C550EAQH7NHQ5NY0_EQ",
                "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!"
    }
}

Sample Request Using Rich Media Summary URN (To be deprecated by January 30, 2020)

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.

POST https://api.linkedin.com/v2/shares
{
    "agent": "urn:li:sponsoredAccount:2342",
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ",
                "landingPageUrl": "https://www.example.com/product1",
                "title": "ABC"
            },
            {
                "entity": "urn:li:digitalmediaAsset:C551DAQEO3lh6Wa6Yng",
                "landingPageUrl": "https://www.example.com/product2",
                "title": "XYZ"
            },
            {
                "entity": "urn:li:digitalmediaAsset:C550EAQH7NHQ5NY0_EQ",
                "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!"
    }
}

Sample Request Using Rich Media Summary URN (To be deprecated by January 30, 2020)

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