List Lookup

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

POST /job_function_breakdown_list

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.

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.

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.

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.

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 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 for the fields every endpoint returns.

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

Example

Input

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

Output

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

Error

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

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

• Download List Data