Migration from V1 to V2

This guide walks you through every change needed to migrate your existing V1 integration to V2. The V2 API is fully backward-compatible in terms of data — the same data is returned, just in a standardized wrapper.

V1 will be deprecated. We recommend migrating to V2 as soon as possible. V1 endpoints will continue to work during the transition period, but all new features are V2-only.

A Claude Code skill is available in the webapp to automatically migrate your codebase from V1 to V2. Install it and run the migration directly from your terminal.

What Changed (TL;DR)

No more login_token

V1 required a login_token and country in every request. V2 replaces this with a single account_id.

One endpoint per category

V1 had a different URL for each action (e.g. /v1/profile/me, /v1/profile/info). V2 uses one URL per category with an action field in the body.

Standardized responses

V1 responses varied between endpoints. V2 always returns success, data/error, and metadata — no more guessing the format.

Proper HTTP status codes

V1 returned 200 for most errors. V2 uses correct HTTP status codes (400, 402, 403, 404, 429, 500).

New in V2 Only

These features have no V1 equivalent — they are only available in V2:

Feature	Endpoint	Description
Webhooks for invitations	`POST /v2/webhooks` → `accepted_invitation`	Get notified in real-time when someone accepts your invitation
Account logs	`GET /v2/accounts/{id}`	Monitor account status, activity, and connection health
Simplified account management	`GET /v2/accounts`	List, inspect, and manage all connected accounts from a single endpoint
Hosted Webhooks	`POST /v2/webhooks` (no `url`)	Built-in SSE stream + polling — no server required
Webhook Event Filter	`POST /v2/webhooks` → `events`	Subscribe to specific event types only

Step-by-Step Migration

Step 1 — Connect Your Account

In V1, you obtained a login_token from /v1/auth/login and passed it in every request along with country. In V2, you connect your account once and receive a persistent account_id.

Option A: Fresh login
Option B: Import existing V1 token

POST /v2/login
{
  "platform": "linkedin",
  "login_token": "your_existing_v1_token",
  "country": "FR"
}
// → { "data": { "account_id": "69c127...", "status": "connected" } }

Save the account_id — you’ll use it in all V2 requests. You no longer need to store or manage login_token or country.

If the response returns "status": "checkpoint_required", call POST /v2/checkpoint with the verification code sent to your email. This replaces POST /v1/auth/verify.

Re-calling /v2/login with an already migrated token returns the same account_id — the call is idempotent and free.

Batch Migration (SaaS with many accounts)

If you have hundreds of login_token values stored in your database, migrate them before changing code:

Add account_id and migration_status columns to your accounts table
Iterate all rows, call POST /v2/login with { "login_token": "...", "country": "..." } for each
Handle outcomes per row:
- connected → save account_id, mark migrated
- error (expired token) → mark failed, user must re-auth
Add 0.5–2s random delay between calls
Switch code to use account_id only after batch is complete
Drop login_token / country columns once V2 is fully deployed

Step 2 — Update Request Format

Every V2 action endpoint uses the same structure:

POST /v2/{category}
{
  "account_id": "69c127c37cae0494dd827286",
  "action": "action_name",
  "params": {
    "key": "value"
  }
}

What to change in your code:

Remove login_token and country from every request body
Add account_id at the root level
Add action to specify what to do
Move all other parameters inside a params object
Rename linkedin_url → profile_url, message → message_text (send message)
Convert search filters from strings to arrays (see below)

V1 (before)
V2 (after)

POST /v1/profile/info
{
  "login_token": "AQED...",
  "country": "FR",
  "linkedin_url": "https://www.linkedin.com/in/example"
}

POST /v2/profiles
{
  "account_id": "69c127c37cae0494dd827286",
  "action": "get",
  "params": {
    "profile_url": "https://www.linkedin.com/in/example"
  }
}

In V1, multi-value search filters used semicolons or commas as separators. In V2, pass proper arrays. This applies to search_people and search_companies — affected parameters: location, company_url, school_url, industry, network, past_company, sector, company_size.

V1 (before)
V2 (after)

{
  "keyword": "CTO",
  "location": "Paris;London;New York",
  "network": "F,S"
}

{
  "keyword": "CTO",
  "location": ["Paris", "London", "New York"],
  "network": ["F", "S"]
}

Single values still work as plain strings — you only need arrays when passing multiple values.

Step 3 — Update Response Parsing

V1 responses had inconsistent formats across endpoints. V2 unifies everything:

Success: { "success": true, "data": { ... }, "metadata": { "action", "account_id", "credits_consumed", "timestamp" } }
Error: { "success": false, "error": { "code": "...", "message": "..." }, "metadata": { ... } }

What to change:

