> 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/enrichments/profile-with-company/list-lookup.md).

# List Lookup

Enrich both the person and their current company for every contact in a Parvenu list. Asynchronous, writes results back into the list.

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

{% hint style="info" %}
This is an **asynchronous** endpoint. It returns a job acknowledgement, not data. Poll `/check_list_status` until the list reports `done`, then fetch the rows with `/download_list`.
{% endhint %}

The whole-list counterpart of [Individual Lookup](/enrichments/profile-with-company/individual-lookup.md) (one URL) and [Batch Lookup](/enrichments/profile-with-company/batch-lookup.md) (up to ten).

The run happens in two phases: profile enrichment first, which fills each row's company LinkedIn URL, then company enrichment, which reads that column. While the run is in flight, `/check_list_status` reports the phase it is working on. The list reports as still running until **both** halves are finished, so a poll can never tempt you into downloading person data before the company data lands.

{% hint style="info" %}
Pricing is the sum of the two phases: **0.1 credit** per contact for the person (**0.3** with `full_profile: true`), plus **0.1 credit** per **unique** company.

Because the company half is billed once per employer however many rows share it, a list with colleagues costs less here than the same contacts run one at a time through `/profile_with_company`.
{% endhint %}

{% hint style="warning" %}
Rows without a LinkedIn URL are skipped. Run LinkedIn Profile URL Finder against the list first if that column is empty. A full-profile run costs three times a basic one on the person half, so check `/credit_check` before launching one against a large list.
{% endhint %}

**Headers**

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

**Body**

| Name           | Type    | Description                                                                                                                                                                 |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`      | string  | Your API Key.                                                                                                                                                               |
| `listname`     | string  | Name of the existing Parvenu list to enrich.                                                                                                                                |
| `view`         | string  | Optional. Which rows of the list to process. `all` (default) processes every contact in the list; `verified` restricts the run to contacts whose email address is verified. |
| `full_profile` | boolean | Optional. Default `false` (0.1 credit per contact on the person half). `true` runs the full profile lookup (0.3 credit per contact).                                        |
| `saved_view`   | string  | Optional. Name of a saved view on this list. Runs only on the contacts in that view. Don't combine with `view`, `filter_stack` or `search`.                                 |

**Saved views.** To run only on the contacts in a saved view, send its name as `saved_view`. See [List Saved Views](/manage-lists/list-saved-views.md).

{% hint style="info" %}
The list name field on this endpoint is `listname`, matching `/check_list_status` and `/download_list`. The body accepts no other fields.
{% endhint %}

**Response**

Every list-scoped trigger answers with the same job acknowledgement.

| Field               | Type    | Description                                                                                        |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `status`            | string  | `queued` when the run is accepted. Poll `/check_list_status`; the finished status there is `done`. |
| `job_id`            | string  | Identifier for this run. Always a string.                                                          |
| `list_name`         | string  | The list being enriched.                                                                           |
| `view`              | string  | Which rows were selected, `all` or `verified`.                                                     |
| `rows_selected`     | number  | How many rows matched your `view` before the page limit was applied.                               |
| `rows_fetched`      | number  | How many rows this run actually picked up. This is the number that gets processed.                 |
| `truncated`         | boolean | `true` when the list held more rows than `max_rows`.                                               |
| `max_rows`          | number  | The ceiling a single run will fetch.                                                               |
| `credits_estimated` | number  | What the run is expected to cost, based on the rows it picked up.                                  |

See [Response Format](/getting-started/response-format.md) for the fields every endpoint returns.

**Example**

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

```json
{
  "api_key": "your_api_key",
  "listname": "Roofing Owners in California",
  "view": "all",
  "full_profile": false
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "queued",
  "job_id": "17",
  "list_name": "Roofing Owners in California",
  "view": "all",
  "rows_selected": 50,
  "rows_fetched": 50,
  "truncated": false,
  "max_rows": 5000,
  "credits_estimated": 5.0,
  "credits_used": 0,
  "credits_remaining": 4823,
  "message": "Profile + company enrichment queued. Poll /check_list_status, then /download_list once it reports done.",
  "success": true
}
```

{% endtab %}

{% tab title="Status while running" %}

```json
{
  "status": "success",
  "data": [
    {
      "list_name": "Roofing Owners in California",
      "status": "processing",
      "phase": "profile"
    }
  ],
  "total": 1,
  "credits_used": 0,
  "credits_remaining": 4823,
  "success": true
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "listname: Field required"
  },
  "success": false
}
```

{% endtab %}
{% endtabs %}

**Retrieving results**

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