Skip to content

LinkedIn post API

The LinkedIn post API publishes text posts, images, videos, and articles to LinkedIn personal profiles and company pages. It handles OAuth, token management, and the LinkedIn media upload process, so you connect an account once, retrieve its accountId, and then publish with content, platforms, and publishNow.

Overview

This guide covers publishing to LinkedIn accounts, including individual profiles and organization pages, across text, image, video, and article formats. Authorization, token handling, and the underlying media upload steps are managed for you. Work through the three quick-start steps in sequence: connect the account, retrieve its account ID, then publish. If any step fails, stop and fix that step before retrying the publish request, because a post request cannot succeed without a connected account and a valid accountId.

Quick start: connect, get account ID, publish

First, request the LinkedIn connection URL with GET {{API_BASE_URL}}/v1/connect/linkedin and the x-access-key header. The response contains a url field pointing to LinkedIn authorization. Redirect the user to that url. After authorization, the account is connected to your project. Check that the redirect completes and that the account appears in the integrations list before continuing. Second, request GET {{API_BASE_URL}}/v1/connect/integrations with the same header. Find the integration whose platform is linkedin and note its id. That id is the accountId you will send when publishing. If no linkedin integration is present, the connection step did not complete. Third, publish with POST {{API_BASE_URL}}/v1/posts, sending content, a platforms array containing platform linkedin and accountId, and publishNow true. A successful response has success true, status published, a postId, and a platforms entry with success true and a platformPostUrl. Treat a missing platformPostUrl or a non-published status as a failure to investigate, not as a completed publish.

Text posts

Text posts can contain up to 3,000 characters. Keep content within that limit before sending, and check the exact text you intend to mention or link, because mention matching and article preview fields depend on the final content string. A text-only post needs no mediaItems and no platformSpecificData unless you want to set visibility or mentions.

Images and videos with mediaItems

Attach media with the mediaItems array on the post request. Supported images are JPG, PNG, and GIF, up to 9 per post. Supported video is MP4, 1 per post, up to 5 GB. Images are limited to 10 MB each. Before publishing, verify each media URL is reachable, each item type matches its file format, and the counts and sizes are within limits. Exceeding a count or size limit is a validation failure to correct in the request, not something to work around by splitting a single intended post into unexpected extra posts.

Visibility with platformSpecificData.visibility

Control who can see the post with platformSpecificData.visibility inside the LinkedIn entry in platforms. PUBLIC, the default, makes the post visible to everyone. CONNECTIONS makes it visible to connections only. Set the field explicitly when the audience matters, and verify the value is exactly PUBLIC or CONNECTIONS. Any other value does not match the captured contract.

Company-page mentions with platformSpecificData.mentions

Tag a company page with platformSpecificData.mentions. This feature works only for organization or company pages; individual profiles cannot be tagged this way. For each entry, you pair a precise piece of your post text with the target organization's URN, and LinkedIn displays that text as a clickable tag. The text value must occur a single time in content and match its capitalization exactly, so check spelling, capitalization, and count before sending. The urn value must be the LinkedIn URN of the company page, in the form urn:li:organization: followed by the organization identifier. To locate that identifier, inspect the company's LinkedIn page address or check the integration details available through Connect Accounts. If the text appears zero times or more than once, or differs in case, the mention will not match the contract.

Articles and documents

For an article or link post, provide articleUrl as a uri. When provided, the post becomes a link share with a preview card. Use articleTitle and articleDescription for the preview card title and description, each up to 400 characters. For a PDF document post, provide documentTitle, up to 200 characters, which is required by LinkedIn when a document media item is included. See the platform-specific data field map and the limits and validation matrix for the full field list and failure checks.

LinkedIn platformSpecificData field map
FieldTypeRequiredValues and constraintsDescription
visibilitystringNoPUBLIC, CONNECTIONSPost visibility. PUBLIC = visible to everyone, CONNECTIONS = visible to connections only. Defaults to PUBLIC.
mentionsobject[]NoItems: 0-30Tag company pages in the post text. Each entry maps an exact substring of content to the organization URN to mention; LinkedIn renders it as a clickable mention. Only company pages can be mentioned, not personal profiles.
mentions[].textstringYes, in each mentions[] itemLength: 1-unboundedExact substring within the post content to turn into a clickable mention (e.g. Acme Corp). Case-sensitive, must appear exactly once in content.
mentions[].urnstringYes, in each mentions[] item-LinkedIn URN of the company page to mention, e.g. urn:li:organization:12345. LinkedIn only supports mentioning organization/company pages, not personal profiles.
articleUrlstringNoFormat: uriURL for an article/link post. When provided, the post becomes a link share with a preview card.
articleTitlestringNoLength: 0-400Title for the article preview card. Max 400 characters.
articleDescriptionstringNoLength: 0-400Description for the article preview card. Max 400 characters.
documentTitlestringNoLength: 0-200Title shown on the document card when posting a PDF. Required by LinkedIn when a document media item is included.

