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.
| Field | Type | Required | Values and constraints | Description |
|---|---|---|---|---|
| visibility | string | No | PUBLIC, CONNECTIONS | Post visibility. PUBLIC = visible to everyone, CONNECTIONS = visible to connections only. Defaults to PUBLIC. |
| mentions | object[] | No | Items: 0-30 | Tag 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[].text | string | Yes, in each mentions[] item | Length: 1-unbounded | Exact substring within the post content to turn into a clickable mention (e.g. Acme Corp). Case-sensitive, must appear exactly once in content. |
| mentions[].urn | string | Yes, 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. |
| articleUrl | string | No | Format: uri | URL for an article/link post. When provided, the post becomes a link share with a preview card. |
| articleTitle | string | No | Length: 0-400 | Title for the article preview card. Max 400 characters. |
| articleDescription | string | No | Length: 0-400 | Description for the article preview card. Max 400 characters. |
| documentTitle | string | No | Length: 0-200 | Title 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}}.
| Limit | Value |
|---|---|
| Character limit | 3,000 per post |
| Images per post | 9 |
| Videos per post | 1 |
| Max video size | 5 GB |
| Max image size | 10 MB |
Captured contract limits.
| Check | Pass condition | Failure action |
|---|---|---|
| Account connected | GET {{API_BASE_URL}}/v1/connect/integrations returns an entry with platform linkedin | Repeat the connect flow and redirect to the returned url |
| accountId present | platforms entry includes accountId matching the integration id | Use the noted id; do not guess an account identifier |
| Content length | content is at most 3,000 characters | Shorten content before publishing |
| Mention text | mentions[].text appears exactly once in content, case-sensitive | Fix spelling, capitalization or duplicate occurrences |
| Mention target | mentions[].urn is an organization URN for a company page | Replace personal-profile targets with a company page URN |
| Media count and size | At most 9 images, at most 1 MP4 video, images at most 10 MB, video at most 5 GB | Remove or replace media items that exceed limits |
| Document post | documentTitle provided when a document media item is included | Add documentTitle within 200 characters |
| Publish result | Response success true, status published, platformPostUrl present | Investigate 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.
curl {{API_BASE_URL}}/v1/connect/linkedin \
-H "x-access-key: YOUR_API_KEY"
# Response:
{
"url": "https://www.linkedin.com/oauth/v2/authorization?..."
}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.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"
}
]
}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
}'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
}'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
}'curl {{API_BASE_URL}}/v1/connect/linkedin \
-H "x-access-key: YOUR_API_KEY"{
"url": "https://www.linkedin.com/oauth/v2/authorization?..."
}curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"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
}'{
"success": true,
"status": "published",
"postId": "post_abc123",
"platforms": [
{
"platform": "linkedin",
"success": true,
"platformPostUrl": "https://www.linkedin.com/feed/update/urn:li:share:123456"
}
]
}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
}'