> ## 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.

## 3. Check capabilities and limits

* `POST /api/linkedin-accounts/{sid}/check-sales-nav`, `/check-premium`,
  `/check-recruiter` report what the account's LinkedIn subscription actually supports.
  Sales Navigator endpoints on an account without Sales Navigator fail upfront with
  `validation_failed` 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.