Skip to content
Last updated

Changelog

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

Current Version: 2.4.0

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

Changelog History

[2.4.0] - 2026-06-08 - Decision Makers API

Added

Decision Makers API Added POST /v3/contacts/decision-makers - resolve companies to their most relevant contacts for outreach.

  • Supply companies by domain or Lusha company id (exactly one per entry); up to N companies per request
  • Optional clientReferenceId per entry is echoed back in the matching result for correlation
  • Results are grouped per company with decision makers ranked by relevance (highest first)
  • Each decision maker is returned as a free contact preview: name, title, location, LinkedIn, seniority, department, has, and canReveal
  • Pass the returned contact id values to Enrich Contacts (POST /v3/contacts/enrich) to reveal emails and phones
  • Companies that cannot be matched return a per-item NOT_FOUND error without failing the entire request

Notes

  • Free for MVP (creditsCharged: 0 on all responses)
  • Encrypted company IDs (vN.…) are supported; legacy numeric IDs are accepted during the transition window
  • Decision makers are returned as V3ContactPreview objects - the same shape as Search Contacts results

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

Added

Website Visits API Added POST /v3/companies/website-visits - identify and filter companies that have visited your tracked domains.

  • Filter by engagement score band (cold, warm, hot) via filters.scoreBands
  • Filter by session metrics: totalSessions, uniqueVisitors, avgSessionMinutes, daysVisited, highIntentPageviews, daysSinceLastVisit
  • Filter by score range via filters.score (min/max, 1–100)
  • Filter by geography via filters.visitorCountries with include and exclude arrays (ISO 3166-1 alpha-2 codes)
  • Sort results by any metric field via sort.by and sort.order (asc or desc)
  • Paginate via pagination.limit (max 150) and pagination.offset
  • Date range window cannot exceed 3 months

Domains must be configured for tracking in the Lusha dashboard before use. If any requested domain is not configured, the entire request fails with 400. Each result includes a V3 company firmographic preview (same shape as Search Companies) plus behavioral visit metrics. Pass the returned company id 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
  • Each result includes score, scoreBand, totalSessions, uniqueVisitors, avgSessionMinutes, daysVisited, highIntentPageviews, daysSinceLastVisit, lastVisit, and visitorCountry

[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

API Versioning

VersionStatusSupport Level
2.2.xCurrentFull support
2.xRecentFull support
1.xLegacySecurity only

Last updated: June 2026

Previous page
Next page
Terms
Copyright © Lusha. All rights reserved.