Connection Sessions

A connection session is a short-lived link that opens the Linked API connection page, where the end user logs into LinkedIn. Use it to connect a new account or to reconnect one whose LinkedIn session has expired. For the accounts themselves, see Accounts.

accounts.createConnectionSession

Create a new connection session to connect a LinkedIn account. Returns a link that opens the connection page where the user logs into LinkedIn.

curl -X POST https://api.linkedapi.io/admin/accounts.createConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"

Body:

The body is optional. Send no body at all to get the default behavior, or pass completion to control what the user sees after a successful connection – see Customizing the completion screen.

Response:

{
  "success": true,
  "result": {
    "sessionId": "990eef7a-...",
    "connectionLink": "https://app.linkedapi.io/connection/990eef7a-..."
  }
}

Errors:

Flow: Create session → open connectionLink → user logs into LinkedIn → poll accounts.getConnectionSession until status is success → account appears in accounts.getAll.

accounts.createReconnectionSession

Create a new reconnection session for an account whose status is reconnection_required. If the account already has an active reconnection session, it is cancelled and replaced with a new one. If an in-progress reconnection session is applying a pending proxy change, Linked API returns that existing session instead so the proxy change state is preserved.

curl -X POST https://api.linkedapi.io/admin/accounts.createReconnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{"accountId": "a91c20f8-..."}'

Body:

Response:

{
  "success": true,
  "result": {
    "reconnectionSessionId": "d90ac1f6-...",
    "reconnectionLink": "https://app.linkedapi.io/connection/d90ac1f6-..."
  }
}

Errors:

Flow: Create reconnection session → open reconnectionLink → user logs into LinkedIn → poll accounts.getConnectionSession with reconnectionSessionId until status is success.

accounts.getConnectionSession

Check the status of a connection session.

curl -X POST https://api.linkedapi.io/admin/accounts.getConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{"sessionId": "990eef7a-..."}'

Body:

Response:

{
  "success": true,
  "result": {
    "session": {
      "sessionId": "990eef7a-...",
      "status": "pending",
      "type": "initial"
    }
  }
}

Session statuses:

accounts.cancelConnectionSession

Cancel an active connection session.

curl -X POST https://api.linkedapi.io/admin/accounts.cancelConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{"sessionId": "990eef7a-..."}'

Body:

Response:

{
  "success": true,
  "result": {}
}

Customizing the completion screen

After the user finishes logging into LinkedIn, the connection page shows a completion screen. The optional completion object accepted by accounts.createConnectionSession and accounts.createReconnectionSession controls what happens there – which is what you need when the connection page is embedded into your own product. Every field is optional, and omitting completion entirely keeps the default behavior.

{
  "completion": {
    "limits": { "mode": "ask" },
    "button": { "text": "Back to Acme", "url": "https://app.acme.com/accounts" },
    "successUrl": "https://app.acme.com/connected?session={SESSION_ID}",
    "failureUrl": "https://app.acme.com/failed?session={SESSION_ID}"
  }
}

Limits modes:

Default button: sessions created through this API do not show the "Continue to platform" button, because it leads to the Linked API dashboard, which your users have no access to. Instead, the completion screen tells the user the account is connected and the tab can be closed. To send the user somewhere, pass either button (they leave by clicking) or successUrl (they leave immediately). Passing both is rejected: with an instant redirect the button would never be visible.

Placeholders: successUrl and failureUrl may contain placeholders that are substituted before the redirect. Values are URL-encoded.

Any other placeholder, an unbalanced brace, or a non-https URL is rejected with invalidRequestPayload when the session is created – not later, when the user is already on the page.

When the redirect happens:

• successUrl fires after the limits step. With mode: "ask" that means after the user saves or skips the limits editor; with defaults or skip it fires as soon as the connection succeeds.
• failureUrl covers the error and expired statuses. Sessions you cancel yourself through accounts.cancelConnectionSession do not redirect, and neither does an invalid or unknown session link, since there is no configuration to read for it.

Do not rely on the redirect for fulfillment. The user may close the tab or lose connectivity before it happens. Treat arriving on successUrl as a hint and confirm the real outcome with accounts.getConnectionSession.

Examples:

Fully embedded – no questions asked, the user is returned to your product in both outcomes:

curl -X POST https://api.linkedapi.io/admin/accounts.createConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "completion": {
      "limits": { "mode": "defaults" },
      "successUrl": "https://app.acme.com/connected?session={SESSION_ID}&account={ACCOUNT_ID}",
      "failureUrl": "https://app.acme.com/failed?session={SESSION_ID}&error={ERROR_TYPE}"
    }
  }'

Keep the limits editor, but finish with your own button instead of an automatic redirect:

curl -X POST https://api.linkedapi.io/admin/accounts.createConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "completion": {
      "limits": { "mode": "ask" },
      "button": { "text": "Back to Acme", "url": "https://app.acme.com/accounts" }
    }
  }'