# Changelog

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

## Current Version: 2.0.0

**Status:** Production • **Released:** 2025 • **Stability:** Stable

### Rate Limits

- Person enrichment: 25 req/sec
- Account usage: 5 req/min
- Webhooks API: Refer to [this section](https://wys-01jv5ezg32t3we6dsc9j04h4t3.wysiwyg.cloud.redocly.com/apis/openapi/webhooks)


## Changelog History


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

### Added

**Contact Lookalikes V3**
Replaced `POST /api/recommendations/contacts` with a new v3 endpoint with expanded seed input options and session-based deduplication:
- `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 "get more" 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) 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` is now a required parameter on all signal retrieval endpoints. 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 (`/v3/lookalike/companies`)
- `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 for the company
- `emailDomain` – Company email domain
- `companyLocations` – Array of all known company site locations (not just HQ). Each location includes: `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 new 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 (`data.linkedinFollowersCount`)
- `linkedinConnectionsCount` – LinkedIn connections count (`data.linkedinConnectionsCount`)
- `linkedinCertifications` – Professional certifications from LinkedIn (`data.linkedinCertifications`)
- `linkedinCourses` – Courses listed on LinkedIn (`data.linkedinCourses`)
- `linkedinAwards` – Honors and awards from LinkedIn (`data.linkedinAwards`)
- `linkedinSkills` – Skills listed on LinkedIn profile (`data.linkedinSkills`)

**Company Size Enhancements**
- `companySize` object (Single Enrich): Now returns `min`, `max`, and `employeesInLinkedin`
- `employeesInLinkedin` (Bulk Enrich): Added as a flat field to the bulk response

**New News Event Signal Types**
Replaced the generic `newsEvent` signal with 7 granular news event 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** (`POST /prospecting/company/search`): New news signal types now available as search filters
- **Prospecting Company Enrich** (`POST /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 follow the same response schema with fields: `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 /subscriptions
- Create webhook subscriptions to receive real-time notifications for:
  - **Contact signals**: Job changes, promotions, and career events
  - **Company signals**: Headcount growth, new job openings, news events, and business updates
- Configure webhook endpoints to receive event payloads automatically
- Manage multiple subscriptions with custom filters and event types

#### GET /subscriptions
- List all active webhook subscriptions
- View subscription configuration and status

#### GET /subscriptions/{subscriptionId}
- Retrieve details for a specific webhook subscription
- Monitor subscription health and delivery status

#### PUT /subscriptions/{subscriptionId}
- Update existing webhook subscription settings
- Modify event types, filters, and webhook endpoints

#### DELETE /subscriptions/{subscriptionId}
- Remove webhook subscriptions when no longer needed

### Features
- **Real-time Delivery**: Receive instant notifications when signals occur
- **Event Filtering**: Subscribe to specific signal types (promotion, job change, headcount growth, etc.)
- **Webhook Security**: Includes signature verification for secure payload validation
- **Retry Logic**: Automatic retry mechanism for failed webhook deliveries
- **Event History**: Track webhook delivery status and payload history

### Notes
- Webhooks provide a push-based alternative to polling the Signals API
- Ideal for time-sensitive workflows like triggering outreach on job changes
- Reduces API calls by receiving only relevant updates as they happen
- Works in conjunction with the existing Signals API for detailed signal metadata
- Premium feature — standard credit charges apply for signal detection

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

### Added

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

#### POST /prospecting/contact/search
- Can now filter contacts by signal types:
  - `promotion`
  - `companyChange`
  - `allSignals`

#### POST /prospecting/company/search
- Can now filter companies by signal types:
  - `headcountGrowth`
  - `newJobsOpen`
  - `newsEvent`
  - `allSignals`

#### Temporal Filtering
- Added a `startDate` parameter to enable time-based filtering of signals.

#### Response Enhancements
- Search responses now return a `signalTypes` array, indicating the detected signals for each contact or company.

### Changed

- **Prospecting Search Response**
  - Added `signalTypes` field to both contact and company search results.

- **Prospecting Search Request**
  - Added a `signal` object to filter options, including:
    - `names` (array of signal types)
    - Optional `startDate`

### Notes
- This is a premium feature — credits are charged for each signal type that returns results.
- Enables targeted prospecting by identifying contacts at key career moments (e.g. promotions, job changes).
- Enables company targeting based on business events (e.g. growth, hiring activity, news).
- Works in conjunction with the existing Signals API for retrieving detailed signal metadata.
--- 

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

### Added
- **New Recommendations Endpoints**:
  - `POST /api/recommendations/contacts` – Get AI-powered recommendations for similar contacts
  - `POST /api/recommendations/companies` – Get AI-powered recommendations for similar companies
- **Recommendations API Overview**:
  - Discover look-alike prospects based on your existing contact or company data
  - Uses AI models to surface highly relevant profiles aligned with your ICP
  - Supports workflows for prospecting expansion, upsell targeting, and account-based outreach

### Notes
- This release introduces Lusha’s first recommendation engine designed to help you scale prospecting by suggesting net-new contacts and companies with similar attributes to your known leads.
- Recommendations can be used as a downstream step after enrichment, prospecting, or CRM triggers.

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

### Added
- **New searchText Filter**: Introduced free-text search capability for Prospecting APIs
  - Available in both `include` and `exclude` sections for contact and company filters
  - `POST /prospecting/contact/search` – Supports searchText in both `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 (names, titles, descriptions, locations)

### Changed
- **Prospecting Search Schemas**: Updated `ContactFilters` and `CompanyFilters` to include optional `searchText` property
  - Contact filters: Can search/exclude across contact names, titles, and related text fields
  - Company filters: Can search/exclude across company names, descriptions, and locations

### Notes
- The searchText filter provides a more flexible and intuitive way to search the Prospecting database
- Supports complex queries combining multiple criteria in a single text string
- Can be combined with existing structured filters for more precise targeting
- Both positive (include) and negative (exclude) text filtering is supported

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

### Added
- **New Signals Endpoints**: Introduced 4 endpoints for contact and company signals, supporting enrichment by IDs and identifiers:
  - `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)
- **Signals Filters Endpoint**:
  - `GET /signals/filters/:objectType` – View available signal filters for `contact` or `company`
  - `allFilters` option available to view all signals
- **Timeframe Filtering**: All signal endpoints support `start_date` (optional) with default range of last 6 months
- **Partial Profile Filter**: Added `partialProfile` boolean parameter to contact enrichment APIs for simplified contact profiles

### Changed
- **Enrichment APIs**: Expanded `v2/person` (single & bulk) and `v2/company` (single & bulk) to always return `person_id` and `company_id` where applicable
- **Signal Filters Usage**: Existing enrichment APIs can now leverage signals as filters

### Notes
- The new Signals suite allows deeper insights into contact and company activity
- Timeframe filtering provides flexibility while defaulting to recent (6 months) signals
- Partial profiles provide a lightweight option for basic contact information retrieval
```

### Format


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

### Added
- New features and endpoints

### Changed  
- Updates to existing functionality

### Fixed
- Bug fixes and corrections

### Removed
- Deprecated features

### Security
- Security improvements
```

## Notifications

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


## API Versioning

| Version | Status | Support Level |
|  --- | --- | --- |
| 2.0.x | Current | Full support |
| 1.x | Legacy | Security only |


*Last updated: February 2026*