> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gtm-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a LinkedIn account

> Connect an account in the app, wait out the initial sync, then work with it over the API. The login happens inside a dedicated antidetect browser; no password ever reaches the platform.

Connecting is the one step that happens in the app rather than the API: the account
owner signs in to LinkedIn inside a dedicated antidetect browser, because a live human
login is what keeps the session real. Everything after that is API territory.

<Tip>
  **Give this to your AI agent** and it will handle the API side once you finish the
  in-app login:

  "Connect to gtm-api: add the MCP connector at [https://mcp.gtm-api.com/mcp](https://mcp.gtm-api.com/mcp) (OAuth) or
  call the REST API at app.gtm-api.com with my key. Then: search linkedin-accounts for
  my newly connected account, watch its status until it is active, read its smart
  limits, and tell me what outbound budgets I have today. Do not send anything yet."
</Tip>

## Prerequisites

* A gtm-api workspace on any plan (Sandbox, the forever free plan, includes one account slot)
* The LinkedIn credentials stay with you; you will type them into LinkedIn itself

## 1. Connect in the app

<Steps>
  <Step title="Open Senders and click Connect account">
    On [app.gtm-api.com](https://app.gtm-api.com/login), open **Senders** and click
    **Connect account** in the top right.

    <Frame caption="The Senders page: every connected account with its browser, health and sync state.">
      <img src="https://mintcdn.com/getsalesio/-R0KXJStre05Nt_b/images/kb/senders-list.png?fit=max&auto=format&n=-R0KXJStre05Nt_b&q=85&s=44cd103b2073b2bd917644abf1203878" alt="Senders page listing LinkedIn accounts with statuses, browsers and health scores" width="2560" height="1600" data-path="images/kb/senders-list.png" />
    </Frame>
  </Step>

  <Step title="Pick how the browser is provisioned">
    **Cloud browser** (recommended): the platform mints a fresh anti-detect profile with a
    managed residential proxy. Pick the **Proxy location** country to match where the
    account usually logs in from.

    <Frame caption="Cloud browser: choose the vendor and the proxy country; the summary names exactly what will be created.">
      <img src="https://mintcdn.com/getsalesio/FtMYVk1j6G6ZX8i_/images/kb/connect-modal-cloud.png?fit=max&auto=format&n=FtMYVk1j6G6ZX8i_&q=85&s=15bcb98b2d9a6fd82acac90d264513f4" alt="Connect LinkedIn account modal on the Cloud browser tab with vendor and proxy location fields" width="1200" height="1016" data-path="images/kb/connect-modal-cloud.png" />
    </Frame>

    **Existing profile ID** (bring your own): you already have a GoLogin profile. It keeps
    its own proxy; the platform verifies the profile exists and is runnable, and never
    changes it.

    <Frame caption="Bring your own: the profile and its proxy remain yours; the platform only reads the session.">
      <img src="https://mintcdn.com/getsalesio/FtMYVk1j6G6ZX8i_/images/kb/connect-modal-byo.png?fit=max&auto=format&n=FtMYVk1j6G6ZX8i_&q=85&s=f9ff5ea3c62d7874c7555358b60a06c8" alt="Connect LinkedIn account modal on the Existing profile ID tab with the GoLogin profile ID field" width="1200" height="1068" data-path="images/kb/connect-modal-byo.png" />
    </Frame>
  </Step>

  <Step title="Log into LinkedIn inside the browser">
    Run the browser and sign in to LinkedIn in the window that opens. The platform detects
    the logged-in account and binds it to the browser.

    Accounts are deduplicated by their LinkedIn member identity: reconnecting an account
    your team connected and deleted before restores it instead of duplicating it. If the
    account is already connected on a different team, binding is refused.
  </Step>
</Steps>

<Warning>
  A sudden proxy-country change is a classic trigger for LinkedIn verification
  challenges. Pick the country the account genuinely operates from, and keep it.
</Warning>

## 2. Watch the initial sync

The account enters onboarding: an initial import of the profile, conversations,
connections and invitations, in a strict order. Outbound actions are held until it
completes.

```bash theme={null}
curl -X POST "https://app.gtm-api.com/linkedin/v4/api/linkedin-accounts/search" \
  -H "Authorization: Bearer gtm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"q": "cooper"}}'
```

The `status` field is the account lifecycle:

| Status | Meaning |
| - | - |
| `new` | Connected, sync not started |
| `initial_syncing` | First sync in progress |
| `active` | Usable; outbound actions allowed |
| `sync_failed` | The sync hit a problem; check the account in the app |
| `shared_out` | Lent to another team via account sharing |
| `subscription_required` | The plan lapsed; renew to reactivate |

Until the account reaches `active`, outbound endpoints (connection requests, messages)
answer with a `conflict` error. Read endpoints work as soon as data lands. When the first
sync finishes, the person who connected the account gets an email saying it is ready, with
what the sync brought in; a large account can run out of its first-day read budget part-way,
in which case the account carries `initial_sync_held_at`, the sync resumes on its own after
the daily reset, and the email arrives a day later and says so.

## 3. Check capabilities and limits

* `POST /api/linkedin-accounts/{sid}/check-premium-subscription` reports what the account's
  LinkedIn subscription actually supports (`has_premium`, `has_sn`, `recruiter_status`, and for a
  Recruiter seat its number and the session's expiry); `checks` narrows it to one step. Sales
  Navigator endpoints on an account without Sales Navigator fail upfront with
  `422 sales_nav_required`, Recruiter ones with `422 recruiter_required`, rather than mid-run.
* `POST /api/linkedin-account-smart-limits/search` returns the account's current
  per-action daily budgets. A newly connected account starts well below platform
  maximums and warms up as it ages; read these limits instead of assuming a number.
  See [Smart limits and warmup](/kb/smart-limits-and-warmup).
* `POST /api/linkedin-account-snapshots/search` gives the health timeline the platform
  records for the account.

## 4. First action

Once `active`, the account's sid (`ln_ac_...`) is the handle every LinkedIn endpoint
takes. A sensible first write is something low-risk, for example reacting to a post,
before you schedule real outreach through a
[mass action](/guides/run-a-mass-action) with pacing.

Every outbound call re-checks the smart limits server-side before dispatch. Hitting a
budget answers `limit_exceeded`, and the action can resume the next day or after the
limit is raised; the account is not penalized for your retry logic.

## If the connection fails

* The browser must be **running** and the LinkedIn tab reachable: a stopped or faulted
  browser cannot bind an account.
* Check the proxy: a dead or blocked proxy prevents LinkedIn from loading. Run the
  connectivity check in the browser drawer
  ([how](/kb/antidetect-browsers-and-proxies#diagnose-a-proxy)).
* If the account was connected on another team, disconnect it there first.
* A browser nobody signs in on is deleted after 30 days
  ([details](/kb/antidetect-browsers-and-proxies#browser-lifecycle)). If yours is gone,
  click **Connect account** again: a new browser is created.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.