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

# Find similar contacts with POST /v3/lookalike/contacts

> Discover new contacts who match your best prospects by submitting seed contact identifiers, LinkedIn URLs, or emails to the Lusha contact lookalikes endpoint.

The contact lookalikes endpoint takes a set of seed contacts and returns new contacts who share similar roles, seniority levels, and industry patterns. Use it to expand your total addressable market or fill your pipeline with prospects who look like your highest-converting leads.

**Endpoint:** `POST https://api.lusha.com/v3/lookalike/contacts`

## Request body

| Field             | Type    | Required | Description                                                                                                                                                                            |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seeds`           | object  | Yes      | Seed contacts, identified via `linkedinUrls`, `emails`, `contactIds`, and/or `contacts` (name + company). Provide at least one; 5–100 unique identifiers total across all four arrays. |
| `dedupeSessionId` | string  | No       | Session token returned from a previous call. Omit on the first request.                                                                                                                |
| `exclude`         | object  | No       | Contacts to exclude from results, in the same shape as `seeds` (up to 500 identifiers total). Applied on every request, combined with session-level deduplication.                     |
| `limit`           | integer | No       | Results per call. Range `1`–`100`, default `25`.                                                                                                                                       |

Each entry in `seeds.contacts` needs `firstName`, `lastName`, and at least one of `companyDomain` or `companyName`.

## Paginating without duplicates

The endpoint uses a `dedupeSessionId` to track which contacts have already been returned. Follow this pattern to retrieve more results across multiple calls.

<Steps>
  <Step title="First call - no dedupeSessionId">
    Send your seed contacts without a `dedupeSessionId`. The server creates a new session and returns the first batch of lookalikes along with a `dedupeSessionId` you will use in the next call.

    ```json theme={null}
    {
      "seeds": {
        "contactIds": [4183886134]
      }
    }
    ```
  </Step>

  <Step title="Subsequent calls - pass the session ID">
    Include the `dedupeSessionId` returned in the previous response. The server skips contacts it has already returned for this session.

    ```json theme={null}
    {
      "seeds": {
        "contactIds": [4183886134]
      },
      "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613"
    }
    ```
  </Step>
</Steps>

<Note>
  Sessions are retained for **30 days** from the last activity (sliding window). After 30 days of inactivity the session expires and the next call starts a new one.
</Note>

## Example: first request

```bash theme={null}
curl --request POST \
  --url https://api.lusha.com/v3/lookalike/contacts \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "seeds": {
      "linkedinUrls": ["https://www.linkedin.com/in/johndoe"],
      "emails": ["jane@acme.com"],
      "contacts": [
        { "firstName": "Alice", "lastName": "Smith", "companyDomain": "sap.com" }
      ]
    }
  }'
```

## Example: get more results

```bash theme={null}
curl --request POST \
  --url https://api.lusha.com/v3/lookalike/contacts \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "seeds": {
      "linkedinUrls": ["https://www.linkedin.com/in/johndoe"]
    },
    "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613"
  }'
```

## Example response

```json theme={null}
{
  "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
}
```

The response always includes `dedupeSessionId` and `meta.hasMore` - carry `dedupeSessionId` forward and check `hasMore` to decide whether to keep paging.

Results are lightweight previews (name, current company, job title, location). Pipe `contactId` values into an enrichment call to retrieve emails and phone numbers.

## Excluding specific contacts

Pass an `exclude` object - shaped like `seeds` - to filter out contacts you already own or do not want to see, regardless of session state. The server applies your exclusions on top of session-level deduplication on every call.

```json theme={null}
{
  "seeds": {
    "contactIds": [4183886134]
  },
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "exclude": {
    "contactIds": [1111111111, 2222222222]
  }
}
```

## Use cases

* **Expand total addressable market** - start from your top-performing contacts and discover similarly qualified prospects you have not yet reached.
* **Fill pipeline gaps** - when a segment goes cold, use lookalikes to quickly identify new prospects with a comparable profile.

<Tip>
  Seed the endpoint with your closed-won contacts for the best match quality. The more specific and consistent the seed set, the more relevant the lookalike results.
</Tip>