Skip to main content
POST
Connect Account
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

string
required
Your API key

Body Parameters

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.
string
Account email address (required for credential-based login)
string
Account password (required for credential-based login)
string
Authentication token/cookie for direct token-based connection. Alternative to email+password.
string
WhatsApp only. The number to link, e.g. +33612345678. Sets the proxy country when country is not given.
string
default:"FR"
Country code for proxy selection. Available: US, UK, FR, DE, NL, IT, IL, CA, BR, ES, IN
string
Optional display name for the account. Defaults to the email address.
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.
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.
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.
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

boolean
Whether the request was successful
object

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)
SMTP (one call)
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

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.

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