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), 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), 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 (409), and connection-failed for anything else, where error.message carries the specific reason. The same code is included on the account.connection_failed webhook.
Authorization
bearerAuth An API key created under Settings → API & Webhooks.
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.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/accounts" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "string", "label": "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": "string", "checkpoint": { "type": "2FA", "input": "code", "requestedAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "expired": true, "canResend": true, "canTryAnotherWay": 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", "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 }}Overview
REST API reference for Swarmhit.
Create a hosted connect link POST
Mint a one-time URL where a person connects their own LinkedIn account on a page Swarmhit serves, so your product never handles their LinkedIn password. Send them to `url`; they sign in, clear any verification step LinkedIn raises, and are redirected back to your `redirectUrl`. The sender lands in the effective workspace (the one named by the X-Swarmhit-Workspace header, if set) and consumes a seat from its allocation. The seat is checked when the link is created, so a full workspace fails here rather than at the end of the person's sign-in. The page carries your organization's name and picture by default; both can be overridden, and a default return URL set, in your organization settings — so `redirectUrl` only has to be sent when a particular link should land somewhere else. With `accountId` the link REPAIRS that sender instead of adding one: it keeps its id, its campaigns and its seat, and no seat is consumed. You learn the outcome three ways, and can use any of them: the redirect back carries `?hosted_link_id=&status=connected|failed|expired|cancelled &account_id=&external_id=`; the account.connected / account.connection_failed webhooks carry `hostedLinkId` and `externalId`; and GET /accounts/hosted-link/{id} returns the current state. `url` is returned once, here — the token inside it is stored only as a hash and cannot be read back.