For a pending CAPTCHA (or a LinkedIn page with nothing to type) on a sender our own LinkedIn gateway runs, i.e. when checkpoint.liveView is true. Returns a single-use websocket URL, valid about ten minutes, streaming the sign-in browser: the server sends JSON text frames {"type":"frame","data":"<base64 JPEG>","meta":{"deviceWidth":…}} and {"type":"state","state":"live|finishing|ended","result":…}; the client sends {"type":"mouse","action":"mousePressed|mouseReleased|mouseMoved","x":…,"y":…}, {"type":"wheel","x":…,"y":…,"dx":…,"dy":…}, {"type":"key","key":…,"code":…,"keyCode":…} or {"type":"text","text":…}. Coordinates are in the page's pixels (scale by meta.deviceWidth). When LinkedIn accepts the step the sender connects as usual (account.connected). Most integrators send their user to the hosted connect page instead, which shows this view itself. 409 with live_view_unavailable when there is no browser step to show, live_view_not_ready while the sign-in is still running (retry in a minute), and live_view_expired once it is no longer waiting.
Authorization
bearerAuth An API key created on the Access tokens page.
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/accounts/string/live-view"{ "data": { "url": "string", "expiresAt": "2019-08-24T14:15:22Z" }}Connect a sender POST
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.
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 (400 `seat-limit-reached`, or `no-plan` without an active plan) rather than at the end of the person's sign-in. It is checked, not reserved; a workspace whose seats are added on demand is not refused. 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. The exception is a change of sign-in method (a browser-session sender signing back in with a password, or the reverse): the sender then comes back under a new id, its campaign pools move to it and the old one is removed, so read the id from `account_id` on the redirect. An `accountId` that is not a sender in the workspace is a 400 with `code: account-not-found`. A failed sign-in attempt does not end the link: the person can try again until it expires or they cancel, and each attempt LinkedIn refuses fires account.connection_failed. 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.