Connect Account

Connect a channel account to start using the API

POST /v2/login

Connect Account

cURL

curl --request POST \
  --url https://api.linkupapi.com/v2/login \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "platform": "<string>",
  "email": "<string>",
  "password": "<string>",
  "login_token": "<string>",
  "phone_number": "<string>",
  "country": "<string>",
  "account_name": "<string>",
  "challenge_type": "<string>",
  "sales_nav": true,
  "account_id": "<string>",
  "proxy": {}
}
'

Connected Successfully

{
  "success": true,
  "data": {
    "account_id": "69c127c37cae0494dd827286",
    "platform": "linkedin",
    "status": "connected"
  },
  "metadata": {
    "action": "login",
    "credits_consumed": 1,
    "timestamp": "2025-01-15T10:30:00.000000"
  }
}

Connect a new channel account (LinkedIn, WhatsApp, etc.) to your API key. Once connected, you receive an account_id to use in all subsequent requests.

This endpoint costs 1 credit per request. Ignore this if you’re on per-seat pricing: usage is unlimited.

Header Parameters

x-api-key · string · required

Your API key

Body Parameters

platform · string · required

The channel platform to connect. Available: linkedin, whatsapp, email. Optional in the one case below where you pass an existing account_id to activate a premium seat — the account already carries its platform. For email, see Email mailbox below.

email · string

Account email address (required for credential-based login)

password · string

Account password (required for credential-based login)

login_token · string

Authentication token/cookie for direct token-based connection. Alternative to email+password.

phone_number · string

WhatsApp only. The number to link, e.g. [phone]. Sets the proxy country when country is not given.

country · string · default: "FR"

Country code for proxy selection. Available: US, UK, FR, DE, NL, IT, IL, CA, BR, ES, IN

account_name · string

Optional display name for the account. Defaults to the email address.

challenge_type · string · default: "code_challenge"

Type of 2FA challenge to use if the account has two-factor authentication enabled.

• code_challenge — receive a verification code via email, SMS, or authenticator app. You must then submit the code via /v2/checkpoint.
• app_challenge — confirm the login directly from the platform’s mobile app. No code needed — just call /v2/checkpoint with the account_id after approving on the app.

This is a preference, LinkedIn may impose another method: check checkpoint_type in the response.

sales_nav · boolean · default: false

Also activate the account’s Sales Nav seat during login (requires the account to hold a Sales Nav license). No extra credential is needed — the seat is derived from the existing session. See Sales Nav below.

account_id · string

Pass an existing account’s id together with sales_nav: true to activate a Sales Nav seat on an already-connected account (e.g. bought after connecting) — no re-login, no credential, and no credit. When set, no other login parameter is required.

proxy · string | object

LinkedIn only. Your own HTTP(S) proxy for this account — the login and every later request go through it. See Custom proxy below.

Response

success · boolean

Whether the request was successful

data · object

Show Properties

account_id · string

The unique identifier for the connected account. Use this in all future requests.

platform · string

The platform that was connected

status · string

Account status: connected (ready to use) or checkpoint_required (needs 2FA verification)

message · string

Additional information (present when checkpoint is required)

checkpoint_type · string

Where the code went, when checkpoint_required: email, sms, authenticator_app, app_approval or code.

sent_to · string

Masked destination when LinkedIn shows it, e.g. phone number ending with 23.

sales_nav · object

Present when sales_nav: true was requested. { "connected": true, "contract_id": "...", "seat_id": "..." } on success, or { "connected": false, "error": "..." } if no seat could be activated. When the login returns checkpoint_required, this is { "pending": true } and the seat is activated once the checkpoint completes.

proxy · object

Present when proxy was given: { "mode": "custom", "host": "...", "port": 8080 }.

Connected Successfully

{
  "success": true,
  "data": {
    "account_id": "69c127c37cae0494dd827286",
    "platform": "linkedin",
    "status": "connected"
  },
  "metadata": {
    "action": "login",
    "credits_consumed": 1,
    "timestamp": "2025-01-15T10:30:00.000000"
  }
}

