Skip to main content
Lusha API V3 is the most flexible and modular version of the API to date. Built on a composable “building block” architecture, V3 gives you better credit control, stable entity IDs, and cleaner endpoint structure - while keeping the same credit model you already know.

​
What is V3?

V3 restructures the Lusha API into four clear, composable building blocks. Each block performs one action, has predictable pricing, and shares a stable entity ID so you can chain them together without re-searching the same records. The key efficiency gain: In V2, enriching a contact always meant running the full search-and-data flow. In V3, you can search 500 contacts cheaply, filter to your ICP, then enrich only the 80 that matter - spending credits only where they count.

​
Key Concepts

  • Building Blocks - The modular structure of V3, categorized into Search, Enrich, Signals, and Lookalike.
  • Stable IDs - V3 introduces permanent contactId and companyId values that remain consistent across your account, preventing duplicate enrichment. Find once, reuse forever.
  • Resource-First URL - A restructured path (e.g., /v3/contacts/) that makes the API more intuitive for developers.
  • Sunset Period - The 6-month window where V2 and V3 run in parallel before V2 is retired.

​
Do You Need to Migrate?

If you’re only using Signals or Lookalikes, there’s nothing for you to do.

​
What’s Changing

The primary shift in V3 is the move from a flat structure to a resource-based structure.
  • Request method changes - Several GET requests in V2 (like Person Enrichment) have moved to POST in V3 to support more complex query parameters.
  • Consolidated endpoints - V3 offers a search-and-enrich endpoint, letting you find a contact and get their details in a single call.
  • Sunset response headers - Starting May 18, 2026, all V2 responses will include a Sunset header as a technical signal that the endpoint is approaching retirement.

​
Migration Paths

​
Person and Company Enrichment (GET /v2/*)

Easiest migration. A single combined endpoint replaces both V2 calls. The main change is HTTP method (GET → POST) and moving parameters into a request body.
Want more credit control? Use the 2-step flow instead: POST /v3/contacts/search to discover, then POST /v3/contacts/enrich only for the records you actually need.

​
Bulk Enrichment (POST /v2/* bulk)

For high-volume use, the 2-step flow (search → filter → enrich) is recommended. Search is cheap - use it to qualify your list before spending enrichment credits.

​
Prospecting

URL structure changes. The enrich step is now shared with the main enrichment flow - fewer endpoints to keep track of.

​
Filter Endpoints

All individual filter endpoints consolidate into one consistent parameterized pattern. Same filter options - just one URL pattern instead of separate endpoints for each filter.

​
How to Start Your Migration

  1. Audit your current usage - Identify which V2 endpoints your team currently calls.
  2. Review the mapping table - Match your V2 endpoints to their V3 equivalents using the tables above.
  3. Test in the Playground - Use the API Playground at dashboard.lusha.com to run test queries in V3 against real data before touching your integration.
  4. Update your base URL - Shift your integration to point toward the /v3/ paths.

​
What’s New in V3

These capabilities are not available in V2. Migrating early gives you access to all of them.

​
Common Questions

Will my integration break? Not immediately. V2 stays fully live until November 18, 2026. You have six months to migrate. Sunset headers will be added to V2 responses from May 18 so you can track the timeline in your tooling. How much work is the migration? For most use cases, very little. The search-and-enrich endpoint is close to a drop-in replacement for GET /v2/person and GET /v2/company - the main change is switching from GET to POST and moving parameters into a request body. Prospecting migrations are mainly URL changes with a small request body update. Do Signals and Lookalikes change? No. Those endpoints are unchanged in V3. If you’re only using Signals or Lookalikes, there is nothing for you to do. What happens if I don’t migrate by November 18? V2 endpoints will stop responding. Any workflow calling a V2 URL directly will break. You’ll receive warning communications at the 60-day and 30-day marks before sunset. Can I test V3 before switching? Yes. The API Playground at dashboard.lusha.com is available to try V3 calls against real data before touching your integration.