> 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/job-function-breakdown/list-lookup.md).

# List Lookup

Break every company in a Parvenu list down by LinkedIn job function. Asynchronous, writes results back into the list.

<mark style="color:green;">`POST`</mark> `/job_function_breakdown_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`. Costs **0.5 credits per company** with a company LinkedIn URL, and **0.7 credits per company** when its LinkedIn page is found from the website. Charged once per company, not per contact. Nothing is charged when no LinkedIn page or no breakdown is found, and a company looked up recently is free.
{% endhint %}

Use this to break down every company in a list in one call, rather than looping over Individual Lookup per row.

Each row needs a **company LinkedIn URL or a company website**. When a row has a company LinkedIn URL, that is used and the website is never looked up. When it only has a website, Parvenu finds the company's LinkedIn page from the website first, then runs the breakdown, and saves the LinkedIn URL it found into the row's `company_linkedin_url` column if that column was empty. A row with neither is skipped and costs nothing.

The run resolves each distinct company once, however many contacts from that company are in the list, and writes the same counts to every one of their rows. Twenty contacts at one company cost 0.5 credits (or 0.7 when found from the website), not 10.

{% hint style="warning" %}
**The counts cover people who have a LinkedIn profile, not everyone who works at the company, and they do not sum to the company's headcount.** In one verified lookup a company returned 90 people across its functions against a LinkedIn employee count of 83, for a company that states it employs more than 280. The percentage in `job_function_breakdown` is that function's share of the people counted. Never present it as a percentage of company size.
{% 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. |
| `filter_stack` | array   | Optional. The column filters to apply before the run, in the same shape the leads table uses. Rows the filters exclude are left untouched.                                  |
| `search`       | string  | Optional. Free-text search applied before the run, narrowing the rows the same way the table's search box does.                                                             |
| `sort_by`      | string  | Optional. Column to sort the selected rows by.                                                                                                                              |
| `sort_dir`     | string  | Optional. Sort direction, `asc` or `desc`.                                                                                                                                  |
| `max_rows`     | integer | Optional. Caps how many rows the run processes. When the selection is larger than the cap the acknowledgement reports `truncated: true`.                                    |
| `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).

**What it writes**

| Column                      | Description                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `company_linkedin_url`      | Only when the row had no company LinkedIn URL and one was found from its website. An existing company LinkedIn URL is never changed.                                                                                                                                                                                                                               |
| `job_function_breakdown`    | Readable summary, one function per line, largest first, e.g. `Sales - 3345 people - 20%`. The percentage is that function's share of the people counted, not of the company.                                                                                                                                                                                       |
| `job_function_top`          | The largest function.                                                                                                                                                                                                                                                                                                                                              |
| `headcount`                 | The number of staff with a LinkedIn profile. This writes into the existing `headcount` column; there is no separate LinkedIn employee column. When two sources disagree, the more trusted one is kept: a headcount from [Company Profile](/enrichments/company-profile.md) is not replaced, and when LinkedIn shows no number the existing value is left as it is. |
| `function_count_<function>` | 28 integer columns: LinkedIn's 27 job functions slugified, plus `function_count_other`. A function with nobody counted in it is left empty rather than set to `0`.                                                                                                                                                                                                 |

**Response**

The acknowledgement reports the job's `status`, which is one of `queued`, `processing`, `done`, `not_found`, `cancelled` or `error`. `done` means the job has finished. It also reports `fetched_count` (rows read from the list), `server_filtered_total` (rows left after the view, filters and search), `max_rows`, `truncated`, `filter_stack_active` and `search_active`. See [Response Format](/getting-started/response-format.md) for the fields every endpoint returns.

`credits_used` on the acknowledgement is always `0`. The run itself is charged as the companies resolve.

**Example**

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

```json
{
  "api_key": "your_api_key",
  "listname": "my_list",
  "view": "all"
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "ok": true,
  "status": "queued",
  "job_id": "your_job_id",
  "view": "all",
  "message": "queued",
  "credits_used": 0,
  "success": true
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "list not found"
  },
  "success": false
}
```

{% endtab %}
{% endtabs %}

The acknowledgement also carries the row counts described above; they are omitted from the example, and `job_id` is shown as a placeholder.

**Retrieving results**

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