> ## Documentation Index > Fetch the complete documentation index at: https://docs.fuseai.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /business/companies/search/save-to-list openapi: 3.1.0 info: title: Fuse Business API version: 1.0.0 description: >- External API for lists, campaigns, prospect search and contacts. Authenticate with your API token as HTTP Basic. All paths are under /api/v1. servers: - url: https://api.tryfuse.ai/api/v1 description: Production security: - basicAuth: [] tags: - name: Lists - name: Custom columns - name: Smart columns - name: Exports - name: Campaigns - name: Knowledge hubs - name: Analytics - name: Website intent - name: Account - name: Prospect search - name: Campaign steps - name: Scheduled sends - name: Campaign templates - name: Agents - name: Research - name: Company search - name: Saved searches - name: Folders - name: Contacts paths: /business/companies/search/save-to-list: post: tags: - Company search summary: Save company-search results into a list description: >- 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. operationId: saveCompanySearchToList requestBody: required: true content: application/json: schema: type: object properties: filters: type: object properties: nameLike: type: array items: type: string maxLength: 500 description: >- 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: type: array items: type: string description: >- Free text: exact website hosts (e.g. stripe.com), forwarded to the provider unchanged — unlike the people search this filter does NOT strip a scheme, a www. prefix or a path, so send the bare host or it matches nothing. Several domains are OR-joined. keywords: type: array items: type: string description: >- Free-text keywords matched against company names and descriptions; any may match. status: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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`) and every exclude value is removed (`noneOf`); this filter ANDs with the others. tags: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. industriesV2: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. linkedinIndustries: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. crunchbaseCategories: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. crunchbaseCategoryGroups: type: array items: type: string description: >- 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: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. headquartersCountryCode: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. headquartersStateName: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- Headquarters state/province entries whose `value` is the full state or province name (e.g. Florida, California). headquartersCity: type: array items: type: string minLength: 1 maxLength: 200 maxItems: 25 description: >- 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: type: object properties: min: type: number description: >- Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field). max: type: number description: Inclusive upper bound. description: >- Headcount range `{ min?, max? }`; any whole number is taken, but each bound snaps to one of the accepted values 0, 1, 10, 50, 200, 500, 1000, 5000, 10000 (min rounds down, max rounds up). The lower bound is then EXCLUSIVE and the upper bound inclusive, so `{ min: 50 }` matches companies with MORE than 50 employees; pass the bucket below the headcount you want to keep. revenueUSD: type: object properties: min: type: number description: >- Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field). max: type: number description: Inclusive upper bound. description: >- Estimated annual revenue range `{ min?, max? }`; the accepted values are whole US dollars, not millions (5000000 means $5M), and both bounds are inclusive. totalFundingUSD: type: object properties: min: type: number description: >- Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field). max: type: number description: Inclusive upper bound. description: >- Total funding raised range `{ min?, max? }`; the accepted values are whole US dollars, not millions (5000000 means $5M), and both bounds are inclusive. lastFundingUSD: type: object properties: min: type: number description: >- Lower bound, inclusive — except on `employeeCountV2`, whose lower bound is exclusive (see that field). max: type: number description: Inclusive upper bound. description: >- 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. stage: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. technologies: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. investors: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. foundedOn: type: object properties: start: type: string description: Earliest date, ISO-8601 (e.g. 2020-01-01). end: type: string description: Latest date, ISO-8601 (e.g. 2024-12-31). description: >- Founding-date range `{ start?, end? }` as ISO-8601 dates. lastFundedOn: type: object properties: start: type: string description: Earliest date, ISO-8601 (e.g. 2020-01-01). end: type: string description: Latest date, ISO-8601 (e.g. 2024-12-31). description: >- Date range of the most recent funding round, `{ start?, end? }` as ISO-8601 dates. acceleratorsV2: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. fortuneRankings: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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`) and every exclude value is removed (`noneOf`); this filter ANDs with the others. officeLocationsV2: type: array items: type: object properties: value: type: string description: >- The filter value — see the field's own description for its vocabulary. label: type: string description: >- Display label for the value (required; repeat the value when you have no label). status: type: string enum: - include - exclude description: >- `include` matches the value; `exclude` removes companies carrying it (includes OR together, every exclude applies). required: - value - label - status description: >- 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. linkedinSlugs: type: array items: type: string description: >- Free text: LinkedIn company slugs — only the part after linkedin.com/company/ (e.g. stripe), forwarded unchanged, so a full URL matches nothing. Several slugs are OR-joined. description: >- 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. savedSearchId: type: string description: >- 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: type: string minLength: 1 maxLength: 255 description: >- 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: type: string minLength: 1 maxLength: 2000 description: >- 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: type: integer minimum: 1 maximum: 10000 description: >- 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: type: string description: >- Id of an existing company list to save into (exactly one of `listId` / `listName`). listName: type: string minLength: 1 maxLength: 255 description: >- 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. required: - limit description: >- Exactly one filter source (`filters` | `savedSearchId` | `savedSearchName` | `query`) and exactly one destination (`listId` | `listName`), plus `limit`. responses: '202': description: Success headers: RateLimit-Limit: schema: type: integer description: Requests permitted in the current window. RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. RateLimit-Reset: schema: type: integer description: Seconds until the current window resets. content: application/json: schema: type: object required: - listIds properties: listIds: type: array items: type: string description: >- The single destination company list id the save is writing into. minItems: 1 maxItems: 1 example: listIds: - 6a8d82b5c5017e82fb6082ac '400': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - basicAuth: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string message: type: string param: type: - string - 'null' doc_url: type: - string - 'null' request_id: type: - string - 'null' required: - code - message required: - error securitySchemes: basicAuth: type: http scheme: basic description: >- Your API token (`af_…`) as the Basic-auth username, with an empty password. ````