Save company-search results into a list

Run the search server-side and save up to limit matches into a company list. Same filter-source contract as POST /companies/search — exactly one of filters, savedSearchId, savedSearchName or query. 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.

filters.headquartersCity names are geocoded one by one and OR-ed together; a name that geocodes to nothing is dropped and the job runs on the rest — only when not one resolves is it refused with 422 CITY_FILTER_UNRESOLVED, and there is no upfront credit pre-check, so take the values from GET /companies/autocomplete?field=location. Fiber firmographics land on the saved companies automatically — there is no enrich switch. Always async: 202 means the save started, not that the list is populated; poll the list's rows. Billing: the job saves in pages of 100 and debits 2 credits per company as it goes, so there is no upfront pre-check and a partially completed run is partially billed.

Errors:

• 404 SAVED_SEARCH_NOT_FOUND — No saved search of yours has that id or exact title.
• 409 SAVED_SEARCH_NAME_AMBIGUOUS — Two of your saved searches share that title — reference it by savedSearchId instead.
• 409 LIST_NAME_AMBIGUOUS — Two of your company lists share that name — pass listId instead.
• 409 LIST_NAME_TAKEN — A company list with that name was created concurrently; retry with listId.
• 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 company search — the blob is empty, or every value in it was retired. A filterless stored search is refused here rather than saved from a whole-universe search.
• 422 QUERY_FILTERS_INVALID — The natural-language query produced no usable filter; name concrete criteria.
• 422 CITY_FILTER_UNRESOLVED — NOT ONE of the filters.headquartersCity names geocoded to a city area, so the save was refused before it started; names that do geocode are OR-ed together and a name that does not is dropped, so this fires only when every name fails. param is filters.headquartersCity.
• 422 LIST_NAME_RESERVED — listName is a system/dynamic list title and cannot be a destination.
• 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: companies.