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 2 credits per row; email, phone or phone_and_email run the enrichment waterfall while saving (50 / 200 / 250 credits per row pre-checked), and rows already carrying the requested data are not re-charged. Only the enrichment modes report totalContacts, estimatedMinutes, and the run's 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 run whose balance runs out mid-run pauses (stopped) and is resumed from the app.

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 job started, not that the list is populated — poll the list's rows. 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 pre-check for this request; nothing was 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.
• 409 ALL_CONTACTS_ALREADY_ENRICHED — Every matching row already carries the requested enrichment — nothing to run and nothing 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.