# LinkedIn document carousels: how the PDF swipe post actually works

Every few months someone asks how to post a LinkedIn carousel through the API.
The answer is that there is no such thing, and the thing they actually want has
a different name.

## The swipe post is a PDF

What people call a LinkedIn carousel is a **document post**. You upload a PDF,
LinkedIn renders each page as a slide, and the feed shows it as a swipeable
card. That is the entire mechanism.

So the API you want is the Documents API, not anything with "carousel" in the
name.

## Three calls

1. **Initialise the upload.**
   `POST /rest/documents?action=initializeUpload` with the author URN. LinkedIn
   returns an `uploadUrl` and a `document` URN.
2. **PUT the bytes** to that `uploadUrl`. This is a plain upload to a
   LinkedIn-owned URL, not an API call in the usual sense.
3. **Create the post.** `POST /rest/posts` with the document URN in the
   `content.media` field.

Between two and three, the document has to finish processing. Poll
`GET /rest/documents/{urn}` until its status is `AVAILABLE`.

## The versioned endpoints have their own rules

The `/rest/*` endpoints are not the old `/v2/*` ones, and mixing them up
produces errors that look like authentication problems.

Every versioned call needs two headers:

```
LinkedIn-Version: 202506
X-Restli-Protocol-Version: 2.0.0
```

The version is a `YYYYMM` string and LinkedIn retires old ones on a schedule. If
you hard-code a single version, your integration has an expiry date you did not
choose. Keep a small ladder of acceptable versions in configuration, and make it
loud when the newest one you know about is rejected.

## The empty 201

This is the one that costs an afternoon.

`POST /rest/posts` succeeds with **201 Created and an empty body**. There is no
JSON, no id, nothing. A client written the obvious way parses the body, finds
nothing, and reports a failure for a post that went out perfectly.

The id is in a response header:

```
x-restli-id: urn:li:share:7231...
```

Read it from there. And if the header is missing but the status was 201, the
post still succeeded — treat the missing id as an unknown id, not as an error,
because retrying will publish a duplicate.

## A document is posted alone

LinkedIn will not accept a post carrying a PDF and images together. One
document, nothing else.

This is worth validating before the upload rather than after. Otherwise you
discover it at step three, having already pushed a 20MB file across the wire.

## Polling, and the duplicate-post trap

The same arithmetic that applies to Instagram containers applies here, and it
is worth repeating because the failure is identical and equally expensive.

If your scheduler reclaims a job it thinks is stuck after five minutes, and your
document-processing poll runs for five minutes, the two race. A second worker
claims the post while the first is still polling, and the customer's audience
gets the same carousel twice.

Give the poll a budget that is a fraction of the reclaim timeout. Half is fine.
The cost of giving up early is a failed post the user can retry; the cost of
giving up late is a duplicate they cannot delete from everyone's feed.

## Summary

Upload a PDF, wait for `AVAILABLE`, create the post, read the id from
`x-restli-id`. Post the document on its own. Keep your API version in config,
and keep your poll shorter than your reclaim.