List Lookup

Find recent news for every company in a Parvenu list. Asynchronous, writes results back into the list.

POST /company_news_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 1 credit per company that returns news, the same rate a single Individual Lookup costs. Each company is charged once, however many of its contacts are on the list. Companies that find nothing are free. Results are written to the company_news column.

Use this to find news for every company on a list in one call, rather than looping over Individual Lookup per row.

Charged once per company. Contacts at the same company (the same website domain) share one answer. The company is looked up and charged once, and the other contacts at that company get the same news for 0 credits, with (same company) in their log.

There is no prompt field. Company News asks a fixed question, so every list is asked the same thing and the answers stay comparable across runs. Sending a prompt returns a 422. To run a question of your own wording across a list, use Research with AI instead.

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.
processing_mode	string	Optional. blank_only (default), all, or first_10. See Processing modes below.
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.
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.

Processing modes

Value	Behaviour
blank_only	Default. Only fills rows whose company_news column is still empty. Cheapest re-run.
all	Re-processes every row and replaces what is there. A row that finds nothing on the re-run has its cell cleared.
first_10	Processes only the first 10 fetched rows. Use this as a cheap dry run.

View values

Value	Processes
all	Every row in the list (default).
verified	Only rows whose email address is verified.

Example

Input

{
  "api_key": "your_api_key",
  "listname": "my_list",
  "processing_mode": "first_10"
}

Output

{
  "success": true,
  "job_id": "a1b2c3d4e5f6",
  "status": "queued",
  "list_name": "my_list",
  "rows_selected": 10,
  "rows_fetched": 10,
  "message": "News lookup started in background.",
  "view": "all",
  "max_rows": 5000,
  "credits_estimated": 10,
  "truncated": false,
  "credits_used": 0
}

Error

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "prompt: Extra inputs are not permitted"
  },
  "success": false
}

credits_estimated is rows_fetched × 1, the most the run can cost. The final spend is usually lower: contacts at the same company share one charge, and two cases are free (a company with no recent news, and a row with no company website to search on). credits_used on the acknowledgement is 0 because nothing has run yet. job_id identifies this run and also appears in each processed row's log entry.

Try a new list with "processing_mode": "first_10" first. At all a re-run replaces results you already have.

Retrieving results

• Check List Status

• Download List Data