# Set Company Lists

`POST https://api.getprospect.com/v2/companies/lists/set`

Sets the lists of a selection of saved companies to exactly `list_ids` (1-100 company lists): each selected record ends up in those lists and in no other. Select by `ids` (up to 25,000), or by `filters` (everything `POST /v2/companies/search` matches, with the optional `sort_by`, `sort_direction`, `limit`, `exclude_ids` and `extra_ids`): exactly one of the two. Answers a job: 200 with the `done` job when the work ran inline, else 202 with the `running` job and `Location: /v2/jobs/{id}` (poll it after `Retry-After`). One bulk action runs per workspace at a time; an `Idempotency-Key` makes a retry answer the same job. Uses 1 unit of the jobs rate limit. Free: costs no credits.

## Authentication

Pass your API key in the `x-api-key` header.

## Body parameters

- `ids` (string[], optional): companies-v2 company ids (1-25000). Exactly one of `ids` and `filters`.
- `filters` (object, optional): The Company Search filter set; active filters AND together. Also taken by Save Companies Search.
  - `company` (object, optional): Company Search `company` filter: match specific companies by `id`, `name`, `domain` or `linkedin_id`. Example: `{"filters":{"company":{"domain":{"include":["intercom.com","stripe.com"]}}}}`
    - `id` (object, optional): Include/exclude list of GetProspect company ids, used by the Company Search `company.id` filter.
      - `include` (string[], optional): Only these companies, by `id`. Max 20000 ids. Example: `["64f1a2b3c4d5e6f7a8b9c0d2"]`
      - `exclude` (string[], optional): Reject these companies (same `id` values). Max 20000 ids.
    - `name` (object, optional): Include/exclude list of strings matched exactly and case-insensitively, used by Company Search filters such as industry, name and domain.
      - `include` (string[], optional): Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
      - `exclude` (string[], optional): Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
    - `domain` (object, optional): Include/exclude list of strings matched exactly and case-insensitively, used by Company Search filters such as industry, name and domain.
      - `include` (string[], optional): Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
      - `exclude` (string[], optional): Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
    - `linkedin_id` (object, optional): Include/exclude filter on LinkedIn's numeric company id, shared by the `company.linkedin_id` filter of People Search and Company Search.
      - `include` (integer[], optional): Match these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by `linkedin_url` first, then filter by the `id` that comes back. Max 500 items. Example: `[162479]`
      - `exclude` (integer[], optional): Reject these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by `linkedin_url` first, then filter by the `id` that comes back. Max 500 items.
  - `company_industry` (object, optional): Include/exclude list of strings matched exactly and case-insensitively, used by Company Search filters such as industry, name and domain. Example: `{"filters":{"company_industry":{"include":["Software & Internet","IT Services & IT Consulting"],"exclude":["Staffing & Recruiting"]}}}`
    - `include` (string[], optional): Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
    - `exclude` (string[], optional): Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
  - `company_type` (object, optional): Include/exclude filter on company type (GET /v2/enums/company_types), shared by `company_type` in People Search and Company Search. Example: `{"filters":{"company_type":{"include":["Privately Held","Public Company"]}}}`
    - `include` (enum[], optional): Company types to match (any of). Allowed values: `Privately Held`, `Public Company`, `Non Profit`, `Self Owned`, `Self Employed`, `Partnership`, `Educational`, `Government Agency`, `Unknown`.
    - `exclude` (enum[], optional): Company types to reject. Allowed values: `Privately Held`, `Public Company`, `Non Profit`, `Self Owned`, `Self Employed`, `Partnership`, `Educational`, `Government Agency`, `Unknown`.
  - `company_business_type` (object, optional): Include/exclude filter on business type (GET /v2/enums/business_types), shared by `company_business_type` in People Search and Company Search. Example: `{"filters":{"company_business_type":{"include":["B2B"]}}}`
    - `include` (enum[], optional): Business types to match (any of). Allowed values: `B2B`, `B2C`, `Nonprofit`, `Unknown`.
    - `exclude` (enum[], optional): Business types to reject. Allowed values: `B2B`, `B2C`, `Nonprofit`, `Unknown`.
  - `company_revenue_stream` (object, optional): Include/exclude filter on revenue stream (GET /v2/enums/revenue_streams), shared by `company_revenue_stream` in People Search and Company Search. Example: `{"filters":{"company_revenue_stream":{"include":["Subscriptions / Recurring","Product Sales"]}}}`
    - `include` (enum[], optional): Revenue streams to match (any of). Allowed values: `Professional Services`, `Product Sales`, `Grants / Donations`, `Subscriptions / Recurring`, `Project / Contract Work`, `Event / Experience Revenue`, `Transaction Fees`, `Rental / Leasing`, `Advertising`, `Financial Services`, `Licensing / IP`, `Unknown`.
    - `exclude` (enum[], optional): Revenue streams to reject. Allowed values: `Professional Services`, `Product Sales`, `Grants / Donations`, `Subscriptions / Recurring`, `Project / Contract Work`, `Event / Experience Revenue`, `Transaction Fees`, `Rental / Leasing`, `Advertising`, `Financial Services`, `Licensing / IP`, `Unknown`.
  - `company_country` (object, optional): Company Search `company_country` filter: ISO-3166-1 alpha-2 codes to include or exclude, plus `headquarters_only`. Example: `{"filters":{"company_country":{"include":["US","CA"],"headquarters_only":true}}}`
    - `include` (string[], optional): Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
    - `exclude` (string[], optional): Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
    - `headquarters_only` (boolean, optional, default: false): When true, match the company headquarters country only. When false (default), any office country we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected).
  - `company_location` (object, optional): Company location filter on unified location strings plus `headquarters_only`, shared by `company_location` in People Search and Company Search. Example: `{"filters":{"company_location":{"include":["San Francisco, California, United States"],"headquarters_only":true}}}`
    - `include` (string[], optional): Match these locations (any of). Unified strings like "United States", "Texas, United States", "San Francisco, California, United States" - or a region like "EMEA", "APAC", "Europe", "Latin America", which expands to its member countries (full list with member countries: GET /v2/enums/regions). Max 100 items, each 2-200 chars. If none of the values resolve to a known location, the request fails with 400.
    - `exclude` (string[], optional): Reject these locations (same unified-string format). Max 100 items, each 2-200 chars. Values that do not resolve are skipped.
    - `headquarters_only` (boolean, optional, default: false): When true, match the company headquarters location only. When false (default), any office location we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected).
  - `company_headcount_range` (enum[], optional): Bucketed headcount range (see GET /v2/enums/employee_ranges). 1-8 buckets. Allowed values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Example: `{"filters":{"company_headcount_range":["51-200","201-500"]}}`
  - `company_headcount_custom` (object, optional): Inclusive numeric range (`min` / `max`), used by Company Search `company_headcount_custom` and `company_founded`. Example: `{"filters":{"company_headcount_custom":{"min":100,"max":5000}}}`
    - `min` (number, optional): Lower bound (inclusive). Optional.
    - `max` (number, optional): Upper bound (inclusive). Must be >= min. Optional.
  - `company_founded` (object, optional): Inclusive numeric range (`min` / `max`), used by Company Search `company_headcount_custom` and `company_founded`. Example: `{"filters":{"company_founded":{"min":2010,"max":2020}}}`
    - `min` (number, optional): Lower bound (inclusive). Optional.
    - `max` (number, optional): Upper bound (inclusive). Must be >= min. Optional.
  - `company_naics` (object, optional): Include/exclude list of numbers, used by Company Search `company_naics`. Example: `{"filters":{"company_naics":{"include":[541511,541512]}}}`
    - `include` (number[], optional): Match companies whose value is in this list - any single value qualifies. Optional - provide include and/or exclude. Max 500 items.
    - `exclude` (number[], optional): Reject companies whose value is in this list. 0-500 items.
  - `company_technologies` (object, optional): Filter on technologies detected on the company website, by suggest id, shared by `company_technologies` in People Search and Company Search. Example: `{"filters":{"company_technologies":{"include":["3421"],"match_mode":"ANY"}}}`
    - `include` (string[], optional): Technology ids to match. `match_mode: ANY` (default): a company using any of them qualifies; `ALL`: it must use every one. Max 500. Example: `["3421"]`
    - `exclude` (string[], optional): Reject companies using any of these technology ids. Max 500.
    - `match_mode` (enum, optional): How `include` combines: `ANY` (default) - at least one; `ALL` - every one, on the same company. Allowed values: `ANY`, `ALL`.
  - `company_technology_categories` (object, optional): Filter on technology categories, by suggest id, shared by `company_technology_categories` in People Search and Company Search. Example: `{"filters":{"company_technology_categories":{"include":["1"]}}}`
    - `include` (string[], optional): Category ids to match (any of). Max 200. Example: `["1"]`
    - `exclude` (string[], optional): Reject companies using any technology in these category ids. Max 200.
  - `company_keywords` (object, optional): Phrase filter on company keyword fields (GET /v2/enums/keywords_sources), shared by `company_keywords` in People Search and Company Search. Example: `{"filters":{"company_keywords":{"include":["customer support","help desk"],"include_all":true,"sources":["specialties"]}}}`
    - `include` (string[], required): Phrases to search for. 1-20 items, 3-100 chars each. Matched as phrases: a multi-word entry like "email finder" requires those words adjacent and in order within one of the selected source fields, not merely present somewhere in it.
    - `exclude` (string[], optional): Phrases that disqualify a company. 0-20 items. Matched as phrases, same as `include`.
    - `include_all` (boolean, optional, default: false): When true, every phrase in `include` must match; otherwise any single match qualifies.
    - `sources` (enum[], optional): Restrict matching to these source fields (see GET /v2/enums/keywords_sources). Omit to use the default source set - see this `company_keywords` filter's own description above for what that is. Allowed values: `specialties`, `social_media_description`, `website_pages`.
  - `lists` (object, optional): Filter for Company Search on your workspace's saved companies: list membership, and saved or not. Carry at least one of `include`, `exclude` or `saved`. Example: `{"filters":{"lists":{"include":["66f1a2b3c4d5e6f7a8b9c0d1"]}}}`
    - `saved` (enum, optional): any = only companies your workspace saved, in a list or not; none = only companies your workspace has not saved; without_list = only companies your workspace saved but did not file into any list. Allowed values: `any`, `none`, `without_list`.
    - `include` (string[], optional): Only companies your workspace filed into these company list ids (`GET /v2/lists?type=companies`). Max 100.
    - `exclude` (string[], optional): Hide companies your workspace filed into these company list ids. Max 100.
