# Changelog

All notable changes to the Lusha API and MCP are documented here. We follow semantic versioning.

## Current Version: 2.3.0

**Status:** Production - **Released:** June 2026 - **Stability:** Stable

## Changelog History

## [2.3.0] - 2026-06-02 - Website Visits API

### Added

**Website Visits API**
Added `POST /v3/websiteVisits` - identify and filter companies that have visited your website.

- Filter by engagement score band (`cold`, `warm`, `hot`)
- Filter by session metrics: `totalSessions`, `uniqueVisitors`, `avgSessionMinutes`, `daysVisited`, `highIntentPageviews`, `daysSinceLastVisit`
- Filter by geography: `visitorCountries` (include) and `visitorCountriesExclude` (exclude)
- Sort results by any metric field via `sortBy` and `order`
- Paginate via `limit` (max 150) and `offset`
- Date range window cannot exceed 3 months


Each request requires at least one `siteId` (UUIDv4). To find yours, click the **⋯** menu next to a configured domain in the Lusha dashboard and select **Copy Site ID**.

Results return `companyId`, which can be passed directly to Enrich Companies for full firmographic data.

### Notes

- `startDate` and `endDate` are required; the window between them must not exceed 3 months
- Both dates must be in `YYYY-MM-DD` format and must be past dates


## [2.2.0] - 2026-03-10 - Signal Sub-Filters, Lookalikes V3 Expansion & Doc Improvements

### Added

**Signal Sub-Filters for Company Bulk Enrich**
Added optional `signalsFilters` parameter to `POST /bulk/company/v2` to narrow signal results within requested signal types:

- `newsEventTypes` - filter news signals by specific event types (e.g. Partnership, New Customer, Executive Hire)
- `hiringByDepartments` - filter `surgeInHiringByDepartment` signals by department
- `hiringByLocations` - filter `surgeInHiringByLocation` signals by country/state
- Multi-value filters use OR logic; values are not case-sensitive
- Sending `state` without `country` in `hiringByLocations` returns HTTP 400


**Signal Sub-Filters for Company Signals API**
Added optional `filters.include` block to:

- `POST /api/signals/companies`
- `POST /api/signals/companies/search`


Supports the same sub-filter options as above (`newsEventTypes`, `hiringByDepartments`, `hiringByLocations`).

**Company Lookalikes V3**
Added `POST /v3/companies/lookalike` - mirrors the contact lookalikes pattern introduced in v2.1.0:

- Session-based deduplication via `dedupeSessionId`
- Seed inputs via `domains` and `linkedinUrls`
- `exclude` parameter to suppress known accounts
- Returns `domain`, `linkedinUrl`, `name`, `employeeCount`, `industry`, and `location` per result


**Webhooks: Opt-Out Subscription Endpoint**
Added `POST /api/subscriptions/opt-out` - subscribe to real-time notifications when a contact opts out of data processing. Delivers contact identity, opt-out date, and specific data points (emails/phones) that must be removed. Supports multi-tenant setups via `partnerClientId`.

### Changed

- **Contact Lookalikes V3** - Result field `id` renamed to `contactId`; nested company field `id` renamed to `companyId` for clarity
- **Signals API** - `maxResultsPerSignal` is now optional across all 4 signal endpoints (previously required in v2.1.0). When omitted: returns all available signals if no `startDate` is provided, or all signals from `startDate` onward if provided


### Removed

- **Webhooks URL Verification** - Removed the challenge/response URL verification step from webhook subscription creation. Webhook URLs are no longer verified via a GET challenge request when creating or updating subscriptions.


### Notes

- Signal sub-filters reduce response size and credit usage by narrowing results within a signal type without requiring separate requests
- `maxResultsPerSignal` remains available as an optional cap when you want to limit results per signal type


## [2.1.0] - 2026-02-26 - Contact Lookalikes V3 & Signals Rate Control

### Added

**Contact Lookalikes V3**
Replaced `POST /api/recommendations/contacts` with a redesigned endpoint:

