# 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, and richer filter capabilities. All V3 endpoints are under `https://api.lusha.com/v3/`. For migration details, see the [Migration Guide](/tutorials/v3-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
- **Webhooks** - receive push notifications when signals occur
- **Website Visits (SOON)** - identify and filter companies that have visited your website


## Endpoints at a Glance

| Category | Endpoint | Purpose |
|  --- | --- | --- |
| **Enrichment** | `POST /v3/contacts/search` | Search contacts by identifier |
|  | `POST /v3/contacts/enrich` | Reveal full contact data |
|  | `POST /v3/contacts/search-and-enrich` | Search and enrich in one call |
|  | `POST /v3/companies/search` | Search companies by identifier |
|  | `POST /v3/companies/enrich` | Reveal full company data |
|  | `POST /v3/companies/search-and-enrich` | Search and enrich in one call |
| **Prospecting** | `POST /v3/contacts/prospecting` | Filter-based contact search |
|  | `POST /v3/companies/prospecting` | Filter-based company search |
| **Lookalikes** | `POST /v3/contacts/lookalike` | AI contact recommendations |
|  | `POST /v3/companies/lookalike` | AI company recommendations |
| **Signals** | `POST /v3/contacts/signals` | Contact signals by ID |
|  | `POST /v3/companies/signals` | Company signals by ID |
|  | `GET /v3/contacts/signals/types` | List contact signal types |
|  | `GET /v3/companies/signals/types` | List company signal types |
|  | `GET /v3/companies/signals/filters` | Discover company signal filter types |
|  | `GET /v3/companies/signals/filters/{filterType}` | Get valid signal filter values |
| **Filters** | `GET /v3/contacts/prospecting/filters` | Discover contact filter types |
|  | `GET /v3/contacts/prospecting/filters/{filterType}` | Get valid contact filter values |
|  | `GET /v3/companies/prospecting/filters` | Discover company filter types |
|  | `GET /v3/companies/prospecting/filters/{filterType}` | Get valid company filter values |
| **Webhooks** | `POST /api/subscriptions` | Create subscriptions |
|  | `GET /api/subscriptions` | List subscriptions |
|  | `GET /api/subscriptions/{id}` | Get subscription by ID |
|  | `PATCH /api/subscriptions/{id}` | Update subscription |
|  | `POST /api/subscriptions/delete` | Delete subscriptions |
|  | `POST /api/subscriptions/{id}/test` | Test subscription delivery |
|  | `GET /api/audit-logs` | Webhook delivery logs |
|  | `GET /api/audit-logs/stats` | Delivery statistics |
|  | `GET /api/account/secret` | Get webhook secret |
|  | `POST /api/account/secret/regenerate` | Regenerate webhook secret |
|  | `POST /api/subscriptions/opt-out` | Opt-out notification subscription |
| **Website Visits (SOON)** | `POST /v3/websiteVisits` | Companies visiting your website |
| **Account** | `GET /v3/account/usage` | Credits, rate limits, plan, pricing |


## 1. Authentication

### API key setup

- Generate and manage API keys in the [Lusha API Dashboard](https://dashboard.lusha.com/enrich/api)
- 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:


```bash
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:**


```bash
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:**


```bash
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


```bash
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


| Code | Meaning |
|  --- | --- |
| 200 | Success |
| 400 | Bad request |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 403 | Account inactive or feature unavailable on your plan |
| 404 | Endpoint or resource not found |
| 429 | Rate limit exceeded |
| 451 | Blocked - GDPR regulations |
| 5XX | Server error - retry with backoff |


## 5. Rate limits and pagination

**Rate limits:**

| Scope | Limit |
|  --- | --- |
| General endpoints | 25 requests per second |
| Account Usage API | 5 requests per minute |
| Webhooks API | 100 requests per minute |


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
- 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](/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**](/apis/openapi) - Complete endpoint docs with examples (cURL, Node.js, Python, Java)
- [**Common API questions**](/qa) - FAQs and clarifications
- [**Changelog & Release Notes**](/changelog) - Track new endpoints, parameter changes, deprecations
- [**Help Center**](/tutorials) - Integration guides and community wrappers
- [**Postman Workspace**](https://www.postman.com/lushateam/workspace/lusha-s-api/collection/28683568-fc849873-9ae1-47dd-8159-0d4deda04750) - Test endpoints with live examples