Why LinkedIn lifecycleState Only Takes PUBLISHED on Create

What does LinkedIn lifecycleState do on the Posts API?

The LinkedIn lifecycleState field sets the state of a post, and on create it takes one value only: PUBLISHED. Microsoft Learn's Post API schema says it in one line: "PUBLISHED is the only accepted field during creation." The schema marks the field as Enum string and required, so you cannot leave it out either.

Every sample request on the Posts API page carries the same line:

{
  "author": "urn:li:organization:5515715",
  "commentary": "Sample text Post",
  "visibility": "PUBLIC",
  "distribution": {
    "feedDistribution": "MAIN_FEED",
    "targetEntities": [],
    "thirdPartyDistributionChannels": []
  },
  "lifecycleState": "PUBLISHED",
  "isReshareDisabledByAuthor": false
}

A successful create returns 201, and LinkedIn puts the new post's ID in the x-restli-id response header as urn:li:share:{id} or urn:li:ugcPost:{id}.

Which values can lifecycleState return?

LinkedIn documents four values, and three of them you will only ever read, never send.

The schema introduces the last three with a plain qualifier: "The following values can be returned in responses." They describe posts, not instructions to LinkedIn.

PUBLISH_REQUESTED is the one that confuses integrations. LinkedIn says content in that state "will be published asynchronously once the processing has successfully completed." A 201 on create tells you LinkedIn accepted the request. The state tells you whether the post is live, and those are two different facts.

PUBLISH_FAILED has a specific recovery rule: "An edit is required in order to re-attempt publishing." Sending the same create request again produces a second post, not a retry of the first.

Can you create a LinkedIn draft through the API?

No. The Posts API documents no way to create a post in DRAFT, and the create rule leaves no room for one. DRAFT shows up in responses for content that exists only for its author, but LinkedIn does not say how such content comes to exist or how a developer would make it.

LinkedIn also does not document the exact response you get for sending "lifecycleState": "DRAFT" on create. The closest match in the error table is this row:

So a scheduler that wants to hold a post until a set time has to hold it on its own side and send the create call at that moment. LinkedIn's API offers no parked state to lean on. This is why scheduled LinkedIn posts stop working when the tool doing the holding loses its token: nothing sits on LinkedIn's side waiting to go live.

Where does LinkedIn's documentation contradict itself?

Three places on the same two pages don't agree with the enum.

The first is the viewContext note on the Posts API page. It says the AUTHOR view "can be used to retrieve the latest version of a post, which has not yet been published; it can be in a number of possible states such as: PUBLISHED, DRAFT or PROCESSING." PROCESSING is not a Posts API value. It belongs to the older ugcPosts API, and the Posts API enum has PUBLISH_REQUESTED in its place.

The second is in the lifecycleStateInfo table on the schema page. The reviewStatus field is "Applicable for lifecycle state values of PUBLISH_REQUESTED and PUBLISHED_FAILED only." There is no PUBLISHED_FAILED. The enum spells it PUBLISH_FAILED. If you are generating types from the docs, use the enum's spelling.

The third is the update section. LinkedIn lists lifecycleState among the only fields you can change with a PARTIAL_UPDATE, next to commentary, contentCallToActionLabel, contentLandingPage and adContext. The page gives no example of changing it and does not say which transitions are allowed. The sample update only touches commentary and contentCallToActionLabel.

How do Posts API states map to the old ugcPosts states?

The Posts API replaced ugcPosts, and LinkedIn's migration trimmed the enum from seven values to four. The ugcPosts schema on Microsoft Learn still lists all seven.

The descriptions line up nearly word for word. ugcPosts defines PROCESSING as content "submitted for publish but is not yet ready for rendering," which is the Posts API's PUBLISH_REQUESTED definition with one word changed.

Two of the dropped values moved elsewhere. Deletion is now a DELETE request with X-RestLi-Method: DELETE, and LinkedIn says "Post deletions are idempotent," returning 204 even for a post that was already gone. Edits show up as a boolean, lifecycleStateInfo.isEditedByAuthor, which LinkedIn says is "Applicable for UserGeneratedContentLifecycleState value of PUBLISHED only."

What is lifecycleStateInfo?

It is the companion object that explains a state, and LinkedIn returns it on read. It has three fields:

• contentStatus: "Status for post content," with the values PENDING, PROCESSING and FAILED. "If processing completes UGC transitions to PUBLISHED and the contentStatus is null."
• reviewStatus: "Review status of the post," with the same three values, null once the post reaches PUBLISHED.
• isEditedByAuthor: defaults to false.

