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.
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.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/accounts/hosted-link" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "string", "status": "pending", "channel": "linkedin", "provider": "google", "url": "string", "workspaceId": "string", "accountId": "string", "reconnectAccountId": "string", "externalId": "string", "redirectUrl": "string", "hasProxy": true, "country": "string", "error": { "code": "string", "message": "string" }, "expiresAt": "2019-08-24T14:15:22Z", "openedAt": "2019-08-24T14:15:22Z", "completedAt": "2019-08-24T14:15:22Z", "createdAt": "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), `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.
Disconnect a sender DELETE
Disconnect a LinkedIn sender account: revoke its session, remove it from the workspace and free its seat. The inverse of connecting a sender (POST /accounts). Permanent: reconnecting later means connecting the sender again.