Lusha Lookalikes API
AI-powered similarity search that expands a seed list of contacts or companies into comparable profiles, with exclusion lists, a dedupe session id and optional persistence into a Lusha table.
AI-powered similarity search that expands a seed list of contacts or companies into comparable profiles, with exclusion lists, a dedupe session id and optional persistence into a Lusha table.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/lusha-lookalike-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Lusha Lookalikes API
version: ''
contact:
name: Lusha Support
url: https://api.lusha.com
email: support@lusha.com
license:
name: Proprietary
url: https://lusha.com/legal/terms
termsOfService: https://lusha.com/legal/terms
x-logo:
url: https://www.lusha.com/logo.png
x-privacy-policy:
name: Privacy Policy
url: https://lusha.com/legal/privacy-notice/
description: 'Operations tagged Lookalikes across 2 of this provider''s published API definitions: lusha-openapi.yml, lusha-v2-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.lusha.com
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Lookalikes
description: '**Lookalike APIs:** Use AI-powered recommendations to discover contacts and companies similar to your best existing customers. The Contact Lookalikes and Company Lookalikes endpoints return paginated results you can pipe directly into Enrich for full data.
Pass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables) or [Companies Tables](#tag/Companies-Tables).
'
x-tag-expanded: true
paths:
/v3/contacts/lookalike:
post:
tags:
- Lookalikes
summary: Contact Lookalikes
operationId: getContactLookalikes
description: 'Find contacts similar to a set of seed contacts using AI-powered recommendations.
Provide 5-100 seed contacts via LinkedIn URLs, emails, Lusha IDs, or name + company. The API returns contacts who share similar roles, seniority, and company profiles.
**Pagination without duplicates:**
On your first request, omit `dedupeSessionId` — the server generates one and returns it. Pass it on every subsequent request to get more results without repeating contacts already seen. Sessions are retained for 30 days.
Use the `exclude` field to always filter out specific contacts (e.g. existing customers).
Results are lightweight previews. Use Enrich Contacts with the returned `id` to get emails and phones.
> **Billing:** Charged per result via the `lookalikeContact` action.
> **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. See [Contacts Tables](#tag/Contacts-Tables).
'
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/orit-shilvock-6243bb5
emails:
- gal.ashkelon@lusha.com
ids:
- '1234'
exclude:
emails:
- existing@customer.com
limit: 25
secondRequest:
summary: Second request (get more using dedupeSessionId)
value:
dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
seeds:
linkedinUrls:
- https://www.linkedin.com/in/shmulikwillinger
limit: 25
responses:
'200':
description: Successfully retrieved contact lookalikes
content:
application/json:
schema:
$ref: '#/components/schemas/ContactLookalikesResponse'
example:
dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
results:
- id: '9659196'
firstName: Sarah
lastName: Johnson
meta:
returned: 1
hasMore: true
billing:
creditsCharged: 3
resultsReturned: 1
'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'
'500':
$ref: '#/components/responses/InternalServerError'
servers:
- url: https://api.lusha.com
description: Production server
/v3/companies/lookalike:
post:
tags:
- Lookalikes
summary: Company Lookalikes
operationId: getCompanyLookalikes
description: 'Find companies similar to a set of seed companies using AI-powered recommendations.
Provide 5-100 seed companies via domains or LinkedIn URLs. The API returns companies with similar size, industry, and profile.
**Pagination without duplicates:**
On your first request, omit `dedupeSessionId` — the server generates one and returns it. Pass it on every subsequent request to get more results without repeating companies already seen. Sessions are retained for 30 days.
Use the `exclude` field to always filter out specific companies (e.g. existing customers or competitors).
Results are lightweight previews. Use Enrich Companies with the returned `id` to get full firmographic data.
> **Billing:** Charged per result via the `lookalikeCompany` action.
> **Persisting to a table:** Pass `tableId` to also persist matching results into an existing table. See [Companies Tables](#tag/Companies-Tables).
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookalikesRequest'
examples:
firstRequest:
summary: First request (server generates dedupeSessionId)
value:
seeds:
domains:
- sap.com
- oracle.com
linkedinUrls:
- https://www.linkedin.com/company/google
exclude:
domains:
- existingcustomer.com
limit: 100
secondRequest:
summary: Second request (get more using dedupeSessionId)
value:
dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
seeds:
domains:
- sap.com
limit: 100
responses:
'200':
description: Successfully retrieved company lookalikes
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookalikesResponse'
example:
dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
results:
- id: '12345'
name: Marriott International
domain: marriott.com
meta:
returned: 1
hasMore: true
billing:
creditsCharged: 3
resultsReturned: 1
'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/ErrorResponse'
'500':
$ref: '#/components/responses/InternalServerError'
servers:
- url: https://api.lusha.com
description: Production server
/v3/lookalike/contacts:
post:
tags:
- Lookalikes
summary: Contact Lookalikes
description: "Returns contact lookalikes based on seed contacts.\n\n*Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/contacts**\n\n\n #### How It Works\n\n\n**First Request (Start a New Run):**\n- Do not send `dedupeSessionId`\n- Server generates one and returns it in the response\n- Use returned `dedupeSessionId` for subsequent \"get more\" requests\n\n**Subsequent Requests (\"Get More\"):**\n- Send the returned `dedupeSessionId` to fetch more results without duplicates\n- Server dedupes against all contacts previously returned for the `dedupeSessionId`\n- User-provided `exclude.*` is applied on every request and combined with server-side dedupe\n- Session history retained for 30 days from last activity (sliding window)\n---\n"
operationId: getContactLookalikes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactLookalikesRequest_2'
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_2'
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_2'
'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'
servers:
- url: https://api.lusha.com
description: Production server
/v3/lookalike/companies:
post:
tags:
- Lookalikes
summary: Company Lookalikes
description: "Returns company lookalikes based on seed companies.\n\n*Endpoint*: **(POST) https://api.lusha.com/v3/lookalike/companies**\n\n\n #### How It Works\n\n\n**First Request (Start a New Run):**\n- Do not send `dedupeSessionId`\n- Server generates one and returns it in the response\n- Use returned `dedupeSessionId` for subsequent \"get more\" requests\n\n**Subsequent Requests (\"Get More\"):**\n- Send the returned `dedupeSessionId` to fetch more results without duplicates\n- Server uses `dedupeSessionId` to deduplicate companies already returned\n- Session history retained for 30 days from last activity (sliding window)\n---\n"
operationId: getCompanyLookalikes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookalikesRequest_2'
examples:
firstRequest:
summary: First request (server generates dedupeSessionId)
value:
seeds:
domains:
- sap.com
- oracle.com
- the-company.com
linkedinUrls:
- https://www.linkedin.com/company/google
- https://www.linkedin.com/company/someone
exclude:
domains:
- existingcustomer.com
- already-sent.com
linkedinUrls:
- https://www.linkedin.com/company/already-sent/
limit: 100
secondRequest:
summary: Second request (get more using dedupeSessionId)
value:
dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
seeds:
domains:
- sap.com
- oracle.com
- the-company.com
linkedinUrls:
- https://www.linkedin.com/company/google
- https://www.linkedin.com/company/someone
exclude:
domains:
- existingcustomer.com
- already-sent.com
linkedinUrls:
- https://www.linkedin.com/company/already-sent/
limit: 100
responses:
'200':
description: Successfully retrieved company lookalikes
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookalikesResponse_2'
examples:
firstResponse:
summary: Example response (first request)
value:
dedupeSessionId: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
results:
- domain: marriott.com
linkedinUrl: https://www.linkedin.com/company/marriott-international
name: Marriott International
employeeCount: 255334
industry: Hospitality
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:
- domain: hilton.com
linkedinUrl: https://www.linkedin.com/company/hilton
name: Hilton
employeeCount: 173000
industry: Hospitality
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_2'
'410':
description: dedupeSessionId is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 410
errors:
- 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'
servers:
- url: https://api.lusha.com
description: Production server
components:
responses:
Forbidden:
description: Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
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
v3NotEnabled:
summary: V3 access not enabled
value:
statusCode: 403
message: V3 API access is not enabled for your account
BadRequest:
description: Bad request - invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: Invalid request parameters
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 500
message: Internal server error. Please try again later.
Forbidden_2:
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.
schemas:
CompanyLookalikesMeta:
type: object
required:
- returned
- hasMore
properties:
returned:
type: integer
example: 1
hasMore:
type: boolean
example: true
ContactItem:
type: object
additionalProperties: false
required:
- firstName
- lastName
description: At least one of companyDomain or companyName is required.
properties:
firstName:
type: string
example: Miri
lastName:
type: string
example: Tamir
companyDomain:
type: string
example: lusha.com
companyName:
type: string
example: Lusha
ContactLookalikesResponse:
type: object
additionalProperties: false
required:
- dedupeSessionId
- results
- meta
properties:
dedupeSessionId:
type:
- string
- 'null'
format: uuid
example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
results:
type: array
items:
$ref: '#/components/schemas/V3LookAlikeContactResult'
meta:
$ref: '#/components/schemas/ContactLookalikesMeta'
tableWrite:
$ref: '#/components/schemas/TableWrite'
billing:
$ref: '#/components/schemas/V3Billing'
V3LookAlikeContactResult:
type: object
properties:
id:
type: string
example: '4389064624'
firstName:
type: string
example: Yehuda
lastName:
type: string
example: Rapp
socialLinks:
type: object
properties:
linkedin:
type: string
example: https://www.linkedin.com/in/yehuda-rapp-53909b99
company:
type: object
properties:
id:
type: string
example: '16303253'
name:
type: string
example: Lusha
domain:
type: string
example: www.lusha.com
jobTitle:
type: object
properties:
title:
type: string
example: Senior Solutions Engineer
departments:
type: array
items:
type: string
example:
- Engineering & Technical
seniority:
type: string
example: Senior
location:
type: object
properties:
country:
type: string
example: Israel
state:
type: string
example: Tel Aviv District
city:
type: string
example: Tel Aviv
ContactLookalikesMeta:
type: object
additionalProperties: false
required:
- returned
- hasMore
properties:
returned:
type: integer
example: 25
hasMore:
type: boolean
example: true
CompanyLookalikesResponse:
type: object
required:
- dedupeSessionId
- results
- meta
properties:
dedupeSessionId:
type: string
format: uuid
example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
results:
type: array
items:
$ref: '#/components/schemas/V3LookAlikeCompanyResult'
meta:
$ref: '#/components/schemas/CompanyLookalikesMeta'
tableWrite:
$ref: '#/components/schemas/TableWrite'
billing:
$ref: '#/components/schemas/V3Billing'
V3LookAlikeCompanyResult:
type: object
properties:
id:
type: string
example: '16303253'
name:
type: string
example: Marriott International
domain:
type: string
example: marriott.com
employeeCount:
type: object
properties:
exact:
type: integer
example: 255334
industry:
type: string
example: Hospitality
location:
type: object
properties:
country:
type: string
example: United States
state:
type: string
example: Maryland
city:
type: string
example: Bethesda
socialLinks:
type: object
properties:
linkedin:
type: string
example: https://www.linkedin.com/company/marriott-international
V3Billing:
type: object
description: Credit usage summary for a V3 API request
properties:
creditsCharged:
type: integer
description: Total credits charged for this request
example: 3
resultsReturned:
type: integer
description: Number of successful results returned
example: 1
ContactIdentifiersBatch:
type:
- object
- 'null'
additionalProperties: false
properties:
linkedinUrls:
type: array
items:
type: string
maxItems: 100
example:
- https://www.linkedin.com/in/orit-shilvock-6243bb5
contacts:
type: array
items:
$ref: '#/components/schemas/ContactItem'
maxItems: 100
emails:
type: array
items:
type: string
format: email
maxItems: 100
example:
- gal.ashkelon@lusha.com
ids:
type: array
items:
type: string
maxItems: 100
description: Lusha contact IDs as strings (preferred)
example:
- '1234'
- '4567'
contactIds:
type: array
items:
type: integer
maxItems: 100
description: Lusha contact IDs as numbers (legacy; prefer ids)
example:
- 1234
- 4567
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'
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.
TableWrite:
type: object
description: 'Added to a Prospecting, Enrich, Signals, or Lookalike response when `tableId` is passed on the request. The primary response is unaffected even if the table write fails.
'
properties:
tableId:
type: string
example: '482910'
added:
type: integer
description: Number of new entities added to the table by this call.
example: 3
alreadyPresent:
type: integer
description: Number of entities from this call that were already in the table.
example: 2
columnsCreated:
type: integer
description: Number of columns auto-created by this call (e.g. a Signals column created on first use).
example: 0
rowsProcessed:
type: integer
description: Number of rows the column-run touched as part of this call.
example: 5
rowsCharged:
type: integer
description: Number of those rows that incurred a credit charge.
example: 5
rowsAlreadyPaidInTable:
type: integer
description: Number of those rows that were already paid for in this table and were not re-charged.
example: 0
creditsCharged:
type: integer
description: Credits charged specifically for this table write.
example: 0
ContactLookalikesRequest:
type: object
additionalProperties: false
required:
- seeds
properties:
dedupeSessionId:
type: string
format: uuid
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
example: 25
tableId:
type: string
description: Optional. If provided, results are also persisted to this table. See the Tables API.
example: '482910'
CompanyLookalikesRequest:
type: object
required:
- seeds
properties:
dedupeSessionId:
type: string
format: uuid
example: 58adaa77-7a6e-4c9b-8c2d-820a6538e613
seeds:
$ref: '#/components/schemas/CompanyIdentifiersBatch'
exclude:
$ref: '#/components/schemas/CompanyIdentifiersBatch'
limit:
type: integer
minimum: 1
maximum: 100
default: 25
example: 25
tableId:
type: string
description: Optional. If provided, results are also persisted to this table. See the Tables API.
example: '583021'
CompanyIdentifiersBatch:
type: object
properties:
domains:
type: array
items:
type: string
maxItems: 100
example:
- sap.com
- oracle.com
linkedinUrls:
type: array
items:
type: string
maxItems: 100
example:
- https://www.linkedin.com/company/sap
minProperties: 1
ContactItem_2:
type: object
additionalProperties: false
required:
- firstName
- lastName
properties:
firstName:
type: string
example: John
lastName:
type: string
example: Doe
companyDomain:
type: string
example: acme.com
companyName:
type: string
example: Acme Inc
LookalikeCompanyResult:
type: object
required:
- domain
- linkedinUrl
- name
- employeeCount
- industry
- location
properties:
domain:
type:
- string
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lusha/refs/heads/main/openapi/lusha-lookalikes-api-openapi.yml