> ## Documentation Index > Fetch the complete documentation index at: https://docs.lusha.com/llms.txt > Use this file to discover all available pages before exploring further. # Contact Lookalikes (Legacy) > Returns contact lookalikes based on seed contacts. *Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/contacts** #### How It Works **First Request (Start a New Run):** - Do not send `dedupeSessionId` - Server generates one and returns it in the response - Use returned `dedupeSessionId` for subsequent "get more" requests **Subsequent Requests ("Get More"):** - Send the returned `dedupeSessionId` to fetch more results without duplicates - Server dedupes against all contacts previously returned for the `dedupeSessionId` - User-provided `exclude.*` is applied on every request and combined with server-side dedupe - Session history retained for 30 days from last activity (sliding window) --- ## OpenAPI ````yaml /v2/openapi.json post /v3/lookalike/contacts openapi: 3.0.3 info: title: Lusha API Documentation version: 0.0.1 x-logo: url: https://www.lusha.com/logo.png license: name: Proprietary url: https://lusha.com/legal/terms description: > Lusha provides a RESTful API that allows you to query a comprehensive dataset of business profiles and company information. It is designed for teams building prospecting, enrichment, automation, and analytics workflows that require accurate, continuously updated business data. The API supports both real-time and bulk use cases and is suitable for production environments. Use the Lusha API to search for new prospects, enrich existing records, react to real-world changes, and expand coverage using lookalike recommendations. *All API requests should be made over HTTPS (SSL), and the response bodies are delivered in JSON format.* ---

Person

• Person Enrichment
• Contact Search & Enrich

https://api.lusha.com/v2/person

▶ Common Use Cases

• Form enrichment
• CRM completion
• Outbound personalization

Company

• Company Enrichment
• Company Search & Enrich

https://api.lusha.com/v2/company

▶ Common Use Cases

• Account enrichment
• Routing, scoring, territory logic
• Market analysis & segmentation

Signals

• Contact Signals
• Company Signals

https://api.lusha.com/v2/signals

▶ Common Use Cases

• Job change tracking
• Company updates signals
• News event alerts

Lookalikes

• Similar Contacts
• Similar Companies

https://api.lusha.com/v3/lookalike

▶ Common Use Cases

• Market expansion
• Similar account discovery
• Prospect recommendations

Filters

Account

Webhooks API **NEW**

Subscribe to real-time notifications when contacts change jobs or companies experience key business events.

View Documentation →

