Overview

This page is the technical entry point to the Lusha API. It introduces the core data types, access patterns, and fundamentals required to authenticate and make a first request. Use this section to understand how the API is structured and confirm access before moving into specific capabilities.

You are viewing the V3 documentation. V3 introduces a search-then-enrich pattern, bulk operations, AI-powered lookalikes, richer filter capabilities, persistent Tables, and Waterfall Reveal for contact enrichment. All V3 endpoints are under https://api.lusha.com/v3/. For migration details, see the Migration Guide.

The Lusha API exposes GTM data through a small set of core data types and access patterns.

• People - contact profiles and identifiers
• Companies - firmographic and company-level attributes
• Signals - change-based events across contacts and companies
• Lookalikes - AI-powered similarity recommendations for expansion
• Tables - persistent, configurable lists of contacts or companies

• Search - find contacts and companies by identifier; returns non-PII previews
• Enrich - reveal full data (emails, phones, firmographics) using IDs from search
• Search and Enrich - combine both steps in a single call
• Prospecting - filter-based search across Lusha's full database
• Buying Group - identify and prioritize the buying committee (decision makers, champions, end users) within a set of target companies
• Signals - retrieve or filter by real-world activity data
• Tables - create and manage reusable tables of contacts or companies; save results into them directly from Prospecting, Enrich, Signals, Buying Group, or Lookalike calls
• Webhooks - receive push notifications when signals occur
• Website Visitors - identify and filter companies that have visited your website

• Generate and manage API keys in the Lusha API Dashboard
• Store keys securely (e.g. environment variables)
• Never expose API keys in client-side code

Include your API key in the api_key header of every request:

api_key: YOUR_API_KEY

• All responses are returned as structured JSON
• Contact previews include non-PII fields (name, job title, location, social links) plus has (available data) and canReveal (revealable fields with credit cost)
• Enriched contacts include emails, phones, previous employment, and LinkedIn enrichment fields
• Enriched companies include firmographics, funding, technologies, intent, and optional breakdowns by department, location, seniority, and competitors
• Buying Group results group contact previews by company, with each contact carrying a roles array (decision_maker, potential_champion, end_user) and a score (0–1) reflecting relevance to that role
• Tables are persistent lists of contacts or companies with configurable columns (default Lusha fields, CRM fields, Signals, AI-generated fields, score columns). Rows are read as a columns[] array per row, with each column carrying a status (not_run, processing, success, no_data, failed)
• Some fields may be absent depending on data availability, plan permissions, or compliance rules

Step 1 - Search:

POST https://api.lusha.com/v3/contacts/search

Send identifying fields such as firstName, lastName, companyDomain. The response returns a preview and the contact's Lusha id.

Step 2 - Enrich:

POST https://api.lusha.com/v3/contacts/enrich

Pass the id from step 1. Specify reveal: ["emails", "phones"] to control what gets unlocked. Optionally add waterfallReveal with the same fields to fall through to your enabled third-party providers when Lusha's own data has no match - requires Data Waterfall enabled under Account > Waterfall.

POST https://api.lusha.com/v3/contacts/search-and-enrich

Combines both steps. Two charges apply per result (search + reveal).

POST https://api.lusha.com/v3/contacts/buying-group

Pass up to 25 companies by domain or Lusha company id. The response groups contact previews by company, each labeled with a persona role (decision_maker, potential_champion, end_user) and a relevance score. Pipe the returned contact id values into POST /v3/contacts/enrich to reveal emails and phones for the people you want to prioritize.

POST https://api.lusha.com/v3/contacts/tables

Create a table first — the response returns a tableId. Then pass that tableId on a Prospecting, Enrich, Signals, or Lookalike call to save matching results into it automatically:

POST https://api.lusha.com/v3/contacts/prospecting

with tableId set in the request body. Results are returned as usual, and a tableWrite object in the response confirms what was saved to the table. See Contacts Tables or Companies Tables.

• Check HTTP status codes for every response
• Read the message field for troubleshooting details
• Handle 4xx and 5xx errors explicitly
• Implement retry logic with exponential backoff for 429 and 5XX responses

Rate limits:

Rate limit status is returned in response headers (x-rate-limit-daily, x-daily-requests-left, x-rate-limit-hourly, x-hourly-requests-left, x-rate-limit-minute, x-minute-requests-left).

Pagination:

Prospecting endpoints support up to 1,000 pages × 50 results = 50,000 results per query. Use the pagination.page and pagination.size fields in your request.

Buying Group results are paginated the same way, via pagination.page and pagination.size in the request body (size 10–100, default 100).

Table entity reads (GET .../entities) use page (0–100) and size (default 100) query parameters instead.

Tables limits:

Once you've validated access, you can:

• Use Enrichment to add missing or updated data to known contacts and companies, optionally falling through to third-party providers via Waterfall Reveal
• Explore Prospecting to build dynamic contact and company lists from Lusha's full database
• Add Signals to trigger workflows based on real-world changes
• Apply Lookalikes to expand target accounts and find net-new prospects
• Use Buying Group to map decision makers, champions, and end users at target accounts before you start outreach
• Use Tables to save and organize contacts or companies into persistent, enrichable lists that sync with the Workspace UI
• Set up Webhooks for push-based signal delivery without polling
• Use Website Visitors to surface high-intent accounts from your website traffic
• Use the Filter endpoints to discover valid values before building prospecting queries
• Review the Changelog to track recent API changes

Quick implementations for common platforms:

• Salesforce - Apex trigger on Lead creation → call Lusha API → update fields; Flows for webhook-based enrichment
• HubSpot - Workflow → custom webhook → map response to HubSpot properties
• Webhooks - Subscribe to events, verify HMAC-SHA256 signatures, Node.js/Express listener example
• Bulk Enrichment - Python scripts to process CSV files, submit bulk requests, poll for results, write output to database or file
• SDK Examples (Node.js, Python, Java) - Community wrappers and raw HTTP equivalents

• Performance & Cost - Batch requests, caching (Redis/in-memory), cost-aware enrichment patterns
• Complex Queries - Combine filters for higher accuracy, client-side matching and deduplication
• Security Best Practices - Encrypt API keys, enforce least privilege, audit logging
• Orchestration Workflows - AWS Lambda and API Gateway integration patterns
• Data Quality & Fallbacks - Handle missing fields, merge multiple enrichers, fallback strategies
• Schema & Data Modeling - DB table structures (Postgres, MongoDB), indexing by email hash or domain
• Compliance & Privacy - GDPR/CCPA guidelines, retention policies, anonymization, opt-out webhook integration
• Custom Connectors - Build for Workato, Zapier, Make, n8n: HTTP module config, auth, mapping, error patterns

• Full API Reference - Complete endpoint docs with examples (cURL, Node.js, Python, Java)
• Common API questions - FAQs and clarifications
• Changelog & Release Notes - Track new endpoints, parameter changes, deprecations
• Help Center - Integration guides and community wrappers
• Postman Workspace - Test endpoints with live examples