Captured contract field map; origin modularised as {{API_BASE_URL}}.

LinkedIn post limits
LimitValue
Character limit3,000 per post
Images per post9
Videos per post1
Max video size5 GB
Max image size10 MB

Captured contract limits.

Input contract checklist and validation matrix
CheckPass conditionFailure action
Account connectedGET {{API_BASE_URL}}/v1/connect/integrations returns an entry with platform linkedinRepeat the connect flow and redirect to the returned url
accountId presentplatforms entry includes accountId matching the integration idUse the noted id; do not guess an account identifier
Content lengthcontent is at most 3,000 charactersShorten content before publishing
Mention textmentions[].text appears exactly once in content, case-sensitiveFix spelling, capitalization or duplicate occurrences
Mention targetmentions[].urn is an organization URN for a company pageReplace personal-profile targets with a company page URN
Media count and sizeAt most 9 images, at most 1 MP4 video, images at most 10 MB, video at most 5 GBRemove or replace media items that exceed limits
Document postdocumentTitle provided when a document media item is includedAdd documentTitle within 200 characters
Publish resultResponse success true, status published, platformPostUrl presentInvestigate the response before treating the post as published

Derived from captured constraints; illustrative checks for implementers.

Frequently asked questions

How do I set LinkedIn post visibility?

Use platformSpecificData.visibility with PUBLIC for everyone or CONNECTIONS for connections only. PUBLIC is the default when the field is omitted.

Can I mention a personal LinkedIn profile?

Only organization or company pages can be mentioned, not personal profiles. Each mentions entry needs text that appears exactly once in content, case-sensitively, and the matching organization URN.

What media limits apply to a LinkedIn post?

Images are JPG, PNG or GIF, up to 9 per post and up to 10 MB each. Videos are MP4, 1 per post, up to 5 GB. Text is limited to 3,000 characters per post.

When is documentTitle required?

When a document media item is included, documentTitle is required by LinkedIn for the document card. It is a string of length 0-200 in the field map.

How do I create an article or link post?

Provide articleUrl as a uri for a link share with a preview card. articleTitle and articleDescription, each up to 400 characters, supply the preview card title and description.

Connect a LinkedIn account
curl {{API_BASE_URL}}/v1/connect/linkedin \
  -H "x-access-key: YOUR_API_KEY"

# Response:
{
  "url": "https://www.linkedin.com/oauth/v2/authorization?..."
}
Get the LinkedIn account ID
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"

# Find the integration with "platform": "linkedin" and note its id as accountId.
Publish a LinkedIn text post
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "linkedin", "accountId": "li_123" }
    ],
    "publishNow": true
  }'

# Response:
{
  "success": true,
  "status": "published",
  "postId": "post_abc123",
  "platforms": [
    {
      "platform": "linkedin",
      "success": true,
      "platformPostUrl": "https://www.linkedin.com/feed/update/urn:li:share:123456"
    }
  ]
}
Publish a LinkedIn post with mediaItems
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "linkedin", "accountId": "li_123" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/photo.jpg" }
    ],
    "publishNow": true
  }'
Publish with CONNECTIONS visibility
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "linkedin",
        "accountId": "li_123",
        "platformSpecificData": {
          "visibility": "CONNECTIONS"
        }
      }
    ],
    "publishNow": true
  }'
Publish with a company-page mention
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "linkedin",
        "accountId": "li_123",
        "platformSpecificData": {
          "mentions": [
            { "text": "An example comment.", "urn": "urn:li:organization:2414183" }
          ]
        }
      }
    ],
    "publishNow": true
  }'
Contract example 1
curl {{API_BASE_URL}}/v1/connect/linkedin \
  -H "x-access-key: YOUR_API_KEY"
Contract example 2
{
	"url": "https://www.linkedin.com/oauth/v2/authorization?..."
}
Contract example 3
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Contract example 4
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "linkedin", "accountId": "li_123" }
    ],
    "publishNow": true
  }'
Contract example 7
{
	"success": true,
	"status": "published",
	"postId": "post_abc123",
	"platforms": [
		{
			"platform": "linkedin",
			"success": true,
			"platformPostUrl": "https://www.linkedin.com/feed/update/urn:li:share:123456"
		}
	]
}
Contract example 8
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Here'\''s a look at what we'\''ve been building.",
    "platforms": [
      { "platform": "linkedin", "accountId": "li_123" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/photo.jpg" }
    ],
    "publishNow": true
  }'