List Lookup

Run a prompt template against every row of a Parvenu list. Asynchronous, writes results back into the list.

POST /personalize_with_ai_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 row processed, the same rate a single Individual Lookup costs. Generated copy is written to the ai_generated_text column.

Your prompt must reference at least one valid column using {{column_name}} syntax. A prompt with no column reference, or one that references a column that does not exist on the list, is rejected with a 400 before any rows are processed (and before any credits are consumed). See Prompt requirements below.

Use this to generate an icebreaker or personalized line for every contact in a list in one call, rather than looping over Individual Lookup per row.

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.
prompt	string	The prompt to run against each row. Must contain at least one {{column_name}} reference.
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.

Prompt requirements

The prompt is a template, not a standalone question. Reference list columns with double curly braces and the API substitutes each row's value before sending it to the model:

Write a one-sentence cold email icebreaker for {{person_name}}, {{current_title}} at {{organization_name}}, a company in the {{current_industry}} space.

Which columns can I reference? Any column on the list: the exact set is the keys returned by Download List Data for that list. Common ones include first_name, last_name, person_name, current_title, organization_name, current_industry, city, state, country, keywords, and headcount, plus the output columns of other enrichments such as research_with_ai, scrapewebsite_with_ai, work_experience, and company_tech_stack.

Richer context from other enrichments. The model only sees what's in the row, so run other enrichments first and reference their output columns. For example, run Research with AI to gather recent funding or product news into research_with_ai, then prompt: Write an icebreaker for {{person_name}} referencing this research: {{research_with_ai}}.

Two validation failures, both rejected with a 400 and no credits consumed:

• No column reference at all: No column references found in prompt. Use {{column_name}} format.

• A column that does not exist on the list: Invalid column names found, with the offending names in invalid_columns.

Processing modes

Value	Behaviour
blank_only	Default. Only fills rows whose target column is still empty. Cheapest re-run.
all	Re-processes and overwrites every row.
first_10	Processes only the first 10 fetched rows. Use this to test a prompt cheaply.

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",
  "prompt": "Write a one-sentence cold email icebreaker for {{person_name}}, {{current_title}} at {{organization_name}}, a company in the {{current_industry}} space.",
  "processing_mode": "first_10",
  "view": "verified"
}

Output

{
  "status": "queued",
  "job_id": "210",
  "list_name": "my_list",
  "view": "verified",
  "rows_selected": 5,
  "rows_fetched": 5,
  "truncated": false,
  "max_rows": 5000,
  "credits_estimated": 2.5,
  "credits_used": 0,
  "credits_remaining": 4823,
  "message": "Prompt saved/updated successfully with ID: 210. Loaded 5 row(s). Data processing started in background. Only first 10 fetched records will be processed, existing results will be replaced.",
  "success": true
}

Error

{
  "status": "error",
  "error": {
    "code": "http_error",
    "message": "Failed to start AI personalization due to external API error",
    "detail": "External API error: 400 - {\"detail\":{\"success\":false,\"message\":\"Invalid column names found\",\"invalid_columns\":[\"favorite_color\"]}}"
  },
  "success": false
}

Reading the acknowledgement

Every list-scoped trigger answers with the same envelope, so one piece of client code handles them all.

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

See Response Format for the fields every endpoint returns.

Test new prompts with "processing_mode": "first_10" before running them across a full list. The prompt is saved and reused under the same job_id, so a bad prompt run at all will overwrite good results.

Retrieving results

• Check List Status

• Download List Data