Run Enrichment

Start an enrichment job that scores contacts (inline or a Parvenu list) against an ICP.

POST /run_enrichment

Billed 0.1 credit per contact scored, including a contact outside the ICP's location. A contact with no title and no company is skipped and not charged. On a list, contacts already scored with this ICP are skipped for free by default (who_to_score: "not_scored"). Returns a queued job immediately. Poll it with Get Enrichment for results.

Score contacts against an ICP. Provide either an inline contacts array or a Parvenu listname. To check contacts against several ICPs at once, use Multi-ICP Score.

Which contacts on a list are scored. The same ones the leads table shows: the view in state (every contact by default), narrowed by search and filter_stack when you send them. Contacts outside that selection are not scored or charged. Or send saved_view to use a saved view's contacts instead.

How a match is decided. Your ICP has must-haves, for example the type of company and the job title, and nice-to-haves. A contact that clearly misses a must-have, or has too little information to check one, is not a match, whatever its score. Job titles need a clear fit: a vague title such as "Manager" passes only when the company clearly fits. An unknown company size neither helps nor hurts the score.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
api_key	string	Your API Key.
icp_id	integer	An ICP id you own.
listname	string	Optional. A Parvenu list to score instead of inline contacts.
list_owner_user_id	string	Optional. Memberstack mem_ id that owns the list. Needed with listname only when the list belongs to a different account from your key.
contacts	array	Optional. Inline contacts to score.
state	string	Optional. Which list view to score: all (default, every contact), filtered, verified, valid, accept_all, job_poster or job_posts.
search	string	Optional. Only contacts matching this search, like the leads table's search box.
filter_stack	object	Optional. Only contacts matching these filters, e.g. {"operator":"and","filters":[{"columnId":"current_title","operator":"includes","value":"Owner"}]}.
semantic_limit	integer	Optional. Cap on contacts scored.
threshold	number (0–1)	Optional. One-off match cutoff for this run; defaults to the ICP's threshold.
who_to_score	string	Optional, list runs only. not_scored (default): contacts that already have a result for this ICP, written since it was last edited, keep it and are not charged again. everybody: score every selected contact again.
only_contacts	array	Optional, list runs only. LinkedIn URLs and/or emails. Only these contacts of the list are scored.
saved_view	string	Optional. Name of a saved view on listname. Scores only the contacts in that view. Needs listname. Don't combine with state, 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.

Response

Field inside data	Type	Description
job_id	string	The job handle. Pass it to Get Enrichment. Also at the top level.
status	string	queued, processing, done, not_found, cancelled, or error.
view	string	Which list view is being scored, for example all or verified.
icp_id	number	The ICP being scored against.
icp_name	string	That ICP's name.
list_name	string	The list being scored, or a note when contacts were sent inline.
threshold	number	Match cutoff used for this run.
created_at	string	When the job was created.

The job is under data, and credits_per_row is the cost per contact scored. See Response Format for the fields every endpoint returns.

Example

Input

{
  "api_key": "your_api_key",
  "icp_id": 26,
  "contacts": [
    { "title": "VP of Sales", "organization": "Acme", "industry": "Computer Software" },
    { "title": "SDR", "organization": "Beta" }
  ],
  "threshold": 0.75
}

Output

{
  "status": "queued",
  "data": {
    "icp_id": 26,
    "icp_name": "Sales Director Small Company",
    "list_name": "(inline: 2 contacts)",
    "status": "queued",
    "threshold": 0.75,
    "created_at": "2026-07-22T23:35:21Z",
    "job_id": "011709e1-8310-429c-8e7a-34533670ec25",
    "view": "all"
  },
  "credits_used": 0.2,
  "credits_remaining": 4004.8,
  "credits_per_row": 0.1,
  "job_id": "011709e1-8310-429c-8e7a-34533670ec25",
  "success": true
}

List input

{
  "api_key": "your_api_key",
  "icp_id": 26,
  "listname": "Texas Builders",
  "state": "all",
  "search": "austin",
  "filter_stack": {
    "operator": "and",
    "filters": [{ "columnId": "current_title", "operator": "includes", "value": "Owner" }]
  }
}