--- **Data Source and Privacy** Please note that **Lusha is a search platform**, meaning the data provided is not created or directly managed by us. Instead, it is retrieved from publicly available sources and through contributions from trusted business partners. For more information on how we collect, use, and handle business profiles, please refer to our [Privacy Policy](https://lusha.com/legal/privacy-notice/). ---- ## Authentication API keys are required for all API and MCP requests and are tied to your Lusha account and plan. To access the Lusha API, you must authenticate your requests using your API key. This key is unique to your account and is used to identify your usage of the API. How to Authenticate: When making an API call, include your API key in the `api_key` header of the request. > You can generate and retrieve your API key [here](https://dashboard.lusha.com/api/manage-api-keys). API keys should be stored securely and used only in server-side environments. --- ### Rate Limiting Lusha API enforces rate limiting to ensure fair usage and protect against excessive load. - **General Rate Limit**: You can make up to 25 requests per second to each API endpoint - **Credit Usage API**: Has a specific rate limit of 5 requests per minute > **Note**: Rate limits may vary based on your account type and subscription plan. If you're encountering rate limit issues frequently, please consult with your account manager or Lusha support team to discuss your specific needs. **Rate Limit Headers** To monitor your current rate limit status, check the HTTP response headers in your API calls: | Header | Description | |--------|-------------| | `x-rate-limit-daily` | The total number of requests allowed per day under your current plan | | `x-daily-requests-left` | The number of requests remaining in your daily quota | | `x-daily-usage` | The number of requests you have made in the current daily period | | `x-rate-limit-hourly` | The total number of requests allowed per hour under your current plan | | `x-hourly-requests-left` | The number of requests remaining in your hourly quota | | `x-hourly-usage` | The number of requests you have made in the current hourly period | | `x-rate-limit-minute` | The total number of requests allowed per minute under your current plan | | `x-minute-requests-left` | The number of requests remaining in your current minute window | | `x-minute-usage` | The number of requests you have made in the current minute window | **Notes on API Rate Limiting** - If you exceed the rate limit, the API will return a 429 (Too Many Requests) error. - To ensure a smooth experience, respect the rate limits defined by your subscription tier. - Daily limits vary based on your billing plan — higher tiers have higher quotas. - You can programmatically track your usage through these response headers: - `X-RateLimit-Remaining-Daily` - `X-RateLimit-Reset-Daily` - It is strongly recommended to implement logic that: - Monitors these headers - Pauses or retries requests accordingly - Helps avoid hitting the limit and ensures reliable operation --- ## Error Codes Lusha API uses standard HTTP response codes to indicate the status of your request. These codes help you understand whether the request was successful or if there was an issue. | Status Code | Name | Description | |-------------|------|-------------| | **200** | OK | Successful request | | **400** | Bad Request | Badly formatted request | | **401** | Unauthorized | The API key is invalid | | **402** | Payment Required | Your account requires payment | | **403** | Forbidden | Your account is not active. Please reach out to support at *support@lusha.com* for assistance | | **403** | Forbidden | Your pricing version does not support requesting individual datapoints [revealEmails, revealPhones] | | **404** | Not Found | The requested endpoint was not found | | **412** | Precondition Failed | The request failed due to invalid syntax that was provided. Please make sure to send a full name field that contains a valid first & last name | | **429** | Too Many Requests | You've reached your trial limit, please contact support for upgrade | | **429** | Too Many Requests | Daily API quota limit exceeded. Limit X calls per day | | **429** | Too Many Requests | Hourly API rate limit exceeded. Limit: X calls per hour. Reset in X seconds | | **451** | Unavailable For Legal Reasons | We are unable to process this contact request due to our GDPR regulations | | **499** | Client Closed Request | Request failed due to request timeout | | **5XX** | Server Error | There's a problem on Lusha's end | **Error Response Format** In case of an error, the response body will contain details about the error: ```json { "error": { "code": 400, "message": "Invalid request parameters" } } ``` Handling errors - Always ensure your API key is correct and valid - Pay attention to the specific error message and code to troubleshoot issues efficiently - Implement proper error handling and retry logic in your application - For 5XX errors, implement exponential backoff before retrying --- contact: name: Lusha Support url: https://api.lusha.com email: support@lusha.com termsOfService: https://lusha.com/legal/terms x-privacy-policy: name: Privacy Policy url: https://lusha.com/legal/privacy-notice/ servers: - url: https://api.lusha.com description: Production server security: - ApiKeyAuth: [] tags: - name: Enrichment description: >- **What is enrichment?**: Enrichment is the process of adding missing or updated data to existing contact or company records. Use enrichment to: - Complete CRM records - Improve outbound accuracy and deliverability - Keep records current as people and companies change > Enrichment can be performed in real time or in bulk, depending on the endpoint and use case. **Available enrichment APIs** Person enrichment: - [**Search single contact**](/apis/openapi/enrichment/searchsinglecontact) - Enrich one contact at a time - [**Search multiple contacts**](/apis/openapi/enrichment/searchmultiplecontacts) - Bulk enrich contacts Company enrichment: - [**Search a single company**](/apis/openapi/enrichment/searchsinglecompanyv2) - Enrich one company at a time - [**Search multiple companies**](/apis/openapi/enrichment/searchmultiplecompaniesv2) - Bulk enrich companies - name: Prospecting - Search & Enrich description: > With Lusha's Prospecting API, you can query Lusha's extensive database based on specific criteria (such as job title, seniority, location, and more) to retrieve detailed contact and company information. The Prospecting API is designed to help you generate new records (contacts or companies) for your CRM system, using filters that align with your Ideal Customer Profile (ICP). This process involves three main steps: | Step | API | Description | |------|-----|-------------| | 1 | **Filters API** | Apply filters to refine your search *(Check available filters under [Contact](/apis/openapi/contact-filters) and [Company](/apis/openapi/company-filters) Filters)*| | 2 | **Search API** | Query [Contacts](/apis/openapi/prospecting-search-and-enrich/searchprospectingcontacts) or [Companies](/apis/openapi/prospecting-search-and-enrich/searchprospectingcompanies) using the available filters | | 3 | **Enrich API** | Get full details of [Contacts](/apis/openapi/prospecting-search-and-enrich/enrichprospectingcontacts) and [Companies](/apis/openapi/prospecting-search-and-enrich/enrichprospectingcompanies) from the search results | x-tag-expanded: true - name: Contact Filters description: Available filters for contact searches x-parent-tag: Prospecting - name: Company Filters description: Available filters for company searches x-parent-tag: Prospecting - name: Signals description: >- With Lusha’s Signals API, you can enrich your contacts and companies with timely insights that highlight key account and prospect changes. Signals help you identify moments of opportunity - from job moves and promotions to company growth and new initiatives - so you can engage prospects and customers at exactly the right time. Easily integrate signal data into enrichment flows, CRM systems, or automation workflows to keep pipelines and customer records always up to date. x-tag-expanded: true - name: Lookalikes description: >- Lusha's Lookalikes API helps you discover similar contacts and companies based on your existing data. Get AI-powered suggestions for new prospects that match your ideal customer profile. [**Contact Lookalikes**](/apis/openapi/lookalikes/getcontactlookalikes) - Find similar contacts based on role, seniority, and industry patterns. [**Company Lookalikes**](/apis/openapi/lookalikes/getcompanylookalikes)- Discover companies with similar firmographics and characteristics. x-tag-expanded: true - name: Webhooks description: > Subscribe to real-time notifications when contacts change jobs or companies experience key business events. Webhooks deliver HTTP POST requests to your endpoints when signals occur - from promotions and job changes to company growth. > For a full list of available signals, refer to [**Signal Options**](https://docs.lusha.com/apis/openapi/signals/getsignaloptions). --- **Key Features:** - Real-time contact & company signal notifications - Bulk subscription management (up to 25 items per request) - Secure delivery with HMAC-SHA256 signatures - Delivery monitoring with audit logs **Available Endpoints:** | Method | Endpoint | Purpose | |--------|----------|---------| | POST | `/api/subscriptions` | Create subscriptions (bulk supported) | | GET | `/api/subscriptions` | List all subscriptions | | GET | `/api/subscriptions/{id}` | Get subscription by ID | | PATCH | `/api/subscriptions/{id}` | Update subscription | | POST | `/api/subscriptions/delete` | Delete subscriptions (bulk supported) | | POST | `/api/subscriptions/{id}/test` | Test subscription delivery | | GET | `/api/audit-logs` | Get webhook delivery logs | | GET | `/api/audit-logs/stats` | Get delivery statistics | | GET | `/api/account/secret` | Get account webhook secret | | POST | `/api/account/secret/regenerate` | Regenerate account secret | > **Webhook Delivery Acknowledgment:** When receiving webhook deliveries (POST requests), your endpoint must acknowledge with a specific response format. See the [Create Subscription](#operation/createSubscription) endpoint for the required acknowledgment structure. ---

Rate Limits

| Operation | Limit | |-----------|-------| | API Requests | 100 requests/minute per account | | Create Subscriptions | 25 items per request | | Delete Subscriptions | 25 items per request |

---

Security & Verification

**HTTPS Requirement:** - Production webhook URLs **must** use HTTPS - HTTP URLs are not accepted **Signature Verification:** All webhook deliveries include an `X-Lusha-Signature` header containing an HMAC-SHA256 signature. Verify this signature to ensure the request is from Lusha: 1. Extract the `X-Lusha-Signature` and `X-Lusha-Timestamp` headers 2. Concatenate: `timestamp + "." + JSON.stringify(payload)` 3. Compute HMAC-SHA256 using your webhook secret 4. Compare the computed signature with the received signature **Example (Node.js):** ```javascript const crypto = require('crypto'); function verifySignature(payload, signature, timestamp, secret) { const signedPayload = `${timestamp}.${JSON.stringify(payload)}`; const expectedSignature = crypto .createHmac('sha256', secret) .update(signedPayload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); } ``` > **Security Best Practice:** Always verify webhook signatures to prevent spoofed requests.

---

Credits & Billing

**Credit Charges:** - Credits are charged when signals are detected and delivered to your webhook - The `creditsCharged` field in the webhook payload indicates how many credits were used - Credits are deducted from your account balance per signal type **No Duplicate Charges:** - Each signal is delivered once and charged once - Webhook delivery retries do not incur additional charges

---

Error Response Format

All error responses follow this format: ```json { "statusCode": 400, "message": "Validation failed", "errors": ["entityType must be one of: contact, company"] } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | number | HTTP status code | | `message` | string | Error message | | `errors` | string[] | Detailed error messages (optional) |

--- - name: Account Management description: > Manage your account and monitor usage. Use this endpoint to: - Monitor credit usage - Understand consumption patterns - Align API usage with plan limits - Support governance and production operations Account-level insights are especially important for teams running Lusha at scale or across multiple systems. paths: /v3/lookalike/contacts: post: tags: - Lookalikes summary: Contact Lookalikes (Legacy) description: > Returns contact lookalikes based on seed contacts. *Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/contacts** #### How It Works **First Request (Start a New Run):** - Do not send `dedupeSessionId` - Server generates one and returns it in the response - Use returned `dedupeSessionId` for subsequent "get more" requests **Subsequent Requests ("Get More"):** - Send the returned `dedupeSessionId` to fetch more results without duplicates - Server dedupes against all contacts previously returned for the `dedupeSessionId` - User-provided `exclude.*` is applied on every request and combined with server-side dedupe - Session history retained for 30 days from last activity (sliding window) --- operationId: getContactLookalikes requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactLookalikesRequest' examples: firstRequest: summary: First request (server generates dedupeSessionId) value: seeds: linkedinUrls: - https://www.linkedin.com/in/johndoe emails: - jane@acme.com - bob@example.com contacts: - firstName: Alice lastName: Smith companyDomain: sap.com contactIds: - 1234 - 4567 exclude: emails: - existing@customer.com linkedinUrls: - https://www.linkedin.com/in/already-contacted/ contactIds: - 9999 limit: 25 secondRequestGetMore: summary: Second request (get more using dedupeSessionId) value: dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613 seeds: linkedinUrls: - https://www.linkedin.com/in/johndoe emails: - jane@acme.com - bob@example.com contacts: - firstName: Alice lastName: Smith companyDomain: sap.com contactIds: - 1234 - 4567 exclude: emails: - existing@customer.com linkedinUrls: - https://www.linkedin.com/in/already-contacted/ contactIds: - 9999 limit: 25 responses: '200': description: Successfully retrieved contact lookalikes content: application/json: schema: $ref: '#/components/schemas/ContactLookalikesResponse' examples: firstResponse: summary: Example response (first request) value: dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613 results: - contactId: '9659196' firstName: Sarah lastName: Johnson socialLinks: linkedin: https://www.linkedin.com/in/sarahjohnson company: companyId: '8605368' name: Marriott International domain: marriott.com jobTitle: title: VP of Sales departments: - Sales seniority: Director location: country: United States state: Maryland city: Bethesda meta: returned: 1 hasMore: true creditsCharged: 3 secondResponse: summary: Example response (get more) value: dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613 results: - contactId: '9659197' firstName: Michael lastName: Davis socialLinks: linkedin: https://www.linkedin.com/in/michaeldavis company: companyId: '8605369' name: Hilton domain: hilton.com jobTitle: title: Sales Director departments: - Sales seniority: Director location: country: United States state: Virginia city: McLean meta: returned: 1 hasMore: true '400': $ref: '#/components/responses/BadRequest' '402': description: Insufficient credits '403': $ref: '#/components/responses/Forbidden' '410': description: dedupeSessionId is invalid or expired content: application/json: schema: $ref: '#/components/schemas/DedupeSessionInvalidError' example: code: DEDUPE_SESSION_INVALID message: >- The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run. '500': $ref: '#/components/responses/InternalServerError' components: schemas: ContactLookalikesRequest: type: object additionalProperties: false required: - seeds properties: dedupeSessionId: type: string format: uuid description: > Dedupe session identifier. Omit on the first request to start a new run (server generates one). Provide on subsequent requests to get more results without duplicates. example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613 seeds: $ref: '#/components/schemas/ContactIdentifiersBatch' exclude: $ref: '#/components/schemas/ContactIdentifiersBatch' limit: type: integer minimum: 1 maximum: 100 default: 25 description: Number of results to return per call (1-100) example: 25 ContactLookalikesResponse: type: object additionalProperties: false required: - dedupeSessionId - results - meta properties: dedupeSessionId: type: string format: uuid nullable: true description: > Server-generated session id to use for subsequent "get more" requests. Null when no results on first request. example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613 results: type: array description: Lookalike contacts items: $ref: '#/components/schemas/LookalikeContactResult' meta: $ref: '#/components/schemas/ContactLookalikesMeta' creditsCharged: type: integer description: Number of credits charged for this request example: 3 minimum: 0 DedupeSessionInvalidError: type: object additionalProperties: false required: - code - message properties: code: type: string example: DEDUPE_SESSION_INVALID message: type: string example: >- The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run. ContactIdentifiersBatch: type: object additionalProperties: false description: > Identifier batch for contact inputs. Provide at least one of linkedinUrls, contacts, emails, or contactIds. For seeds: total unique identifiers across all arrays must be 5-100. For exclude: total must be at most 500. properties: linkedinUrls: type: array items: type: string description: LinkedIn profile URL maxItems: 100 example: - https://www.linkedin.com/in/johndoe contacts: type: array items: $ref: '#/components/schemas/ContactItem' maxItems: 100 emails: type: array items: type: string format: email description: Contact email maxItems: 100 example: - john@acme.com contactIds: type: array items: type: integer description: Lusha person ID maxItems: 100 example: - 1234 - 4567 minProperties: 1 nullable: true LookalikeContactResult: type: object additionalProperties: false properties: contactId: type: string description: Lusha person ID example: '9659196' firstName: type: string nullable: true description: First name example: Sarah lastName: type: string nullable: true description: Last name example: Johnson socialLinks: type: object properties: linkedin: type: string nullable: true description: LinkedIn profile URL example: https://www.linkedin.com/in/sarahjohnson company: type: object properties: companyId: type: string description: Company ID example: '8605368' name: type: string nullable: true description: Company name example: Marriott International domain: type: string nullable: true description: Company domain example: marriott.com jobTitle: type: object properties: title: type: string nullable: true description: Job title example: VP of Sales departments: type: array items: type: string description: Departments example: - Sales seniority: type: string nullable: true description: Seniority level example: Director location: $ref: '#/components/schemas/ContactLocation' ContactLookalikesMeta: type: object additionalProperties: false required: - returned - hasMore properties: returned: type: integer description: Number of results returned in this response example: 25 hasMore: type: boolean description: >- Indicates whether more results are available for the same seeds + dedupeSessionId example: true ErrorResponse: type: object required: - statusCode - message properties: statusCode: type: integer description: HTTP status code example: 400 message: type: string description: Error message example: Validation failed errors: type: array items: type: string description: Detailed error messages (optional, only for validation errors) example: - 'entityType must be one of: contact, company' ContactItem: type: object additionalProperties: false required: - firstName - lastName properties: firstName: type: string description: First name example: John lastName: type: string description: Last name example: Doe companyDomain: type: string description: Company domain (e.g., acme.com) example: acme.com companyName: type: string description: Company name (alternative to companyDomain) example: Acme Inc description: At least one of companyDomain or companyName is required. ContactLocation: type: object additionalProperties: false properties: country: type: string nullable: true example: United States state: type: string nullable: true example: Maryland city: type: string nullable: true example: Bethesda responses: BadRequest: description: Bad request - invalid input data content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 400 message: Invalid request parameters Forbidden: description: Forbidden - account inactive or feature not available content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountInactive: summary: Account inactive value: statusCode: 403 message: >- Your account is not active. Please reach out to support at support@lusha.com featureNotAvailable: summary: Feature not available for pricing plan value: statusCode: 403 message: >- Your pricing version does not support requesting individual datapoints [revealEmails, revealPhones] subscriptionLimitReached: summary: Subscription limit reached value: statusCode: 403 message: Maximum subscriptions limit reached for your account dncNotSupported: summary: DNC filter not supported on current plan value: statusCode: 403 message: >- Exclude DNC is not supported on your current plan. Please contact support or your account manager for assistance. InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 500 message: Internal server error. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key description: > Your Lusha API key. You can find this in your Lusha dashboard under API settings. Include this key in the `api_key` header for all requests. ```` ## Related topics - [Company Lookalikes (Legacy)](https://docs.lusha.com/api-reference/lookalikes/company-lookalikes-legacy.md) - [Discover lookalike contacts and companies with AI](https://docs.lusha.com/v2/lookalikes/overview.md) - [Lusha Lookalikes: Finding similar contacts and companies](https://docs.lusha.com/user-guide/getting-started-with-prospecting/lusha-lookalikes-finding-similar-contacts-and-companies.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.