Login Methods

There are two ways to connect an account:

1. Credential-based login — provide email + password. If 2FA is enabled, you’ll receive a checkpoint_required status and need to call /v2/checkpoint.

2. Token-based login — provide a login_token directly. No 2FA step needed.

Email mailbox

Connect a mailbox with platform: "email" and a provider:

• gmail_oauth / m365_oauth — OAuth. Two steps: this call returns status: "checkpoint_required" + an authorization_url; redirect the user there, then submit the returned code to /v2/checkpoint. By default LinkupAPI’s own OAuth app is used — pass oauth_client_id + oauth_client_secret in params to use your own.
• smtp_generic — IMAP/SMTP. Verified and connected in one call (no checkpoint).

The mailbox address is the top-level email field (the same one used for credential login), and its display name the top-level account_name. Everything else goes in params: optional daily_limit (default 40); redirect_uri for OAuth; smtp { host, port, password } (+ optional imap { host, port }) for SMTP. Tip: call /v2/email/autoconfig first to get the right provider and server settings. Connecting a mailbox is free.

OAuth (step 1)

{
  "platform": "email",
  "provider": "gmail_oauth",
  "email": "[e-mail]",
  "params": { "redirect_uri": "https://yourapp.com/oauth/email/callback" }
}

SMTP (one call)

{
  "platform": "email",
  "provider": "smtp_generic",
  "email": "[e-mail]",
  "params": {
    "smtp": { "host": "smtp.company.com", "port": 587, "password": "app-password" },
    "imap": { "host": "imap.company.com", "port": 993 }
  }
}

Common failures return the standard error envelope: an address with no Gmail mailbox or a rejected SMTP login → CHANNEL_ERROR (422); an expired/reused code → INVALID_PARAMS (400); denied consent → FORBIDDEN (403). A failed attempt leaves no leftover account.

WhatsApp

1. platform: "whatsapp" + phone_number → checkpoint_required with a QR code (qr_code_image)
2. Scan it on the phone: WhatsApp › Settings › Linked devices › Link a device
3. Poll /v2/checkpoint with the account_id every few seconds → current QR, then connected

• The QR refreshes every ~20 s and expires after 3 min: /v2/checkpoint with resend: true gives a new one
• Can’t scan (QR shown on the same phone)? Pass params.pairing_code: true: you get an 8-character pairing_code to type on the phone instead (Link a device › Link with phone number instead)
• Free

WhatsApp

{ "platform": "whatsapp", "phone_number": "[phone]" }

Sales Nav

The Sales Nav seat is derived from the account’s existing session — there is no separate login. There are two ways to activate it:

1. At login — pass sales_nav: true alongside your credentials or login_token. The seat is activated in the same request.
2. On an already-connected account — pass account_id + sales_nav: true (no credential, no credit). Ideal when the user buys Sales Nav after connecting.

The seat is attached to the account and renewed automatically when it expires. Activating a seat never breaks an otherwise-successful login: if the account has no Sales Nav license, you still get status: connected with sales_nav.connected: false.

Connected + Sales Nav

{
  "success": true,
  "data": {
    "account_id": "69c127c37cae0494dd827286",
    "platform": "linkedin",
    "status": "connected",
    "sales_nav": {
      "connected": true,
      "contract_id": "2016220713",
      "seat_id": "1545550052"
    }
  },
  "metadata": {
    "action": "login",
    "credits_consumed": 1,
    "timestamp": "2025-01-15T10:30:00.000000"
  }
}

Custom proxy

• proxy: http://user:pass@host:port, host:port:user:pass, host:port, or { "host", "port", "username", "password" }. HTTP(S) only
• tested before the login — unreachable proxy returns 400, no credit
• kept for later re-logins. Change it with Set Custom Proxy, remove it with Remove Custom Proxy

Notes

• The account_id returned is permanent — store it and reuse it for all API calls
• If you receive checkpoint_required, use the /v2/checkpoint endpoint to complete verification
• The country parameter determines which proxy is used for the connection