- `POST /v3/lookalike/contacts` - returns contact lookalikes based on seed contacts
- Supports multiple seed identifier types: `linkedinUrls`, `emails`, `contactIds`, and `contacts` (name + company)
- Session-based deduplication via `dedupeSessionId` - omit on first request, reuse on subsequent calls
- Session history persists for 30 days from last activity
- `exclude` parameter supports up to 500 contacts across all identifier types
- Seeds require 5-100 total identifiers across all arrays
- Returns `id`, `firstName`, `lastName`, `socialLinks`, `company`, `jobTitle`, and `location` per result


**Signal Rate Control**
Added `maxResultsPerSignal` (required at time of release) to all 4 Signals API endpoints:

- `POST /api/signals/contacts`
- `POST /api/signals/contacts/search`
- `POST /api/signals/companies`
- `POST /api/signals/companies/search`


### Changed

- **Contact Lookalikes** - Endpoint path changed from `/api/recommendations/contacts` to `/v3/lookalike/contacts`. Request and response schemas fully replaced - not backwards compatible.
- **Signals API** - `maxResultsPerSignal` added as a required parameter. Limits the number of signal instances returned per signal type per entity, starting from `startDate`.


### Notes

- The new contact lookalikes endpoint aligns with the existing company lookalikes pattern
- `maxResultsPerSignal` helps control response size and credit consumption, especially when requesting `allSignals` over long date ranges


## [1.8.0] - 2026-02-18 - Company Data Points & News Signal Expansion

### Added

**New Company Data Fields**
Added 7 new data points to Company API V2 (Single & Bulk) and Prospecting Company Enrich API:

- `linkedinFollowers` - LinkedIn followers count
- `emailDomain` - company email domain
- `companyLocations` - array of all known company site locations (not just HQ), each with `city`, `continent`, `country`, `country_iso2`, `location_coordinates`, `state`, `state_code`
- `alternativeName` - normalized alternative company name
- `companyType` - type of company (e.g. "Private company")
- `lushaPopularityTier` - Lusha popularity tier


**New Person Data Fields**
Added LinkedIn enrichment fields to Person API V2 (Single & Bulk) and Prospecting Contact Enrich API:

- `xUrl` - Twitter/X profile URL (`data.socialLinks.xUrl`)
- `linkedinFollowersCount` - LinkedIn followers count
- `linkedinConnectionsCount` - LinkedIn connections count
- `linkedinCertifications` - professional certifications from LinkedIn
- `linkedinCourses` - courses listed on LinkedIn
- `linkedinAwards` - honors and awards from LinkedIn
- `linkedinSkills` - skills listed on LinkedIn profile


**Company Size Enhancements**

- `companySize` object (Single Enrich) now returns `min`, `max`, and `employeesInLinkedin`
- `employeesInLinkedin` added as a flat field to the bulk response


**New News Event Signal Types**
Replaced the generic `newsEvent` signal with 7 granular categories, available across Signals API, Prospecting API, and Webhooks:

- `riskNews` - litigations and security news
- `commercialActivityNews` - launches, partnerships, and go-to-market activity
- `corporateStrategyNews` - M&A, restructuring, or strategic direction changes
- `financialEventsNews` - funding, IPOs, and financial performance events
- `peopleNews` - hiring, layoffs, or leadership changes
- `marketIntelligenceNews` - event participation, recognition, competitor activity
- `productActivityNews` - product launch, development, and integration news


### Changed

- **Company API V2 (Single Enrich)** - `companySize` now returns an object with `min`, `max`, and `employeesInLinkedin` instead of a simple range array
- **Prospecting Company Search** - New news signal types now available as search filters
- **Prospecting Company Enrich** - Response now includes all signal types including new news signal categories
- **Webhooks** - New news signal types are now subscribable event types for company subscriptions


### Notes

- `companyLocations` differs from the existing HQ `location` field - it returns all known company site locations
- The new news signal types replace the previous generic `newsEvent` signal
- All 7 news signal types share the same response schema: `companyId`, `companyName`, `domain`, `signalId`, `eventType`, `eventSummary`, `articlePublishedDate`, `articleTitle`, `articleHighlight`, `eventEffectiveDate`, `articleUrl`


## [1.7.0] - 2026-01-26 - Webhooks API Release

### Added

**New Webhooks API**
Introduced real-time event notifications for contact and company signals via webhooks.

