Lusha API V3 is our most flexible and modular API to date. Built on a "Building Block" architecture, V3 allows you to scale your automation and enrichment workflows with better precision and more stable data mapping. This article explains the technical shift from V2 to V3, the migration timeline, and how to ensure your workflows continue to run without interruption.
Key Concepts and Terminology
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.
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 operate in parallel before V2 is retired.
Why Migrate to V3 Early?
V3 introduces exclusive capabilities that V2 simply can't support—including search-before-spend logic, stable entity IDs, lookalike previews, multi-step workflows, and premium data. Built on a modular, flexible API architecture, V3 delivers cleaner endpoints and superior credit control from day one.
Plan Availability
API V3 is available to all customers on Pro, Premium, and Scale plans with API access. New features like the Website Visits API and the updated API Playground are exclusive to V3.
The V2 to V3 Migration Timeline
To ensure a smooth transition, we are providing a 6-month "dual-run" period. During this time, your existing V2 integrations will continue to work while you build and test on V3. V2 final sunset will be at the end of November 2026.
What is Changing?
The primary shift in V3 is the move from a flat structure to a resource-based structure. While Signals and Lookalike endpoints remain unchanged, the Enrichment and Prospecting endpoints have been updated.
Request Method Changes: Several GET requests in V2 (like Person Enrichment) have moved to POST in V3 to allow for more complex query parameters.
Consolidated Endpoints: V3 offers a search-and-enrich endpoint, allowing you to find a contact and get their details in a single call.
Response Headers: Starting May 18, 2026, all V2 responses will include a Sunset header. This is a technical signal to your dev team that the endpoint is approaching retirement.
How to Start Your Migration
Audit your current usage: Identify which V2 endpoints your team currently calls.
Review the Mapping Table: Match your V2 endpoints to the new V3 equivalents (see the link below).
Test in the Playground: Use the API Page 2.0 to run test queries in V3 without writing code.
Update your Base URL: Shift your integration to point toward the /v3/ paths.
💡 Note: If you are a Scale customer with a custom integration, please don't hesitate to contact your Account manager, who can help you to migrate.
For a detailed technical breakdown of every endpoint change, please refer to our How to Migrate from API V2 to V3 guide.
Now you're ready to prospect smarter.