- `sort_by` (enum, optional): With `filters`: which companies are "the first `limit`". Allowed values: `company_name`, `company_employee_count`, `company_industry`, `company_country`, `company_founded`, `company_saved_at`.
- `sort_direction` (enum, optional): Ignored without `sort_by`. Allowed values: `asc`, `desc`.
- `limit` (number, optional, min: 1, max: 25000): With `filters`: how many companies at most.
- `exclude_ids` (string[], optional): With `filters`: company ids taken out of the match.
- `extra_ids` (string[], optional): With `filters`: hand-ticked company ids outside the match, added to it.
- `list_ids` (string[], required): The company lists the selection ends up in, exactly (1-100).

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/companies/lists/set \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "ids": [
    "5f8d0d55b54764421b7156c9",
    "5f8d0d55b54764421b7156d2"
  ],
  "list_ids": [
    "66f1a2b3c4d5e6f7a8b9c0e7"
  ]
}
'
```

## Response 200

Done inline: the `done` job.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2d4e5f6a7b8c9d0e1",
    "type": "companies_lists_set",
    "status": "done",
    "total": 2,
    "processed": 2,
    "progress_percent": 100,
    "result": {
      "updated": 2,
      "skipped": 0
    },
    "error": null,
    "resource_url": null,
    "created_at": "2026-10-08T12:00:00.000Z",
    "finished_at": "2026-10-08T12:00:00.000Z"
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}
```