This is where PROCESSING legitimately lives in the Posts API. It is a value of contentStatus and reviewStatus, not of lifecycleState. Code that switches on lifecycleState should never expect it.

Which headers does a create call need?

Four, and LinkedIn states two of them at the top of the Posts API page: "All APIs require the request header Linkedin-Version: {Version in YYYYMM format}" and "All APIs require the request header X-Restli-Protocol-Version: 2.0.0".

curl -X POST 'https://api.linkedin.com/rest/posts' \
  -H 'Authorization: Bearer {INSERT_TOKEN}' \
  -H 'X-Restli-Protocol-Version: 2.0.0' \
  -H 'Linkedin-Version: 202608' \
  -H 'Content-Type: application/json' \
  --data '{ ...body with "lifecycleState": "PUBLISHED"... }'

The version header is the one that breaks builds, because it has to be six digits and the version has to still be live. The rules for that value are in the note on why the LinkedIn-Version header must be YYYYMM. The Posts API page currently carries a warning that Marketing Version 202510 "will be sunset on October 15, 2026."

The token needs a posting permission too. w_member_social posts for the authenticated member. w_organization_social posts for a company page and is "Restricted to organizations where the authenticated member has one of the following company page roles: ADMINISTRATOR, DIRECT_SPONSORED_CONTENT_POSTER, CONTENT_ADMIN."

How do you read the current state of a post?

Send a GET to https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn}, and add viewContext=AUTHOR if you want to see unpublished states. LinkedIn explains that the default, READER, "specifies the version of the post that has been published and is viewable to a general audience." A post still in PUBLISH_REQUESTED is exactly the kind of thing the READER view will not show you.

Media posts go through a separate upload step first. LinkedIn says a post with an image "requires uploading an image asset to obtain an Image URN (urn:li:image:{id}) for use in the post," and the create call then references that URN. The note on the LinkedIn initializeUpload image URN covers that part of the flow.

Frequently asked questions

Is lifecycleState required on the LinkedIn Posts API?

Yes. The schema marks it required, and the MISSING_FIELD error description names it as one of the fields that must be present, next to author, visibility and distribution.

Can I schedule a LinkedIn post by creating it as a DRAFT?

No. PUBLISHED is the only value LinkedIn accepts on create, so a scheduled post has to wait in your own system until the moment you send the create call.

What does PUBLISH_REQUESTED mean?

LinkedIn accepted the post but has not finished processing it. LinkedIn says the content "will be published asynchronously once the processing has successfully completed."

How do I retry a post stuck in PUBLISH_FAILED?

Edit it. LinkedIn's definition says "An edit is required in order to re-attempt publishing." Creating the post again makes a new post.

Why do LinkedIn's docs mention PROCESSING and PUBLISHED_FAILED?

Both are documentation slips. PROCESSING is a ugcPosts value and a contentStatus value, and PUBLISHED_FAILED is a misspelling of PUBLISH_FAILED. Neither appears in the Posts API lifecycleState enum.

Does a deleted post come back with a DELETED state?

No. The Posts API has no DELETED value. A DELETE request returns 204, and LinkedIn says repeat deletions of the same post also return 204.

What error does LinkedIn return if I send DRAFT as lifecycleState?

LinkedIn does not document the exact response for that case. The closest documented error is 400 INVALID_VALUE_FOR_FIELD, with the message "{field} cannot be set to {value}." LinkedIn advises verifying that enum values such as lifecycleState are valid, and on create the only valid one is PUBLISHED.

How do I see a LinkedIn post that is not published yet?

Send a GET to https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn} with viewContext=AUTHOR. The default READER view shows only the version that has been published and is viewable to a general audience. A post in PUBLISH_REQUESTED will not appear there.

Which headers does a LinkedIn Posts API create call need?

Linkedin-Version in YYYYMM format and X-Restli-Protocol-Version: 2.0.0 are required. The sample request also sends Authorization with a Bearer token and Content-Type: application/json. The version has to still be live, because LinkedIn warns that Marketing Version 202510 "will be sunset on October 15, 2026."

Which permission do I need to post to a LinkedIn company page?

You need w_organization_social. LinkedIn says it is "Restricted to organizations where the authenticated member has one of the following company page roles: ADMINISTRATOR, DIRECT_SPONSORED_CONTENT_POSTER, CONTENT_ADMIN." To post as the authenticated member, w_member_social is the one to use.