Save people-search results into a list

Run the search server-side and save up to limit matches into a contact list. The filter source is exactly one of filters, a saved search (savedSearchId / savedSearchName), or a natural-language query — the same contract as POST /prospects/search. The destination is exactly one of listId or listName; listName is create-or-reuse by exact name (case-insensitive), a name shared by two lists is a 409, and system list names are refused.

enrich selects what runs on the saved rows. none (default) saves the search rows as-is at 1 credit per row saved. email, phone or phone_and_email save first, then enrich, as the app’s Save + enrich does: the same save (1 credit per row saved), then one enrichment job on exactly the contacts that save added, charged only for the values it finds (50 / 200 / 250 credits per contact for the work email / phone / both; 100 / 300 for email and both when personal emails come first). Contacts already carrying the requested data cost their save and nothing for enrichment. Before anything starts the balance must cover limit x (1 + the mode’s highest enrichment price), so 51 / 201 / 251 credits per row (101 / 301 with personal emails first); short of that the request is a 402 and nothing is saved or billed.

Following an enrichment mode: the 202 carries totalContacts, estimatedMinutes, jobId and status pending. The enrichment job only exists once the save is done, so jobId is the save run’s id; poll GET /business/jobs/{jobId}. It reads pending with every count at 0 while the contacts are saved, then as the enrichment job: pending while it waits behind your other enrichment job, processing, then completed, cancelled or failed, with its counts; stopped means the balance ran out mid-run (pausedReason INSUFFICIENT_CREDITS) and it resumes from the app. When the save added nobody, or could not be paid in full (the balance fell after the check), no enrichment starts: the job ends completed with every count at 0, the rows saved stay on the list, and the app’s notification says why (enrich them later with POST /business/lists//enrich). When the save itself fails, the job ends failed. An identical request while the first is still saving or enriching gets the first answer and saves nothing again.

An optional campaignId XOR campaignName attaches the destination list to that campaign in the same motion, and the response’s campaign.attached says whether that succeeded — a failed attach never retracts a started save. The attach happens when the save STARTS: a draft campaign enrols the full list at approval, while an ACTIVE non-dynamic campaign enrols only the rows present at attach time.

Always async: 202 means the save started, not that the list is populated — poll the list’s rows (and, with an enrichment mode, the job). Billing: this runs its own search, it does NOT reuse a prior POST /prospects/search, so previewing first and then saving pays for the search twice. Saving a hand-picked subset of results is not supported; narrow the filters instead.

Errors:

• 402 INSUFFICIENT_CREDITS — The balance does not cover the up-front check: limit x 1 credit with enrich: none, limit x (1 credit for the save + the mode’s highest enrichment price) otherwise. Nothing was saved or billed.
• 404 SAVED_SEARCH_NOT_FOUND — No saved search of yours has that id or exact title.
• 404 CAMPAIGN_NOT_FOUND — No campaign of yours matches campaignId / campaignName; nothing was saved.
• 404 LIST_NOT_FOUND — With enrich other than none: listId is not one of your lists, or it was deleted before the save started. Nothing was saved or billed.
• 409 SAVED_SEARCH_NAME_AMBIGUOUS — Two of your saved searches share that title — reference it by savedSearchId instead.
• 409 CAMPAIGN_NAME_AMBIGUOUS — Two of your campaigns share that name — pass campaignId instead.
• 409 LIST_NAME_AMBIGUOUS — Two of your lists share that name — pass listId instead.
• 409 LIST_NAME_TAKEN — With enrich other than none: the new list for listName could not be created because the name was taken in the meantime. Retry, or pass listId. Nothing was saved or billed.
• 422 VALIDATION_FAILED — The request failed the declared schema; param names the offending key and message quotes the rule it broke.
• 422 SAVED_SEARCH_TYPE_MISMATCH — The saved search exists but stores the other kind of filters; param is savedSearchId.
• 422 SAVED_SEARCH_INVALID — The STORED filters no longer form a runnable search — every value was retired, or the blob translates to nothing.
• 422 QUERY_FILTERS_INVALID — The natural-language query produced no usable filter; name concrete criteria.
• 422 LIST_NAME_RESERVED — listName is a system/dynamic list title and cannot be a destination.
• 422 CAMPAIGN_LIST_CAP_REACHED — The campaign already holds the maximum number of attached lists; nothing was saved.
• 429 RATE_LIMITED — Per-token rate limit for this bucket exhausted; retry after the window in the RateLimit-Reset header.
• 500 UNEXPECTED_ERROR — The request failed inside the service; nothing was billed and the request_id identifies the failure.

Requires one of the following token scopes: search.