linkedin-api

# LinkedIn API: publish and pull analytics over the wire You own the **transport**. Auth headers, scopes, URNs, request shapes, rate-limit handling, token refresh, and the write that turns post performance into a durable feedback log. You do **not** decide what to post or why. **Decision line:** if the question is *which HTTP call, which header, which scope, which URN, how do I store the numbers* → you. If it is about the *meaning* of the content → a sibling. - Words, hooks, CTA for one post → `linkedin-content` (planned sibling). - Cadence, pillars, audience plan → `linkedin-strategy` (planned sibling). - The multi-slide PDF artifact → `linkedin-carousels` (planned sibling) builds it; you only upload the resulting document URN. - DMs, connection requests, sequences → `linkedin-outreach` (planned sibling). - Generic OAuth2 / webhook scaffolding with no LinkedIn specifics → `../api-connector-builder/SKILL.md`, `../webhooks/SKILL.md`. ## Prereqs: app + products + scopes You configure this on the LinkedIn Developer portal once, before any code runs. 1. Create a developer app, associate it with a company page (required to request org products). 2. On the **Products** tab, request the product that grants the scopes you need: - **Share on LinkedIn** → grants `w_member_social` (default-grantable, post as the member). - **Community Management API** / **Marketing Developer Platform (MDP)** → grants the organization scopes and member-read. These require approval — the app sits in a review queue. 3. Add your exact **redirect URI** under Auth. It must match the one in the authorize URL byte-for-byte or the callback fails. | Scope | Grants | Product needed | Page-role requirement | |---|---|---|---| | `w_member_social` | post/comment/like as the authed member | Share on LinkedIn | none | | `r_member_social` | read the member's own posts | restricted — approved apps only | none | | `w_organization_social` | post on behalf of an org | Community Management / MDP | ADMINISTRATOR, CONTENT_ADMIN, or DIRECT_SPONSORED_CONTENT_POSTER on the page | | `r_organization_social` | read org posts/stats | Community Management / MDP | same role set | > "unauthorized scope `w_organization_social`" at the consent screen does not mean a typo — it means the app's Community Management / MDP product is **not yet approved**. The fix is product approval, not code. ## Step 1 — 3-legged OAuth Authorization-code flow. Two endpoints: ```text GET https://www.linkedin.com/oauth/v2/authorization # send the user here POST https://www.linkedin.com/oauth/v2/accessToken # exchange code -> token ``` Send the user to authorize with `response_type=code`, your `client_id`, `redirect_uri`, a CSRF `state`, and space-separated `scope`. On callback, exchange the `code`: ```bash curl -X POST https://www.linkedin.com/oauth/v2/accessToken \ -d grant_type=authorization_code \ -d code="$AUTH_CODE" \ -d redirect_uri="$LINKEDIN_REDIRECT_URI" \ -d client_id="$LINKEDIN_CLIENT_ID" \ -d client_secret="$LINKEDIN_CLIENT_SECRET" ``` Access tokens are short-lived (~60 days). Marketing / Community apps can be issued **refresh tokens** — store the refresh token and exchange it (`grant_type=refresh_token`) before expiry. Why: re-prompting consent on every expiry breaks unattended publishing and looks broken to the user. ```text Bad: client_secret = "WPL_AP1.abc..." # committed in source Good: client_secret = process.env.LINKEDIN_CLIENT_SECRET # injected at runtime, file gitignored ``` Never write the token or secret into a tracked file. `scripts/verify.sh` greps for committed `client_secret=` and `AQED`-style token literals and fails the build if it finds one. ## Step 2 — resolve the author URN Every post needs an `author`. Two shapes: - Member: `urn:li:person:{id}` (the `sub` from the OpenID userinfo / token introspection). - Organization: `urn:li:organization:{id}` (the numeric page id). Before publishing as an org, confirm the authed member holds an eligible **page role** (ADMINISTRATOR / CONTENT_ADMIN / DIRECT_SPONSORED_CONTENT_POSTER). Why: with the scope granted but no role, the publish still returns **403 ACCESS_DENIED** — the scope authorizes the app, the role authorizes the person. ## Step 3 — publish Current organic endpoint: `POST https://api.linkedin.com/rest/posts`. The legacy `/v2/ugcPosts` and `/v2/shares` are deprecated — migrate to the versioned `/rest/posts`. Pin the version **once**: ```bash LINKEDIN_VERSION=202605 # latest; 202505 is sunset — pinning a sunset version breaks ``` Every versioned call carries **two** headers (omit either and you get 426/400): ```text Linkedin-Version: 202605 X-Restli-Protocol-Version: 2.0.0 ``` ### Text post ```bash curl -X POST https://api.linkedin.com/rest/posts \ -H "Authorization: Bearer $LINKEDIN_TOKEN" \ -H "Linkedin-Version: $LINKEDIN_VERSION" \ -H "X-Restli-Protocol-Version: 2.0.0" \ -H "Content-Type: application/json" \ -d '{ "author": "urn:li:organization:12345", "commentary": "Shipping notes for this week.", "visibility": "PUBLIC", "distribution": { "feedDistribution": "MAIN_FEED", "targetEntities": [], "thirdPartyDistributionChannels": [] }, "lifecycleState": "PUBLISHED", "isReshareDisabledByAuthor": false }' ``` Success is **201**, and the new post URN comes back in the **`x-restli-id` response header** (`urn:li:share:{id}` or `urn:li:ugcPost:{id}`) — not the body. Capture that header; you need the URN to pull analytics later. ### Article (link share) post The Posts API does **NOT scrape the URL**. You set the preview fields yourself, and the `thumbnail` must be an **Image URN** you uploaded via the Images API first: ```jsonc "content": { "article": { "source": "https://example.com/post", "title": "Our launch writeup", "description": "What we shipped and why", "thumbnail": "urn:li:image:C5..." } } ``` ### Document post Upload the file via the **Documents API** to get `urn:li:document:{id}`, then reference it: ```jsonc "content": { "media": { "id": "urn:li:document:C4..." } } ``` (Images → Images API → `urn:li:image:`; videos → Videos API → `urn:li:video:`.) Full reshare / multi-image / poll payloads and the retrieval finders live in `references/api-reference.md`. ## Step 4 — pull analytics ### Share statistics (post-level engagement) ```text GET https://api.linkedin.com/rest/organizationalEntityShareStatistics ?q=organizationalEntity &organizationalEntity=urn%3Ali%3Aorganization%3A12345 ``` **Organic only** (sponsored excluded), **rolling 12-month window**. Omit `timeIntervals` for lifetime; include it for a time-bound slice. Returns `impressionCount`, `uniqueImpressionsCount`, `clickCount`, `likeCount`, `commentCount`, `shareCount`, and `engagement` (engagement rate). ### Follower statistics ```text GET https://api.linkedin.com/rest/organizationalEntityFollowerStatistics ``` Lifetime or time-bound follower counts, segmented by facet (geo, industry, seniority, function, staff size), covering **paid + organic** followers. > URNs in any URL path or query **must be URL-encoded**: `urn:li:organization:12345` → `urn%3Ali%3Aorganization%3A12345`. An un-encoded colon silently breaks the route. ## Step 5 — ingest performance into the wiki This is the deliverable that makes the skill durable: after pulling stats, write one file per post under `02-DOCS/wiki/linkedin/`. Later content decisions get grounded in what actually worked, not vibes. Filename: the post id slug, e.g. `02-DOCS/wiki/linkedin/share-7012345678901234567.md`. ```markdown --- type: linkedin-record title: "Share 7012345678901234567 — OAuth pitfalls carousel" description: Performance snapshot for one LinkedIn post, pulled from organizationalEntityShareStatistics. tags: [linkedin, analytics, post-performance] timestamp: "2026-06-02T10:00:00Z" topic: linkedin status: stable post_urn: "urn:li:share:7012345678901234567" author: "urn:li:organization:12345" captured_at: "2026-06-02T10:00:00Z" impressions: 4821 unique_impressions: 4102 clicks: 213 likes: 96 comments: 14 shares: 8 engagement: 0.0683 --- # Share 7012345678901234567 — OAuth pitfalls carousel Carousel on OAuth pitfalls. Highest unique-impression post this month; CTR ~4.4%. The "common 403 causes" hook outperformed the plain howto. ``` `type` is the only required OKF v0.1 field; `title`/`description`/`tags`/`timestamp` are the recommended OKF surface. The DOMAIN keys below them are mandatory and must stay byte-for-byte — `verify.sh` checks that `post_urn`, `captured_at`, `impressions`, and `engagement` are present in every file under that directory. `captured_at` is the API-capture instant (a domain value verify.sh parses); `timestamp` is the OKF last-edit field — keep both. Note these files share `02-DOCS/wiki/linkedin/` with `linkedin-strategy`; using `type: linkedin-record` keeps the two skills' wiki content consistent. ## Anti-patterns | Anti-pattern | Why it breaks | Do instead | |---|---|---| | Pinning `Linkedin-Version: 202505` | That version is sunset; calls start failing on cutover | Pin `202605` in one constant; bump deliberately | | Sending only `Linkedin-Version`, dropping `X-Restli-Protocol-Version` | Versioned endpoints reject the request (426/400) | Always send both headers together | | Expecting the API to scrape an article URL | Posts API never fetches OG tags; you get a bare link | Set `source`/`title`/`description` + an uploaded Image URN | | Reading the new post id from the response body | The URN is in `x-restli-id`, body has no id | Read the `x-restli-id` response header | | Treating share statistics as total reach | They are **organic only**, 12-month window | Pull sponsored from the ads stats endpoints separately | | Un-encoded URN in the URL path/query | The colons break routing → 400/404 | URL-encode every URN argument | | Committing the token or `client_secret` | Leaked credential, instant revoke | Read from env; gitignore token files | | Re-prompting consent on every token expiry | Breaks unattended jobs, looks broken | Store the refresh token, refresh before ~60-day expiry | | Granted scope but member has no page role | Publish still returns 403 ACCESS_DENIED | Verify ADMINISTRATOR/CONTENT_ADMIN/DSC role first | | Polling analytics in a tight loop | `429 TOO_MANY_REQUESTS` throttle | Back off and batch; schedule, don't hammer | ## Verify Run `scripts/verify.sh [TARGET_DIR]` (default current dir). It is read-only and static — no network. It confirms each `02-DOCS/wiki/linkedin/*.md` carries the required front-matter keys, and fails on any committed token / client secret in the tree. A clean or not-yet-run target passes with a NOTE. ## References `references/api-reference.md` — full curl bodies (text, article, document, reshare, multi-image, poll), post retrieval finders, the complete analytics query params and response schemas for both statistics endpoints, the HTTP error-code catalog (400/401/403/404/409/422/429/500/503), URL-encoding and query-tunneling rules, and the version-deprecation note.