---
title: "Save company-search results into a list"
method: POST
path: "/business/companies/search/save-to-list"
tags: ["Company search"]
---

# Save company-search results into a list

`POST /business/companies/search/save-to-list`

## Request

- Base URL: `https://api.tryfuse.ai/api/v1`
- URL: `https://api.tryfuse.ai/api/v1/business/companies/search/save-to-list`
- Auth: HTTP basic

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.

## Request body

- object: Exactly one filter source (`filters` | `savedSearchId` | `savedSearchName` | `query`) and exactly one destination (`listId` | `listName`), plus `limit`.
  - `filters` object: Literal filters, one of the four filter sources — the same vocabulary as POST /companies/search. Company filters in the search vocabulary: include/exclude fields take `[{ status, value, label }]` entries (`label` is required), list fields arrays of strings, ranges `{ min, max }` and date ranges `{ start, end }` — enum vocabularies come from GET /companies/filter-options, names and places from GET /companies/autocomplete. Must contain at least one non-empty value.
    - `nameLike` string[]: Free text: company-name fragments of at most 500 chars each, matched fuzzily against the company NAME only (never the description). Several fragments are OR-joined (provider `nameLike.anyOf`); resolve a real company to its canonical name with GET /companies/autocomplete?field=company.
    - `domains` string[]: Free text: company website domains (e.g. stripe.com). A scheme, a www. prefix, a path and the letter case are all stripped before the search, so https://www.Stripe.com/pricing and stripe.com behave the same; a value that is not a domain at all is dropped. Several domains are OR-joined.
    - `keywords` string[]: Free-text keywords matched against company names and descriptions; any may match.
    - `status` object[]: Operating-status entries whose `value` is one of exactly: active, acquired, closed. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`). The provider ignores an exclude list on this field, so an exclusion is sent as the statuses that were NOT excluded, which also drops companies whose status is unknown. This filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `tags` object[]: Company-tag entries whose `value` is a slug from `companyTags` in GET /companies/filter-options: raised-from-top-vc, venture-backed-startup, is-government, is-school. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `industriesV2` object[]: Industry entries whose `value` is one of the `fiberIndustries` values in GET /companies/filter-options, copied exactly as listed (e.g. Software, Finance). An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `linkedinIndustries` object[]: LinkedIn-industry entries whose `value` is one of the `linkedinIndustries` values in GET /companies/filter-options, copied exactly as listed (e.g. Software Development) — a much finer taxonomy than `industriesV2`. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `crunchbaseCategories` object[]: Crunchbase-category entries whose `value` is one of the `crunchbaseIndustries` values in GET /companies/filter-options, copied exactly as listed (e.g. Financial Services). An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `crunchbaseCategoryGroups` string[]: Crunchbase category groups as plain strings copied verbatim (case-sensitive) from `crunchbaseCategoryGroups` in GET /companies/filter-options (e.g. Financial Services) — the broad parent of `crunchbaseCategories`. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Several groups are OR-joined (provider `anyOf`); this filter has no exclude form.
    - `naicsCodes` object[]: NAICS entries whose `value` is the code, not the title (`naicsCodes[].code` in GET /companies/filter-options, e.g. 513210 for Software Publishers; 2- to 6-digit codes are all accepted, a shorter code being the broader sector). An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `headquartersCountryCode` object[]: Headquarters-country entries whose `value` is the country's three-letter `apiCode` from `countries` in GET /companies/filter-options (e.g. USA, DEU). The two-letter `isoCodeAlpha2` in the same row (US, DE) is NOT accepted — the provider rejects it and the whole search fails. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `headquartersStateName` object[]: Headquarters state/province entries whose `value` is the full state or province name (e.g. Florida, California).
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `headquartersCity` string[]: Up to 25 fully qualified place names from GET /companies/autocomplete?field=location (e.g. Dallas, Texas, United States); each is geocoded independently to its city bounds and the areas are OR-ed together (no exclusion). A name that geocodes to nothing is dropped and the search runs on the names that did resolve — take the values from the typeahead so every one of them counts — and only when NOT ONE of them resolves is the search refused rather than run worldwide (422 CITY_FILTER_UNRESOLVED).
    - `employeeCountV2` object: Headcount range `{ min?, max? }`; any whole number is taken on either side and is used as sent — the values the search UI offers (1, 10, 50, 200, 500, 1000, 5000, 10000) are its own vocabulary, not a constraint here. The lower bound is EXCLUSIVE and the upper bound inclusive, so `{ min: 50 }` matches companies with MORE than 50 employees, and `{ min: 300, max: 320 }` matches 301 to 320. Inverted bounds are read the other way round, and an equal pair keeps only the lower bound, because the provider rejects a range whose bounds meet.
      - `min` number: Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field).
      - `max` number: Inclusive upper bound.
    - `revenueUSD` object: Estimated annual revenue range `{ min?, max? }`; the accepted values are whole US dollars, not millions (5000000 means $5M), and both bounds are inclusive.
      - `min` number: Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field).
      - `max` number: Inclusive upper bound.
    - `totalFundingUSD` object: Total funding raised range `{ min?, max? }`; the accepted values are whole US dollars, not millions (5000000 means $5M), and both bounds are inclusive.
      - `min` number: Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field).
      - `max` number: Inclusive upper bound.
    - `lastFundingUSD` object: Size range of the most recent funding round `{ min?, max? }`; the accepted values are whole US dollars, not millions (5000000 means $5M), and both bounds are inclusive.
      - `min` number: Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field).
      - `max` number: Inclusive upper bound.
    - `stage` object[]: Funding-stage entries whose `value` is one of exactly: pre_seed, seed, series_a, series_b, series_c, series_d, series_e, series_f, series_g, series_h, series_i, series_j, public, acquired, closed, private_equity, venture_other, no_funding_yet, unknown. No endpoint serves this list — it is fixed here. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `technologies` object[]: Technology-in-use entries whose `value` is a name from the provider's predefined technology vocabulary, forwarded verbatim, so it must carry the product's own spelling and casing — e.g. Salesforce, Kubernetes, Next.js, Google Analytics, and `AWS` for Amazon Web Services. No endpoint serves this vocabulary yet; the product's own picker offers a curated 141-name subset. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `investors` object[]: Investor entries whose `value` is the investor's website domain — resolve names with GET /companies/autocomplete?field=company&orgType=investor and send the `domain` from that response, never the investor's name. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `foundedOn` object: Founding-date range `{ start?, end? }` as ISO-8601 dates.
      - `start` string: Earliest date, ISO-8601 (e.g. 2020-01-01).
      - `end` string: Latest date, ISO-8601 (e.g. 2024-12-31).
    - `lastFundedOn` object: Date range of the most recent funding round, `{ start?, end? }` as ISO-8601 dates.
      - `start` string: Earliest date, ISO-8601 (e.g. 2020-01-01).
      - `end` string: Latest date, ISO-8601 (e.g. 2024-12-31).
    - `acceleratorsV2` object[]: Accelerator entries whose `value` is the `acceleratorSlug` from `accelerators` in GET /companies/filter-options (e.g. ycombinator, techstars); the `acceleratorName` in the same row is NOT accepted. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `fortuneRankings` object[]: Fortune-list entries whose `value` is one of exactly: fortune-500, fortune-1000 (fortune-1000 contains fortune-500). Any other value is silently DROPPED and the whole filter disappears, so the search then runs with no ranking constraint at all rather than returning nothing. Include values are OR-joined (provider `anyOf`). The provider takes an include list only here, and the tiers nest, so an exclude value cannot be honoured and is ignored. This filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `officeLocationsV2` object[]: Office-location entries whose `value` is a country's three-letter `apiCode` from `countries` in GET /companies/filter-options (e.g. USA) — the same vocabulary as `headquartersCountryCode`, but matching ANY office rather than only the headquarters. An off-list value is not rejected by this API: the search comes back empty (or fails upstream) with no error naming the field, so check the value against the list first. Include values are OR-joined (provider `anyOf`) and every exclude value is removed (`noneOf`); this filter ANDs with the others.
      - `value` string, required: The filter value — see the field's own description for its vocabulary.
      - `label` string, required: Display label for the value (required; repeat the value when you have no label).
      - `status` 'include' | 'exclude', required: `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies).
    - `linkedinSlugs` string[]: Free text: LinkedIn company slugs (e.g. stripe). A full company URL is accepted and reduced to the part after linkedin.com/company/, and the value is lower-cased, because the provider matches the slug exactly. Several slugs are OR-joined.
  - `savedSearchId` string: Id of one of your COMPANY saved searches to take the filters from instead of `filters` (a people saved search answers 422 SAVED_SEARCH_TYPE_MISMATCH).
  - `savedSearchName` string: Exact title of one of your company saved searches to take the filters from instead of `filters`; two searches sharing the title answer 409 SAVED_SEARCH_NAME_AMBIGUOUS.
  - `query` string: Natural-language description of the companies to find (max 2000 chars), converted into filters server-side instead of `filters`; criteria that could not be mapped come back as `unresolvedCriteria`, and a query yielding no filter answers 422 QUERY_FILTERS_INVALID.
  - `limit` integer, required: Maximum number of matching companies to save (1-10000); the background job saves in pages of 100 and debits 2 credits per company saved as it goes (no upfront credit check).
  - `listId` string: Id of an existing company list to save into (exactly one of `listId` / `listName`).
  - `listName` string: Name of the destination company list, created when none exists; an existing list with the same name (case-insensitive) is reused, a name shared by several lists answers 409 LIST_NAME_AMBIGUOUS, and system list names answer 422 LIST_NAME_RESERVED.

## Response `202`

Success

- object
  - `listIds` string[], required: The single destination company list id the save is writing into.

## Other responses

- `400`: Error
- `401`: Error
- `402`: Error
- `403`: Error
- `404`: Error
- `409`: Error
- `422`: Error
- `429`: Error
- `500`: Error

---

[API](https://skmtc.dev/fuseai/apis/fuse-business-api.md) · [All operations](https://skmtc.dev/fuseai/apis/fuse-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fuseai/apis/fuse-business-api/revisions/50d95e0536f4?raw)