Connect a sender | Swarmhit Developers

JavaScript SDK: swarmhit.accounts.connect(params)

Connect a LinkedIn sender with its email/username and password; optionally a proxy and country. The sender lands in the effective workspace (the one named by the X-Swarmhit-Workspace header, if set), consuming a seat from its allocation. Credentials are stored encrypted and never returned. The outcome and later changes arrive via the account.* webhooks.

To connect a sender without ever handling their password, create a hosted connect link instead (POST /accounts/hosted-link) and send the person to it.

A sender can also be connected from an existing browser session: send liAt (the LinkedIn session cookie value) and the userAgent of the browser it came from, instead of username / password. The session is stored encrypted and connectionMethod is cookie; checkpoints and webhooks behave the same. A browser session cannot re-establish itself, so these senders never reconnect on their own: repair one by POSTing a fresh liAt to POST /accounts/{id}/reconnect. Password sign-in with a totpSecret is the lower-maintenance path. proxy and country may accompany liAt exactly as they do a password sign-in, and a reconnect keeps the sender's stored proxy unless it sends a new one.

Add a 2FA setup key (totpSecret) for automatic (infinite) login: the sign-in then completes hands-free, solving a 2FA challenge from the secret. Anything else fails with 400 and an account.connection_failed webhook rather than leaving a half-connected sender holding a seat.

Without a totpSecret the connect is interactive. If LinkedIn asks for a verification step the response is 200 with status checkpoint_required and a checkpoint object describing it; answer it on POST /accounts/{id}/checkpoint within five minutes. An account.checkpoint_required webhook fires at the same time.

On failure the error body carries a stable error.code to branch on and a plain-language error.message describing what went wrong. Codes for this endpoint: invalid-credentials (wrong email/password), invalid-session (the liAt browser session was rejected; copy a fresh one), rate-limited (LinkedIn is throttling sign-in; retry later), proxy-failed (the proxy sent with the request did not respond, so the sign-in never reached LinkedIn), country-unavailable (accounts in the requested country cannot be connected at the moment; pick a nearby country), provider-timeout / provider-unreachable (LinkedIn answered too slowly, or could not be reached at all; safe to retry), checkpoint-code-rejected (the account's 2FA setup key is wrong, so the authenticator code is rejected), checkpoint-restricted (LinkedIn has restricted the account; clear it on linkedin.com and connect again), account-restricted (the same, found at sign-in, before any verification step), sign-in-in-progress (a sign-in for this account is already running; finish it or wait a few minutes), unsupported-verification (automatic login was requested but the account signs in with a method other than authenticator 2FA — connect it without a totpSecret and answer the challenge instead), verification-required / verification-failed (a verification step that can't be completed automatically), invalid-totp-secret (the 2FA key isn't a valid authenticator key), already-connected, no-plan, and seat-limit-reached, and connection-failed for anything else, where error.message carries the specific reason. Every one of them is a 400. When the attempt reached LinkedIn, the account.connection_failed webhook carries the same code; refusals made before signing in (invalid-totp-secret, no-plan, seat-limit-reached, and already-connected for a password sign-in) come back on the response only.

Authorization

bearerAuth

AuthorizationBearer <token>

An API key created on the Access tokens page.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Either a password sign-in (username + password) or a browser session (liAt). Sending liAt selects the browser-session connect and the password fields are not required.

username?string

LinkedIn account email/username. Required unless liAt is sent.

password?string

LinkedIn account password (stored encrypted; never returned). Required unless liAt is sent.

liAt?string

The li_at cookie value from a browser already signed in to LinkedIn. Connects the sender from that session instead of a password; stored encrypted and never returned.

userAgent?string

The User-Agent of the browser the liAt came from. LinkedIn ties a session to it, so sending the real one keeps the session alive longer. Only used with liAt.

browser?

Optional, with liAt: what the browser the session came from tells a page, read with JavaScript in that same browser (the one whose userAgent is sent). Requests made with the session then carry the same client hints, languages and clock as that browser. Anything missing or malformed is derived from the userAgent and the sender's country, so a partial object is fine.

totpSecret?string

Optional 2FA authenticator setup key. With it the sign-in completes automatically (infinite login) and reconnects on its own later; without it a verification step comes back as a checkpoint to answer.

country?|

Two-letter code of the country the account is normally used from; the sender connects from there. Optional and never required: without it (and without a proxy), a location is chosen for the sender. On a managed connection that is the most common country among the workspace's senders, else the country of the IP calling the API, else the United States. That IP is your server's, not the member's, so passing country is still best, above all for a workspace's first sender.

proxy?|

Proxy the sender's LinkedIn session should egress through, as { host, port, username?, password? }. Applies to both sign-in modes: a password sign-in and a browser-session (liAt) connect. The password is stored encrypted and never returned.

Response Body

`application/json`

curl -X POST "https://example.com/accounts" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "string",    "label": "string",    "senderId": "string",    "fullName": "string",    "firstName": "string",    "lastName": "string",    "headline": "string",    "publicIdentifier": "string",    "profileUrl": "string",    "profilePicture": "string",    "connectionMethod": "cookie",    "connectedVia": "app",    "hostedLinkId": "string",    "status": "active",    "connectionStatus": "string",    "isVerified": true,    "isPremium": true,    "linkedinPlan": "classic",    "error": "string",    "limits": {},    "usage": {},    "paused": true,    "pausedReason": "user",    "pausedAt": "2019-08-24T14:15:22Z",    "cooldownUntil": "2019-08-24T14:15:22Z",    "cooldownReason": "invite_daily_limit",    "checkpoint": {      "type": "2FA",      "input": "code",      "requestedAt": "2019-08-24T14:15:22Z",      "expiresAt": "2019-08-24T14:15:22Z",      "expired": true,      "canResend": true,      "canTryAnotherWay": true,      "liveView": true    },    "inmailCredits": {      "balance": 0,      "syncedAt": "2019-08-24T14:15:22Z"    },    "ssi": {      "score": 0,      "brand": 0,      "people": 0,      "insights": 0,      "relationships": 0,      "industryTop": 0,      "networkTop": 0,      "industryAverage": 0,      "networkAverage": 0,      "industryName": "string",      "unavailable": true,      "syncedAt": "2019-08-24T14:15:22Z"    },    "country": "string",    "stoppedReason": "proxy_drift",    "connection": {      "country": "string",      "isp": "string",      "changedAt": "2019-08-24T14:15:22Z"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "status": "connected",  "checkpoint": {    "type": "2FA",    "input": "code",    "requestedAt": "2019-08-24T14:15:22Z",    "expiresAt": "2019-08-24T14:15:22Z",    "expired": true,    "canResend": true,    "canTryAnotherWay": true,    "liveView": true  }}

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`