Enrich a list's contacts in place

Runs an enrichment over the list’s contacts in place. mode selects what runs: the waterfall modes (email, phone, phone_and_email) discover new values through the provider waterfall and take an optional row filters object or an explicit contactIds selection; validate_emails re-verifies the contacts’ existing emails; demographics resolves manually-added rows to canonical contacts. limit is how many rows are taken, from offset (default 0) in the list’s default order after filters — required unless contactIds is given, and capped at 5,000 for validate_emails/demographics. Rows that already hold the requested data, or were searched for it before, are skipped and not charged but still count toward limit, so a repeated call with the same offset and limit takes the same rows: pass a larger offset to reach rows further down. A call identical to one whose job is still queued or running (same mode, filters, offset and limit) returns that job instead of starting another. Billing is per processed contact: up to 50 credits per work email (100 when personal emails are prioritised in the workspace settings), 200 per phone, 10 per re-verified address, 1 per resolved demographics row; the balance must cover the reserved price up front (402 INSUFFICIENT_CREDITS) and contacts already carrying the requested data are never re-charged — with the waterfall modes a fully enriched list answers 409 ALL_CONTACTS_ALREADY_ENRICHED before anything bills, while validate_emails and demographics report a nothing-to-do run as 202 with totalContacts: 0. Async: totalContacts is the number of rows this run takes (at most limit, fewer at the list’s end; a call that returns a running job, or explicit contactIds that join a queued one, answers that job’s total) and estimatedMinutes a rough duration; poll GET /business/lists/{listId}/rows (emails/phones fill in) or the list’s metrics. The waterfall modes run as a job: the 202 also carries its jobId and status (pending while it waits behind your other enrichment job, processing once it runs); poll GET /business/jobs/{jobId} for its status and counts. A job whose balance runs out mid-run pauses (stopped, with pausedReason INSUFFICIENT_CREDITS) and is resumed from the app. To work through a list in batches, pass offset as the previous call’s offset plus limit: a call without offset always starts at the list’s first row.

Errors:

• 402 INSUFFICIENT_CREDITS — The credit balance does not cover the reserved price for the requested rows.
• 404 LIST_NOT_FOUND — No list with that id is visible to the token owner.
• 409 ALL_CONTACTS_ALREADY_ENRICHED — Every contact in the list already carries the requested data; nothing to run. Waterfall modes (email, phone, phone_and_email) only — validate_emails and demographics answer 202 with totalContacts 0 instead.
• 422 CONTACT_LIST_REQUIRED — The list is a company list; enrichment runs on contacts.
• 422 CONTACT_NOT_IN_LIST — A contactIds entry is not a row of this list.
• 422 VALIDATION_FAILED — mode missing/unknown, limit missing without contactIds or outside 1-10000, filters/contactIds sent together or with validate_emails/demographics, offset sent with contactIds or with validate_emails/demographics.
• 429 RATE_LIMITED — The lists rate bucket (120 requests/minute, 10,000/day per token owner) is exhausted.

Requires one of the following token scopes: lists.