data["status"] == "success" → data["success"] == True
Errors: use data["error"]["code"] and data["error"]["message"]
metadata.credits_consumed is always present — use it for credit tracking
Remove any per-endpoint parsing workarounds

Step 4 — Update Error Handling

V2 uses real HTTP status codes — V1 returned 200 for almost everything.

Code	HTTP Status	What To Do
`INVALID_API_KEY`	403	Check your API key
`INVALID_ACCOUNT`	404	Call `GET /v2/accounts` to list valid IDs
`ACCOUNT_INACTIVE`	403	Re-login via `POST /v2/login`
`INVALID_ACTION`	400	Check docs for valid actions
`INVALID_PARAMS`	400	Read `error.message` for details
`RATE_LIMITED`	429	Implement exponential backoff
`INSUFFICIENT_CREDITS`	402	Top up at app.linkupapi.com
`CHANNEL_ERROR`	varies	Retry or check the platform directly
`INTERNAL_ERROR`	500	Retry after a few seconds

Errors never consume credits in V2.

Step 5 — Migrate Webhooks

In V1, webhooks were standalone “webhook accounts” with their own login_token. In V2, webhooks are configurations attached to existing accounts.

V1 (before)
V2 (after)

POST /v1/webhooks/accounts
{
  "platform": "linkedin",
  "login_token": "AQED...",
  "webhook_url": "https://your-server.com/webhook",
  "country": "FR"
}

POST /v2/webhooks
{
  "account_id": "69c127c37cae0494dd827286",
  "url": "https://your-server.com/webhook",
  "events": ["message_received", "accepted_invitation"]
}

Key changes:

No more separate “webhook accounts” — reuse your existing account_id
webhook_url → url
Filter events with the events array: ["message_received", "accepted_invitation", "disconnection"]
Start/stop: /v1/webhooks/accounts/{id}/start → /v2/webhooks/{id}/start
Status: replace GET .../status with the is_active field on GET /v2/webhooks
New hosted mode: omit url to get a built-in SSE stream + polling endpoint (no server needed)

Complete Endpoint Mapping

Authentication

V1 Endpoint	V2 Endpoint
`POST /v1/auth/login`	`POST /v2/login`
`POST /v1/auth/verify`	`POST /v2/checkpoint`
—	`GET /v2/accounts` (new)
—	`GET /v2/accounts/{id}` (new)

Profiles

V1 Endpoint	V2 Action
`POST /v1/profile/me`	`POST /v2/profiles` → `get_me`
`POST /v1/profile/info`	`POST /v2/profiles` → `get`
`POST /v1/profile/contact`	`POST /v2/profiles` → `get_contact`
`POST /v1/profile/visit`	`POST /v2/profiles` → `visit`
`POST /v1/profile/search`	`POST /v2/profiles` → `search_people`
`POST /v1/companies/search`	`POST /v2/profiles` → `search_companies`
`POST /v1/companies/info`	`POST /v2/profiles` → `get_company`

Messages

V1 Endpoint	V2 Action
`POST /v1/messages/send-message`	`POST /v2/messages` → `send`
`POST /v1/messages/inbox`	`POST /v2/messages` → `list_inbox`
`POST /v1/messages/conversation`	`POST /v2/messages` → `get_conversation`

Network

V1 Endpoint	V2 Action
`POST /v1/network/connect`	`POST /v2/network` → `invite`
`POST /v1/network/accept-invitation`	`POST /v2/network` → `accept`
`POST /v1/network/connections`	`POST /v2/network` → `list_connections`
`POST /v1/network/invitations`	`POST /v2/network` → `list_invitations`
`POST /v1/network/sent-invitations`	`POST /v2/network` → `list_sent`
`POST /v1/network/withdraw`	`POST /v2/network` → `withdraw`
`POST /v1/network/invitation-status`	`POST /v2/network` → `check_invitation`
`POST /v1/network/get-network-recommendations`	`POST /v2/network` → `recommendations`

Content & Posts

V1 Endpoint	V2 Action
`POST /v1/posts/create`	`POST /v2/content` → `create`
`POST /v1/posts/create-company`	`POST /v2/content` → `create_company`
`POST /v1/posts/search`	`POST /v2/content` → `search`
`POST /v1/posts/feed`	`POST /v2/content` → `get_feed`
`POST /v1/posts/like`	`POST /v2/content` → `like`
`POST /v1/posts/react`	`POST /v2/content` → `react`
`POST /v1/posts/comment`	`POST /v2/content` → `comment`
`POST /v1/posts/answer-comment`	`POST /v2/content` → `answer_comment`
`POST /v1/posts/repost`	`POST /v2/content` → `repost`
`POST /v1/posts/extract-comments`	`POST /v2/content` → `get_comments`
`POST /v1/posts/reactions`	`POST /v2/content` → `get_reactions`
`POST /v1/posts/time-spent`	`POST /v2/content` → `time_spent`

