Create a hosted connect link | Swarmhit Developers

JavaScript SDK: swarmhit.accounts.hostedLinks.create(params)

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.

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.

redirectUrl?string

Absolute http(s) URL the person is sent back to when they finish, cancel, or the link expires. Optional when your organization has a default return URL set in its settings; passing one here overrides that default for this link. Required when there is no default, and the call fails with 400 invalid-redirect-url if neither exists.

accountId?string

Reconnect mode: the existing sender this link repairs. It keeps its id, campaigns and seat, and no seat is consumed.

externalId?string

Your own opaque id for this session, echoed back on the redirect and on the account.connected / account.connection_failed webhooks.

proxy?|

Proxy the sender's LinkedIn session should egress through, as { host, port, username?, password? }. Set here rather than on the page: the person signing in is your customer and cannot reasonably be asked for one, and routing a sender near where its owner actually is matters for LinkedIn safety. The password is stored encrypted and never returned. Applies to both tabs of the connect page: a password sign-in and a browser-session one.

Organizations whose users DO run their own proxies can instead turn on a proxy panel on the connect page, in organization settings. A proxy sent here always wins and hides that panel.

country?string

2-letter country code for the session, never required. Set it here and the page stops asking the person for one; nor does it ask on a link that repairs a sender with a country, which keeps it. Left out, the page pre-selects the country the person opens it from, and a sender on a managed connection connected without one connects from there (when that can't be told, from the workspace's most common sender country, else the United States).

expiresIn?integer

How long the link stays usable, in seconds. Default 1800, minimum 300, maximum 604800. Single use either way.

Response Body

`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",    "providers": [      "google"    ],    "orderId": "string",    "purchase": {      "maxMailboxes": 0,      "contactProvided": true    },    "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"  }}

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`