# Lusha API - Frequently Asked Questions (Q&A)

## Q: What APIs does Lusha offer?

**A:** Lusha provides six main RESTful API endpoint groups:

1. **Enrichment API**
Search and enrich contact and company records. V3 uses a search-then-enrich pattern: first search by identifier to get a non-PII preview, then enrich to reveal emails, phones, and firmographic data. A combined Search and Enrich endpoint is also available for single-step workflows.
2. **Prospecting API**
Filter-based queries across Lusha's full database. Filter by job title, seniority, department, location, company size, revenue, industry, technologies, intent topics, and signals to build targeted contact and company lists. Returns up to 50,000 results per query (1,000 pages × 50 results).
3. **Signals API**
Real-time buying intent and market intelligence data. Retrieve contact signals (job changes, promotions) and company signals (headcount changes, hiring surges, website traffic, IT spend, news events) by ID or by identifier. Can also be used as a filter inside Search and Prospecting requests.
4. **Lookalikes API**
AI-powered contact and company recommendations based on seed inputs. Uses session-based deduplication so repeated calls return new results without overlap. Sessions persist for 30 days.
5. **Webhooks API**
Subscribe to real-time push notifications when contacts change jobs or companies experience key business events. Supports bulk subscription management, HMAC-SHA256 signature verification, automatic retries, and delivery audit logs. Includes an opt-out notification endpoint for GDPR/CCPA compliance workflows.
6. **Website Visits API**
Identify and filter companies that have visited your website. Query traffic across your registered tracking sites and filter by engagement score, session depth, unique visitors, and geography to surface high-intent accounts. Returns company IDs you can pass directly to Enrich Companies for full firmographic data.
7. **Account API**
Returns current credit usage, rate limit status, plan details, and per-action pricing.


## Q: What version of the API should I use?

**A:** V3 is the current production version and is recommended for all new integrations. All V3 endpoints are under `https://api.lusha.com/v3/`. V2 is still operational but is approaching deprecation - see the [Migration Guide](/tutorials/v3-migration-guide) for details on what changed.

## Q: How do I make requests to Lusha's APIs?

**A:**

- All requests must be made over HTTPS.
- Responses are returned in JSON format.
- Include your API key in the `api_key` request header on every call.


## Q: How does authentication work?

