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,
  "recruiter": true,
  "products": [
    "<string>"
  ],
  "allow_product_selection": true,
  "choose_contract": true,
  "contract_id": "<string>",
  "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, CA, MX, CR, BR, AR, CL, CO, FR, UK, DE, NL, ES, IT, PT, BE, CH, AT, IE, SE, DK, FI, LT, LV, EE, PL, CZ, SK, HU, RO, UA, SI, HR, RS, AL, GR, CY, TR, IL, AE, EG, ZA, IN, PK, BD, JP, SG, MY, ID, TH, PH, AU

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.

recruiter · boolean · default: false

Connect the LinkedIn Recruiter (Lite) seat of an already-connected account. Needs account_id + email + password. See Recruiter seat below.

products · string[]

What to open with this login: classic, sales_navigator, recruiter. classic is always included. With recruiter, one login and one 2FA open the account and its Recruiter seat. See Recruiter seat.

allow_product_selection · boolean · default: false

Let the user choose. After the login you get checkpoint_type: "product_selection" with the products the account holds. See Choosing products and contracts.

choose_contract · boolean · default: false

If the account holds several Sales Nav or Recruiter contracts, return them instead of picking one (checkpoint_type: "contract_selection").

contract_id · string

Open the seat on this contract. Remembered for later reconnections.

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. With recruiter: true, the LinkedIn account the Recruiter seat is opened from.

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.

checkpoint_message · string

Ready-to-display sentence for your user, built from checkpoint_type and sent_to, e.g. LinkedIn sent a verification code to the phone number ending with 23. message keeps its generic wording.

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.

recruiter · object

Present when products includes recruiter. { "connected": true, "contract_id": "...", "seat_id": "..." }, or { "connected": false, "error": "..." }. { "pending": true } while a 2FA is pending.

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. For OAuth the address is optional: without it the user picks the mailbox on the provider’s consent screen and the account takes that address. 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]" }

iMessage

An iMessage line is a dedicated US or UK number. It is not connected with /v2/login: buy it from the dashboard (Plans or Account connection), $199 per line per month. Once active, it appears in List Accounts with platform: "imessage" and works with the same message endpoints and webhooks. Sending rules: iMessage limits.

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"
  }
}

Recruiter seat

Recruiter actions use the LinkedIn account’s account_id.

New account — one login opens both:

Request

{ "platform": "linkedin", "email": "[e-mail]", "password": "••••••", "products": ["classic", "recruiter"] }

Already-connected account — pass its account_id, recruiter: true, email and password. No password needed if it was connected with products.

• One 2FA at most. Answer it with /v2/checkpoint
• The seat’s events arrive on the account’s webhook, with "product": "recruiter"
• The seat and the account disconnect independently. Reconnect the seat with recruiter: true
• No Recruiter licence → recruiter.connected: false (NO_RECRUITER_LICENSE with recruiter: true)
• The seat itself is free and never billed as an extra account

Response

{
  "success": true,
  "data": {
    "account_id": "69c127c37cae0494dd827286",
    "platform": "linkedin",
    "status": "connected",
    "recruiter": { "connected": true, "contract_id": "347818991", "seat_id": "1612550011" }
  },
  "metadata": { "action": "login", "credits_consumed": 1, "timestamp": "2026-10-15T10:30:00.000000" }
}

Choosing products and contracts

Some accounts hold several products or contracts. Let the user pick:

• allow_product_selection: true → checkpoint_type: "product_selection" with products. Answer with code: "classic,recruiter"
• choose_contract: true → checkpoint_type: "contract_selection" with contracts. Answer with code: "<contract id>"

Both answers go to /v2/checkpoint with the account’s account_id.

To change contract later:

• GET /v2/accounts/{account_id}/contracts?product=recruiter lists them (selected marks the current one)
• POST /v2/accounts/{account_id}/contracts/{contract_id}/select?product=recruiter switches. No password

Use product=sales_navigator for Sales Nav.

Contract choice

{
  "success": true,
  "data": {
    "account_id": "69c127c37cae0494dd827286",
    "status": "checkpoint_required",
    "checkpoint_type": "contract_selection",
    "product": "recruiter",
    "contracts": [
      { "id": "338091421", "name": "Acme Inc. - Recruiter" },
      { "id": "347818991", "name": "Recruiter Lite" }
    ]
  }
}

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