This page is the technical entry point to the Lusha API. It introduces the core data types exposed by the API, the main access patterns, and the 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.
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 — similarity-based recommendations for expansion
- Enrichment — add missing or updated data to existing records
- Search & prospecting — find contacts and companies using filters
- Automation — use enrichment and signals inside workflows
| Resource | Endpoint | Purpose |
|---|---|---|
| Person | GET /v2/person | Lookup contact details |
POST /v2/person | Bulk person enrichment | |
| Company | GET /v2/company | Lookup company info |
POST /v2/company | Bulk company enrichment | |
| Prospect | POST /prospecting/contact/search | Search for contacts |
POST /prospecting/contact/enrich | Enrich contact data | |
POST /prospecting/company/search | Search for companies | |
POST /prospecting/company/enrich | Enrich company data | |
| Account | GET /account/usage | Check credit usage |
| Signals | POST /signals/contacts | Retrieve contact signals by IDs |
POST /signals/companies | Retrieve company signals by IDs | |
POST /signals/contacts/search | Retrieve contact signals by identifiers | |
POST /signals/companies/search | Retrieve company signals by identifiers | |
| Recommendations | POST /recommendations/contacts | Get contact recommendations |
POST /recommendations/companies | Get company recommendations |
- Generate and manage API keys in the Lusha API Dashboard
- Store keys securely (for example, using environment variables)
- Never expose API keys in client-side code
When making an API call, include your API key in the api_key header of the request.
- Header:
api_key - Format:
Bearer YOUR_API_KEY
- All responses are returned as structured JSON
- Common fields include
email,phone,job title,company, andlocation - Some fields may be missing depending on availability, permissions, or compliance rules
GET https://api.lusha.com/v2/person- Send identifying fields such as
firstName,lastName,company - Parse the JSON response
- Locate returned fields such as
emailorphonewhen available
- Check HTTP status codes for every response
- Handle 4xx and 5xx errors explicitly
- Implement retry logic for rate limit responses (HTTP 429)
Detailed error formats and retry guidance are covered in Errors & handling
- Default rate limit: 25 requests per second
- Some endpoints return paginated results
- Use pagination tokens to retrieve additional pages
See Rate limits for full details.
Once you've validated access, you can:
- Use Enrichment to add missing data to contacts and companies
- Explore Search & prospecting to build dynamic contact and company lists
- Add Signals to trigger workflows based on real-world changes
- Apply Lookalikes to expand target accounts and audiences
- Explore MCP for AI- and agent-based workflows
- Review rate limits and best practices before moving to production
Quick implementations for common platforms:
Salesforce
- Apex trigger on
Leadcreation → call Lusha API → update fields. - Flows for easy webhook API implementation.
- Apex trigger on
HubSpot
- Workflow → custom webhook
- Map response to HubSpot properties (YAML/JSON examples).
Webhooks
- Subscribe to events (e.g., data updates).
- Verify signatures; Node.js/Express listener example.
Bulk Enrichment
- Python scripts to process CSV files
- Submit bulk requests, poll for results, and write output to a database or file
SDK Examples (Node.js, Python, Java)
- Community wrappers: install, initialize, fetch data.
- Raw HTTP equivalents for each example.
Deeper guidance for teams running Lusha at scale.
Performance & Cost
- Batch requests, caching (Redis/in-memory), cost-aware enrichment patterns.
Complex Queries
- Combine parameters for higher accuracy, client-side matching and deduplication.
Security Best Practices
- Encrypt API keys, enforce least privilege, audit logging.
Orchestration Workflows
- Terraform/CloudFormation snippets for AWS Lambda and API Gateway.
Data Quality & Fallbacks
- Handle missing fields: fallback to alternative data sources, merge multiple enrichers.
Schema & Data Modeling
- DB table structures (Postgres, MongoDB), indexing (email hash, domain), migration strategies.
Compliance & Privacy
- GDPR/CCPA guidelines: retention policies, anonymization, privacy disclaimers.
Custom Connectors
- Build for Workato, Zapier, Make: HTTP module config, auth, mapping, error patterns.
- Full API Doc: 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: Links to community-driven wrappers; installation and usage.
Explore the Postman Public Environment: Test out the API endpoints and see how the data is structured. You can access our public Postman workspace to experiment with live examples and understand the response formats - Access Lusha's Postman Workspace!