Recruiter

V1 Endpoint	V2 Action
`POST /v1/recruiter/posts`	`POST /v2/recruiter` → `get_posts`
`POST /v1/recruiter/get-candidate`	`POST /v2/recruiter` → `get_candidates`
`POST /v1/recruiter/cv`	`POST /v2/recruiter` → `get_cv`
`POST /v1/recruiter/publish`	`POST /v2/recruiter` → `publish_job`
`POST /v1/recruiter/close`	`POST /v2/recruiter` → `close_job`

Email / Enrichment

V1 Endpoint	V2 Action
`POST /v1/data/mail/finder`	`POST /v2/enrich` → `find_email`
`POST /v1/data/mail/reverse`	`POST /v2/enrich` → `reverse_email`
`POST /v1/data/mail/validate`	`POST /v2/enrich` → `validate_email`

Webhooks

V1 Endpoint	V2 Endpoint
`POST /v1/webhooks/accounts`	`POST /v2/webhooks`
`GET /v1/webhooks/accounts`	`GET /v2/webhooks`
`PUT /v1/webhooks/accounts/{id}`	`PUT /v2/webhooks/{id}`
`DELETE /v1/webhooks/accounts/{id}`	`DELETE /v2/webhooks/{id}`
`POST /v1/webhooks/.../start`	`POST /v2/webhooks/{id}/start`
`POST /v1/webhooks/.../stop`	`POST /v2/webhooks/{id}/stop`
`GET /v1/webhooks/.../status`	Check `is_active` on `GET /v2/webhooks`
—	`GET /v2/webhooks/{id}/stream` (new: SSE)
—	`GET /v2/webhooks/{id}/events` (new: polling)

Quick Migration Checklist

Connect your account

Call POST /v2/login with your credentials or existing V1 token to get an account_id.

Replace login_token with account_id

Remove login_token and country from all requests. Add account_id instead.

Update endpoint URLs

Replace individual V1 URLs with the V2 category endpoint + action field.

Wrap params

Move all action parameters inside the params object.

Rename parameters

linkedin_url → profile_url, message → message_text. Convert search filter strings to arrays.

Update response parsing

Check success (boolean) instead of status (string). Access data via data field.

Update error handling

Use HTTP status codes and error.code for programmatic error handling.

Migrate webhooks

Create webhook configs via POST /v2/webhooks with your existing account_id.

Need Help?

Full V2 reference: Introduction
Error codes: Error Codes
Best practices: Platform Best Practices
Email: [email protected]

Getting Started

Accounts

Profiles

Messaging

Network

Content

Recruiting

Credits

Logs

Email Enrichment

Webhooks (Real-Time)

Migration from V1 to V2

What Changed (TL;DR)

No more login_token

One endpoint per category

Standardized responses

Proper HTTP status codes

New in V2 Only

Step-by-Step Migration

Step 1 — Connect Your Account

Batch Migration (SaaS with many accounts)

Step 2 — Update Request Format

Search Filters: Strings → Arrays

Step 3 — Update Response Parsing

Step 4 — Update Error Handling

Step 5 — Migrate Webhooks

Complete Endpoint Mapping

Authentication

Profiles

Messages

Network

Content & Posts

Recruiter

Email / Enrichment

Webhooks

Quick Migration Checklist

Need Help?

​What Changed (TL;DR)

No more login_token

One endpoint per category

Standardized responses

Proper HTTP status codes

​New in V2 Only

​Step-by-Step Migration

​Step 1 — Connect Your Account

​Batch Migration (SaaS with many accounts)

​Step 2 — Update Request Format

​Search Filters: Strings → Arrays

​Step 3 — Update Response Parsing

​Step 4 — Update Error Handling

​Step 5 — Migrate Webhooks

​Complete Endpoint Mapping

​Authentication

​Profiles

​Messages

​Network

​Content & Posts

​Recruiter

​Email / Enrichment

​Webhooks

​Quick Migration Checklist

​Need Help?

What Changed (TL;DR)

New in V2 Only

Step-by-Step Migration

Step 1 — Connect Your Account

Batch Migration (SaaS with many accounts)

Step 2 — Update Request Format

Search Filters: Strings → Arrays

Step 3 — Update Response Parsing

Step 4 — Update Error Handling

Step 5 — Migrate Webhooks

Complete Endpoint Mapping

Authentication

Profiles

Messages

Network

Content & Posts

Recruiter

Email / Enrichment

Webhooks

Quick Migration Checklist

Need Help?