This guide provides the exact steps required to transition your Lusha API integration from V2 to V3. By migrating, you will gain access to Stable IDs, which prevent credit waste on duplicate records, and the new Search and Enrich combined endpoints.
Prerequisites
An active Lusha API Key.
Access to your organization's codebase or integration middleware (e.g., Zapier, Make, or custom scripts).
A Pro, Premium, or Scale plan.
Step 1: Map your V2 Endpoints to V3
Lusha V3 uses a resource-first URL structure. You must update your base URLs and specific endpoint paths.
Identify all calls starting with https://api.lusha.com/v2/.
Replace them with the corresponding V3 paths. Refer to the table below for the most common changes:
V2 Endpoint | V3 Equivalent | Key Change |
GET /v2/person | POST /v3/contacts/search-and-enrich | Changed from GET to POST. |
GET /v2/company | POST /v3/companies/search-and-enrich | Changed from GET to POST. |
POST /prospecting/contact/search | POST /v3/contacts/prospecting | Restructured under /v3/contacts/. |
POST /bulk/company/v2 | POST /v3/companies/enrich | /bulk/ prefix removed. |
Step 2: Update Request Methods from GET to POST
In V2, single enrichments were often handled via GET. In V3, these have been standardized to POST to support more robust data queries.
Locate your enrichment functions for individual contacts or companies.
Change the HTTP method from GET to POST.
Move your query parameters (like email or linkedin_url) from the URL string into the JSON request body.
Step 3: Implement Stable IDs
V3 introduces contactId and companyId. These IDs are permanent and scoped to your account.
Update your database schema to store the new contactId returned in V3 responses.
Use these IDs for future enrichment calls to ensure you are not charged credits for data you have already revealed.
Step 4: Test in the API Playground
Before pushing changes to production, validate your new logic in our sandbox environment.
Navigate to Dashboard → Developer → API Page 2.0.
Select the V3 tab.
Input your parameters and click Send Request to verify the JSON output matches your application's requirements.
Step 5: Monitor for Deprecation Headers
While testing, check the headers of any remaining V2 calls in your logs.
Look for the Sunset header. It will display: Sunset: Wed, 18 Nov 2026 00:00:00 GMT.
If you see the X-Lusha-Migration header, follow the included URL for specific documentation regarding that endpoint.
Success State
Once you have updated your base URLs to /v3/ and verified a successful 200 OK response in your production logs, your migration is complete. You will no longer see deprecation warnings in your API response headers.
💡 Note: V2 connectors for Zapier and HubSpot will remain functional until November 2026. However, we recommend switching to the V3 connector versions as soon as they are published in Phase 1 to access new data fields.
⚠️ Important: All V2 endpoints will be retired in November 2026. Failure to migrate by this date will result in 410 Gone errors and the interruption of your workflows.
You're all set!