> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkupapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Connection Link

> Let your users connect their LinkedIn, WhatsApp or email account on a page hosted by LinkupAPI, so their credentials never reach your servers

Generate a single-use link and hand it to your user. They connect their account on `app.linkupapi.com` (LinkedIn sign-in and 2FA, WhatsApp QR or pairing code, Google / Microsoft consent or SMTP settings), and you only receive the resulting `account_id`. Your app never sees or handles the credentials.

<Note>
  The link itself is free. A LinkedIn login through it costs **1 credit**, like [Connect Account](/api-reference/v2/accounts/login); WhatsApp and email are free. Ignore this if you're on per-seat pricing.
</Note>

**Flow**

1. Your backend calls this endpoint and gets a `url`.
2. Your app sends the user to that `url` (full redirect or new tab, never an iframe).
3. The user picks a channel (if you offered several) and connects it on our page, verification included.
4. We POST the outcome to your `notify_url` and send the user to your `success_url`. You can also poll [Get Connection Link](#get-connection-link) or [List Accounts](/api-reference/v2/accounts/list-accounts).

Links are single-use: generate a new one each time a user starts a connection.

### Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key
</ParamField>

### Body Parameters

<ParamField body="platforms" type="string | string[]" default="*">
  Channels the page offers: `linkedin`, `whatsapp`, `email`, or `*` for all. With a single value the page skips the chooser. `platform` works as a shorthand for one value.
</ParamField>

<ParamField body="name" type="string">
  Your own reference for this user (max 200 characters), echoed in the `notify_url` payload so you can match the new account to your user.
</ParamField>

<ParamField body="expires_in" type="integer" default="3600">
  Link lifetime in seconds, from 60 to 604800 (7 days).
</ParamField>

<ParamField body="country" type="string">
  LinkedIn and WhatsApp: lock the proxy country (same codes as [Connect Account](/api-reference/v2/accounts/login)). Omit to let the user pick it on the page.
</ParamField>

<ParamField body="account_id" type="string">
  Reconnect an existing account instead of creating one. The page only offers that account's channel and pre-fills its email; the account keeps its id, its country and its webhooks.
</ParamField>

<ParamField body="account_name" type="string">
  Display name of the account once connected. Defaults to the email.
</ParamField>

<ParamField body="success_url" type="string">
  Where to send the user once the account is connected. Omit to show our confirmation screen.
</ParamField>

<ParamField body="failure_url" type="string">
  Where to send the user if they open the link after it expired or was used.
</ParamField>

<ParamField body="notify_url" type="string">
  HTTPS endpoint we POST to once the account is connected. See [Callback](#callback).
</ParamField>

### Response

<ResponseField name="data.link_id" type="string">
  Id of the link, for [Get Connection Link](#get-connection-link).
</ResponseField>

<ResponseField name="data.url" type="string">
  The page to send your user to.
</ResponseField>

<ResponseField name="data.expires_at" type="string">
  ISO 8601 UTC expiry of the link.
</ResponseField>

### Callback

When the account is connected we POST this JSON to `notify_url`, with a `X-Linkup-Link-Id` header. We retry twice (after 5 s and 30 s) if your endpoint doesn't answer 2xx.

```json theme={null}
{
  "status": "CREATION_SUCCESS",
  "account_id": "6acf60d12e999f4a3534cfcb",
  "platform": "linkedin",
  "name": "user_12345",
  "link_id": "6ad01a9b2e999f4a3534d001"
}
```

`status` is `RECONNECTED` when the link was created with an `account_id`. The callback is not signed: confirm it with [Get Account](/api-reference/v2/accounts/get-account) before trusting it.

### Get Connection Link

`GET /v2/accounts/connect-link/{link_id}` returns the link's `status` (`pending`, `checkpoint` while the user is completing a verification, `used`, `expired`), the `platform` chosen, its `account_id` once connected, and `notified` when a `notify_url` was set.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.linkupapi.com/v2/accounts/connect-link \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "platforms": ["linkedin", "email"],
      "name": "user_12345",
      "country": "FR",
      "success_url": "https://yourapp.com/linkedin/connected",
      "notify_url": "https://yourapp.com/webhooks/linkup"
    }'
  ```

  ```python Python theme={null}
  import requests

  r = requests.post(
      "https://api.linkupapi.com/v2/accounts/connect-link",
      headers={"x-api-key": "YOUR_API_KEY"},
      json={
          "platforms": ["linkedin", "email"],
          "name": "user_12345",
          "country": "FR",
          "success_url": "https://yourapp.com/linkedin/connected",
          "notify_url": "https://yourapp.com/webhooks/linkup",
      },
  )
  print(r.json()["data"]["url"])
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "link_id": "6ad01a9b2e999f4a3534d001",
      "url": "https://app.linkupapi.com/connect/K3sX9...",
      "expires_at": "2026-10-14T16:00:00Z",
      "platforms": ["linkedin", "email"],
      "name": "user_12345",
      "reconnect": null
    },
    "metadata": {
      "action": "connect_link",
      "credits_consumed": 0
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.