Overview

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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, and richer filter capabilities. All V3 endpoints are under https://api.lusha.com/v3/. For migration details, see the Migration Guide.

How the Lusha API is organized

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

Core data types

• 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

Access patterns

• 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
• Signals - retrieve or filter by real-world activity data
• Decision Makers - surface the most relevant contacts to reach within a set of companies
• Webhooks - receive push notifications when signals occur
• Website Visits - identify and filter companies that have visited your website

Endpoints at a Glance

1. Authentication

API key setup

• 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

Authenticating requests

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

api_key: YOUR_API_KEY

2. Data model basics

• 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
• Some fields may be absent depending on data availability, plan permissions, or compliance rules

3. First request

Example: search then enrich a contact

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.

Or: search and enrich in one call

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

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

4. Error handling

• 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

5. Rate limits and pagination

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.

6. Next steps

Once you've validated access, you can:

• Use Enrichment to add missing or updated data to known contacts and companies
• 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 Decision Makers to quickly identify the right contacts to reach within a set of target account
• Set up Webhooks for push-based signal delivery without polling
• Use Website Visits 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

7. Integration Guides

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

8. Advanced Topics

• 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

Need help?

• 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