- `POST /api/subscriptions` - create webhook subscriptions (bulk, up to 25 per request) for contact and company signals
- `GET /api/subscriptions` - list all active webhook subscriptions
- `GET /api/subscriptions/{id}` - retrieve a specific subscription
- `PATCH /api/subscriptions/{id}` - update subscription settings
- `POST /api/subscriptions/delete` - delete subscriptions (bulk supported)
- `POST /api/subscriptions/{id}/test` - test delivery with mock payload (no credits consumed)
- `GET /api/audit-logs` - webhook delivery logs
- `GET /api/audit-logs/stats` - delivery statistics
- `GET /api/account/secret` - retrieve webhook secret
- `POST /api/account/secret/regenerate` - regenerate webhook secret


Features include real-time delivery, event filtering by signal type, HMAC-SHA256 signature verification, automatic retry with exponential backoff (max 3 attempts), and delivery audit logs retained for 90 days (successful) and 180 days (failed).

### Notes

- Webhooks are a push-based alternative to polling the Signals API
- Ideal for time-sensitive workflows like triggering outreach on job changes
- Premium feature - standard credit charges apply for signal detection; retries do not incur additional charges


## [1.6.0] - 2025-01-05 - Prospecting API Signal Filtering

### Added

**Signal Filtering for Prospecting Search**
Enhanced Prospecting APIs with signal-based filtering.

- `POST /prospecting/contact/search` - can now filter contacts by `promotion`, `companyChange`, `allSignals`
- `POST /prospecting/company/search` - can now filter companies by `headcountGrowth`, `newJobsOpen`, `newsEvent`, `allSignals`
- `startDate` parameter added for time-based filtering
- Search responses now include a `signalTypes` array indicating detected signals per result


### Notes

- Premium feature - credits are charged for each signal type that returns results
- Works in conjunction with the Signals API for retrieving detailed signal metadata


## [1.5.0] - 2025-10-15 - Recommendations API Release

### Added

- `POST /api/recommendations/contacts` - AI-powered recommendations for similar contacts
- `POST /api/recommendations/companies` - AI-powered recommendations for similar companies


Enables prospect expansion by surfacing net-new contacts and companies with similar attributes to your known leads. Can be used as a downstream step after enrichment, prospecting, or CRM triggers.

### Notes

- These endpoints were superseded by the redesigned Lookalikes V3 endpoints in v2.1.0


## [1.4.0] - 2025-09-30 - Enhanced Search Capabilities

### Added

**New `searchText` Filter**
Free-text search capability for Prospecting APIs, available in both `include` and `exclude` sections:

- `POST /prospecting/contact/search` - supports `searchText` in contacts and companies filter sections
- `POST /prospecting/company/search` - supports `searchText` in companies filter section
- Enables natural language queries like "finance marketing in Germany DE"
- Searches across multiple fields simultaneously


### Changed

- `ContactFilters` and `CompanyFilters` schemas updated to include optional `searchText` property


## [1.3.0] - 2025-09-10 - Signals API Expansion

### Added

**New Signals Endpoints**

- `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 (LinkedIn URL, email, or name + company/domain)
- `POST /signals/companies/search` - retrieve company signals by identifiers (domain, company name, or ID)
- `GET /signals/filters/:objectType` - view available signal filter types for `contact` or `company`


All signal endpoints support `startDate` (optional, defaults to last 6 months).

**Partial Profile Filter**
Added `partialProfile` boolean parameter to contact enrichment APIs for simplified contact profiles.

### Changed

- Enrichment APIs (`v2/person` and `v2/company`, single and bulk) now always return `person_id` and `company_id` where applicable
- Signal filters can now be used as filters in existing enrichment API calls


## Format Reference


```
## [Version] - YYYY-MM-DD - Title

### Added
New features and endpoints

### Changed
Updates to existing functionality

### Fixed
Bug fixes and corrections

### Removed
Deprecated features

### Notes
Additional context
```

## Notifications

- **Email:** Subscribe for release notifications
- **Support:** [support@lusha.com](mailto:support@lusha.com)


## API Versioning

| Version | Status | Support Level |
|  --- | --- | --- |
| 2.2.x | Current | Full support |
| 2.x | Recent | Full support |
| 1.x | Legacy | Security only |


*Last updated: June 2026*