> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/search/lookalike-audience-list.md).

# Lookalike Audience List

Find companies similar to a set of seed companies and save them into a Parvenu list.

<mark style="color:green;">`POST`</mark> `/lookalike_list`

{% hint style="info" %}
Lookalike Audience costs **0.2 credits per similar company saved**. The seed companies are never charged and never saved.
{% endhint %}

Find companies similar to a set of seed companies and save them into a list as company rows. Each row gets a name, domain, website, LinkedIn URL, industry, size, headcount, location and description. Give the seeds as an existing Parvenu list, or as a list of domains.

Credits are reserved when the job is submitted and the unused part is refunded when it finishes. Asking for 100 companies holds 20 credits. If only 80 are saved, 4 credits come back. If nothing is found, all of it comes back.

{% hint style="warning" %}
**Companies only.** This endpoint saves companies, not people. To add people at those companies, run [Lead Enrichment](/search/lead-enrichment.md) with `company_domain` set to the saved domains and the same `listname`.
{% endhint %}

{% hint style="info" %}
This is a bulk endpoint. The process has three steps: (1) start the job here, (2) check status with `/check_list_status`, (3) download results with `/download_list`.
{% endhint %}

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

| Name            | Type           | Description                                                                                                           |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `api_key`       | string         | Your API Key.                                                                                                         |
| `listname`      | string         | The list to save the similar companies into. Created if it does not exist.                                            |
| `seed_listname` | string         | An existing Parvenu list whose company websites are the seeds (up to 500). Send this **or** `seed_domains`, not both. |
| `seed_domains`  | array\[string] | 1 to 500 company domains. Send this **or** `seed_listname`, not both. Free-mail domains and duplicates are dropped.   |
| `max_results`   | integer        | Optional. Most similar companies to save, 1 to 1,000. Default 25. `max_results` × 0.2 credits are reserved up front.  |

**Response**

This endpoint starts a background job and answers with an acknowledgement, not the companies. See [Response Format](/getting-started/response-format.md) for the fields every endpoint returns.

| Field               | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `status`            | `queued` once the job is accepted.                                          |
| `job_id`            | The job handle.                                                             |
| `list_name`         | The list the companies are being saved into.                                |
| `rows_selected`     | How many companies the job will look for.                                   |
| `max_rows`          | How many you asked for.                                                     |
| `credits_estimated` | Credits reserved for the run. The unused part is refunded when it finishes. |
| `credits_per_row`   | Credits charged per company saved.                                          |
| `seed_count`        | How many seeds were used after clean-up.                                    |
| `message`           | A short note about the job.                                                 |

Poll `/check_list_status` until the list reports `done`, then download the rows. Each saved row gets one line in its `log` with the company's domain and the 0.2 credits it cost.

**Example**

{% tabs %}
{% tab title="Input" %}

```json
{
  "api_key": "your_api_key",
  "listname": "Payroll Lookalikes",
  "seed_domains": ["gusto.com", "rippling.com"],
  "max_results": 3
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "queued",
  "job_id": "ae7a310bf63b47019921e837ed944c23",
  "list_name": "Payroll Lookalikes",
  "view": "all",
  "rows_selected": 3,
  "max_rows": 3,
  "truncated": false,
  "credits_estimated": 0.6,
  "credits_used": 0.6,
  "credits_per_row": 0.2,
  "seed_count": 2,
  "message": "Lookalike Audience queued for up to 3 companies similar to 2 seeds. 0.6 credits reserved; unused credits are refunded when the run finishes.",
  "success": true
}
```

{% endtab %}

{% tab title="Error: no usable seeds" %}
Returned with HTTP 422 when the seeds hold no company domain, for example a seed list with no websites on it. Nothing is charged.

```json
{
  "status": "error",
  "error": {
    "code": "http_error",
    "message": "No company domains found in seed_domains (free-mail domains such as gmail.com are dropped). Nothing was charged."
  },
  "success": false
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
To check the seeds give the kind of companies you want, try [Lookalike Audience](/search/lookalike-audience.md) with `page_size: 5` first. That costs at most 1 credit.
{% endhint %}

**Retrieving results**

* [Check List Status](/get-enrichment-results/check-list-status.md)
* [Download List Data](/get-enrichment-results/download-list-data.md)