---
title: "Contact Lookalikes"
method: POST
path: "/v3/contacts/lookalike"
tags: ["Lookalikes"]
---

# Contact Lookalikes

`POST /v3/contacts/lookalike`

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).

## Request body

- ContactLookalikesRequest
  - `dedupeSessionId` string, uuid
  - `seeds` ContactIdentifiersBatch, nullable, required
    - `linkedinUrls` string[]
    - `contacts` ContactItem[]
      - `firstName` string, required
      - `lastName` string, required
      - `companyDomain` string
      - `companyName` string
    - `emails` string[]
    - `ids` string[] — Lusha contact IDs as strings (preferred)
    - `contactIds` integer[] — Lusha contact IDs as numbers (legacy; prefer ids)
  - `exclude` ContactIdentifiersBatch, nullable
    - `linkedinUrls` string[]
    - `contacts` ContactItem[]
      - `firstName` string, required
      - `lastName` string, required
      - `companyDomain` string
      - `companyName` string
    - `emails` string[]
    - `ids` string[] — Lusha contact IDs as strings (preferred)
    - `contactIds` integer[] — Lusha contact IDs as numbers (legacy; prefer ids)
  - `limit` integer
  - `tableId` string — Optional. If provided, results are also persisted to this table. See the Tables API.

## Response `200`

Successfully retrieved contact lookalikes

- ContactLookalikesResponse
  - `dedupeSessionId` string, uuid, nullable, required
  - `results` V3LookAlikeContactResult[], required
    - `id` string
    - `firstName` string
    - `lastName` string
    - `socialLinks` object
      - `linkedin` string
    - `company` object
      - `id` string
      - `name` string
      - `domain` string
    - `jobTitle` object
      - `title` string
      - `departments` string[]
      - `seniority` string
    - `location` object
      - `country` string
      - `state` string
      - `city` string
  - `meta` ContactLookalikesMeta, required
    - `returned` integer, required
    - `hasMore` boolean, required
  - `tableWrite` TableWrite — 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.
    - `tableId` string
    - `added` integer — Number of new entities added to the table by this call.
    - `alreadyPresent` integer — Number of entities from this call that were already in the table.
    - `columnsCreated` integer — Number of columns auto-created by this call (e.g. a Signals column created on first use).
    - `rowsProcessed` integer — Number of rows the column-run touched as part of this call.
    - `rowsCharged` integer — Number of those rows that incurred a credit charge.
    - `rowsAlreadyPaidInTable` integer — Number of those rows that were already paid for in this table and were not re-charged.
    - `creditsCharged` integer — Credits charged specifically for this table write.
  - `billing` V3Billing — Credit usage summary for a V3 API request
    - `creditsCharged` integer — Total credits charged for this request
    - `resultsReturned` integer — Number of successful results returned

## Other responses

- `400` — Bad request - invalid input data
- `402` — Insufficient credits
- `403` — Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
- `410` — dedupeSessionId is invalid or expired
- `500` — Internal server error

---

[API](https://skmtc.net/lusha/apis/lusha-api-documentation.md) · [All operations](https://skmtc.net/lusha/apis/lusha-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lusha/lusha-api-documentation/revisions/4c51e40e3e67/schema)