**A:** Pass your API key in the `api_key` header of every request. You can generate and manage your key in the [Lusha dashboard](https://dashboard.lusha.com/enrich/api). Store your key securely and only use it in server-side environments - never expose it in client-side code.

## Q: What is the search-then-enrich pattern in V3?

**A:** V3 separates data retrieval into two steps:

1. **Search** - Look up contacts or companies by identifier (LinkedIn URL, email, name + company, domain, or Lusha ID). Returns a non-PII preview with a `has` field listing available data points and a `canReveal` field showing what can be unlocked and the credit cost.
2. **Enrich** - Pass the IDs from search results to reveal full data (emails, phones, firmographics).


You can also use the **Search and Enrich** endpoint to combine both steps in a single call. Billing applies at both steps.

## Q: What identifiers can I use to search for contacts?

**A:** Any one of the following per contact:

- Lusha contact `id`
- `linkedinUrl`
- `email`
- `firstName` + `lastName` + `companyName` or `companyDomain`


Up to 100 contacts per request.

## Q: What identifiers can I use to search for companies?

**A:** Any one of the following per company:

- Lusha company `id`
- `name`
- `domain`


Up to 100 companies per request.

## Q: What does the Prospecting API do, and when should I use it?

**A:** Use Prospecting when you want to discover net-new contacts or companies matching your Ideal Customer Profile (ICP). Unlike Enrichment (which looks up known records), Prospecting queries Lusha's full database using filter criteria and returns paginated results you can then enrich.

Contact filters include: job title, seniority, department, location, existing data points, signals, and company attributes like size, revenue, industry, and technologies.

Company filters include: size, revenue, industry, SIC/NAICS codes, technologies, locations, intent topics, funding, and signals.

## Q: What filtering options are available in the Prospecting API?

**A:** You can filter on a wide range of attributes:

**Contact-level:** job title, normalized job title, seniority, department, location (city/state/country/continent), existing data points (e.g. `work_email`, `phone`), LinkedIn URLs, free-text search (`searchText`), and signal types.

**Company-level:** name, domain, size (employee range), revenue range, industry/sub-industry, SIC codes, NAICS codes, technologies (with OR/AND logic), intent topics, funding details, locations (HQ or site-level offices), LinkedIn employee count, and signal types.

Both include and exclude filters are supported. Use the Filter endpoints to discover valid values before building your query.

## Q: What is the Signals API, and how does it work?

**A:** The Signals API provides real-time market intelligence and activity data for contacts and companies.

**Contact signals:** `promotion`, `companyChange`

**Company signals:** headcount changes (1m/3m/6m/12m increase or decrease), `surgeInHiring`, `surgeInHiringByDepartment`, `surgeInHiringByLocation`, `websiteTrafficIncrease`, `websiteTrafficDecrease`, `itSpendIncrease`, `itSpendDecrease`, and 7 news signal categories: `riskNews`, `commercialActivityNews`, `corporateStrategyNews`, `financialEventsNews`, `peopleNews`, `marketIntelligenceNews`, `productActivityNews`.

You can retrieve signals by Lusha IDs or by identifiers (LinkedIn URL, email, name + company/domain). Signals can also be used as filters in Search and Prospecting requests. Use `startDate` to scope results to a specific timeframe (default: last 6 months). `maxResultsPerSignal` is optional and caps results per signal type per entity.

Company signals also support sub-filters: `newsEventTypes`, `hiringByDepartments`, and `hiringByLocations` to narrow results without separate requests.

## Q: What is the Lookalikes API?

**A:** The Lookalikes API uses AI to find contacts or companies similar to a set of seeds you provide.

For contacts, seed with LinkedIn URLs, emails, Lusha IDs, or name + company (5-100 seeds required). For companies, seed with domains or LinkedIn URLs.

Results use session-based deduplication via `dedupeSessionId` - omit it on your first request and the server generates one. Pass it on subsequent requests to get more results without repeats. Sessions are active for 30 days from last use.

Use the returned IDs with the Enrich endpoints to get full contact or company data.

## Q: What is the Website Visits API?

**A:** The Website Visits API (`POST /v3/websiteVisits`) returns a paginated list of companies that visited your website within a specified date range (max 3 months).

Each request requires at least one `siteId` — find yours by clicking the **⋯** menu next to a configured domain in the Lusha dashboard and selecting **Copy Site ID**.

Filter results by:

- **Engagement score band:** `cold`, `warm`, or `hot`
- **Session metrics:** `totalSessions`, `uniqueVisitors`, `avgSessionMinutes`, `daysVisited`, `highIntentPageviews`, `daysSinceLastVisit`
- **Geography:** `visitorCountries` (include) and `visitorCountriesExclude` (exclude)


Sort by any metric field using `sortBy` and `order`. Paginate via `limit` (max 150) and `offset`. Results include a `companyId` you can pass directly to Enrich Companies for full firmographic data.

## Q: What are Webhooks, and when should I use them?

**A:** Webhooks provide a push-based alternative to polling the Signals API. Subscribe to specific entities (contacts or companies) and Lusha delivers HTTP POST payloads to your endpoint when signals occur.

Key capabilities:

- Bulk subscription creation (up to 25 per request)
- Supports all contact and company signal types
- HMAC-SHA256 signature verification for security
- Automatic retry with exponential backoff (max 3 attempts)
- Audit logs for delivery monitoring
- Opt-out subscription endpoint for data removal compliance


Your endpoint must respond with HTTP 2xx and a JSON acknowledgment within 10 seconds. Subscriptions auto-disable after max retries are exceeded but can be reactivated via the update endpoint.

## Q: In what format are responses delivered?

**A:** All endpoints return JSON. Example V3 contact search response snippet:


```json
{
  "id": "4415824633",
  "firstName": "Orit",
  "lastName": "Shilvock",
  "jobTitle": {
    "title": "Vice President of Partnerships",
    "departments": ["Business Development"],
    "seniority": "Vice President"
  },
  "has": ["firstName", "lastName", "jobTitle", "emails"],
  "canReveal": [{ "field": "emails", "credits": 1 }]
}
```

## Q: Are there rate limits?

**A:** Yes. Default limits:

- 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`, and their usage counterparts). Contact your account manager if you frequently hit limits.

## Q: How are API errors handled?

**A:** Lusha uses standard HTTP status codes. Common ones:

| Code | Meaning |
|  --- | --- |
| 200 | Success |
| 400 | Bad request - malformed or missing parameters |
| 401 | Unauthorized - invalid or missing API key |
| 402 | Payment required - insufficient credits |
| 403 | Forbidden - account inactive or feature not available on your plan |
| 404 | Not found |
| 429 | Rate limit or daily quota exceeded |
| 451 | Blocked due to GDPR regulations |
| 5XX | Server error - retry with exponential backoff |


Error response format:


```json
{
  "statusCode": 400,
  "message": "Invalid request parameters"
}
```

## Q: How does credit billing work?

**A:** Credits are consumed per action:

- **Search (contact or company):** charged per successful result via `api_search`
- **Enrich contacts:** charged per revealed field (`revealEmail`, `revealPhone`) via per-datapoint pricing
- **Enrich companies:** charged per successful result via `reveal_company`; additional revealable fields (e.g. `employeesByDepartment`, `competitors`, `intent`) are charged separately per result
- **Signals:** charged per matched signal per result
- **Lookalikes:** charged per result returned
- **Webhooks:** charged when signals are detected and delivered; retries do not incur additional charges


Check `billing.creditsCharged` in any response to see what was consumed. Use the Account Usage endpoint to monitor your balance.

## Q: Can I test the API before integrating?

**A:** Yes. Use the [Lusha Postman Workspace](https://www.postman.com/lushateam/workspace/lusha-s-api/collection/28683568-fc849873-9ae1-47dd-8159-0d4deda04750) to test endpoints with live examples. You can also test webhook delivery without consuming credits using the Test Subscription endpoint (`POST /api/subscriptions/{id}/test`).

## Q: Where can I find valid filter values for Prospecting?

**A:** Use the Filter endpoints before building your prospecting queries:

- `GET /v3/contacts/prospecting/filters` - lists available contact filter types
- `GET /v3/contacts/prospecting/filters/{filterType}` - returns valid values for a specific filter (e.g. `departments`, `seniority`, `countries`, `locations`)
- `GET /v3/companies/prospecting/filters` - lists available company filter types
- `GET /v3/companies/prospecting/filters/{filterType}` - returns valid values (e.g. `sizes`, `revenues`, `industriesLabels`, `technologies`, `intentTopics`)


Some filters require a `query` parameter (e.g. `locations`, `technologies`, `names`).

## Q: What's the difference between V2 and V3?

**A:** Key changes in V3:

- **Search-then-enrich pattern** - Search is now a separate billable step that returns previews before you commit to enrichment
- **New endpoint paths** - All V3 enrichment endpoints are under `/v3/contacts/` and `/v3/companies/`
- **Bulk by default** - V3 endpoints natively accept arrays of up to 100 records
- **Lookalikes redesign** - New session-based deduplication, expanded seed identifier types, and renamed fields (`contactId` instead of `id` in results)
- **Company enrich** - New revealable fields: `employeesByDepartment`, `employeesByLocation`, `employeesBySeniority`, `competitors`, `intent`
- **Signals are optional per-request** - `maxResultsPerSignal` is now optional (previously required in v2.1.0)


See the [Migration Guide](/tutorials/v3-migration-guide) for the full breakdown.