## Response 202

Queued: the `running` job; poll `Location`.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2d4e5f6a7b8c9d0e1",
    "type": "companies_lists_set",
    "status": "running",
    "total": 18450,
    "processed": 0,
    "progress_percent": 0,
    "result": {
      "updated": 0,
      "skipped": 0
    },
    "error": null,
    "resource_url": null,
    "created_at": "2026-10-08T12:00:00.000Z",
    "finished_at": null
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}
```

## Response 400

Invalid body or `Idempotency-Key` (`VALIDATION_ERROR` with `payload.code`); neither or both of `ids` and `filters`; or a list in `list_ids` is not a live list of that type in this workspace (`VALIDATION_ERROR`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "list_ids must contain at least 1 elements",
      "payload": {
        "field": "list_ids",
        "code": "out_of_range",
        "received_value": [],
        "received_type": "object",
        "constraints": {
          "arrayMinSize": "list_ids must contain at least 1 elements"
        }
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 409

Another bulk action of the workspace is still running (`CONFLICT`, `payload.code: bulk_action_running` with its `job_id`; poll it, then retry); or the `Idempotency-Key` was used for another request (`idempotency_key_reused`), or its first request is still running inline (`idempotency_in_progress`, with `Retry-After`).

```json
{
  "success": false,
  "data": {
    "code": "bulk_action_running",
    "job_id": "6703f1c2d4e5f6a7b8c9d0e1"
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "Another bulk action is still running in this workspace.",
      "payload": {
        "code": "bulk_action_running",
        "job_id": "6703f1c2d4e5f6a7b8c9d0e1"
      }
    }
  ]
}
```

## Response 429

Over the `jobs` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced.

## Response 500

Unexpected server error.