Set Company Lists

POST/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.

Body parameters

idsstring[]optional
companies-v2 company ids (1-25000). Exactly one of ids and filters.

filtersobjectoptional

The Company Search filter set; active filters AND together. Also taken by Save Companies Search.

Child attributes

companyobjectoptional

Company Search company filter: match specific companies by id, name, domain or linkedin_id.

Child attributes

idobjectoptional
Include/exclude list of GetProspect company ids, used by the Company Search company.id filter.
Field Type Description
include string[] Only these companies, by id. Max 20000 ids.
Example: ["64f1a2b3c4d5e6f7a8b9c0d2"]
exclude string[] Reject these companies (same id values). Max 20000 ids.

Field	Type	Description
`include`	string[]	Only these companies, by `id`. Max 20000 ids. Example: `["64f1a2b3c4d5e6f7a8b9c0d2"]`
`exclude`	string[]	Reject these companies (same `id` values). Max 20000 ids.

nameobjectoptional

Include/exclude list of strings matched exactly and case-insensitively, used by Company Search filters such as industry, name and domain.

Field	Type	Description
`include`	string[]	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[]	Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.

domainobjectoptional

Include/exclude list of strings matched exactly and case-insensitively, used by Company Search filters such as industry, name and domain.

Field	Type	Description
`include`	string[]	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[]	Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.

linkedin_idobjectoptional

Include/exclude filter on LinkedIn's numeric company id, shared by the company.linkedin_id filter of People Search and Company Search.

Field	Type	Description
`include`	integer[]	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[]	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.

Example

{
  "filters": {
    "company": {
      "domain": {
        "include": [
          "intercom.com",
          "stripe.com"
        ]
      }
    }
  }
}

company_industryobjectoptional

Include/exclude list of strings matched exactly and case-insensitively, used by Company Search filters such as industry, name and domain.

Field	Type	Description
`include`	string[]	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[]	Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.

Example

{
  "filters": {
    "company_industry": {
      "include": [
        "Software & Internet",
        "IT Services & IT Consulting"
      ],
      "exclude": [
        "Staffing & Recruiting"
      ]
    }
  }
}

company_typeobjectoptional

Include/exclude filter on company type (Company types), shared by company_type in People Search and Company Search.

Field	Type	Description
`include`	enum[]	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[]	Company types to reject. Allowed values: `Privately Held` `Public Company` `Non Profit` `Self Owned` `Self Employed` `Partnership` `Educational` `Government Agency` `Unknown`

Example

{
  "filters": {
    "company_type": {
      "include": [
        "Privately Held",
        "Public Company"
      ]
    }
  }
}

company_business_typeobjectoptional
Include/exclude filter on business type (Business types), shared by company_business_type in People Search and Company Search.
Field Type Description
include enum[] Business types to match (any of).
Allowed values: B2B B2C Nonprofit Unknown
exclude enum[] Business types to reject.
Allowed values: B2B B2C Nonprofit Unknown
Example
```
{
  "filters": {
    "company_business_type": {
      "include": [
        "B2B"
      ]
    }
  }
}
```

Field	Type	Description
`include`	enum[]	Business types to match (any of). Allowed values: `B2B` `B2C` `Nonprofit` `Unknown`
`exclude`	enum[]	Business types to reject. Allowed values: `B2B` `B2C` `Nonprofit` `Unknown`

company_revenue_streamobjectoptional

Include/exclude filter on revenue stream (Revenue streams), shared by company_revenue_stream in People Search and Company Search.

Field	Type	Description
`include`	enum[]	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[]	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`

Example

{
  "filters": {
    "company_revenue_stream": {
      "include": [
        "Subscriptions / Recurring",
        "Product Sales"
      ]
    }
  }
}

company_countryobjectoptional

Company Search company_country filter: ISO-3166-1 alpha-2 codes to include or exclude, plus headquarters_only.

Field	Type	Description
`include`	string[]	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[]	Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
`headquarters_only`	boolean	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). default: false.

Example

{
  "filters": {
    "company_country": {
      "include": [
        "US",
        "CA"
      ],
      "headquarters_only": true
    }
  }
}

company_locationobjectoptional

Company location filter on unified location strings plus headquarters_only, shared by company_location in People Search and Company Search.

Field	Type	Description
`include`	string[]	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[]	Reject these locations (same unified-string format). Max 100 items, each 2-200 chars. Values that do not resolve are skipped.
`headquarters_only`	boolean	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). default: false.

Example

{
  "filters": {
    "company_location": {
      "include": [
        "San Francisco, California, United States"
      ],
      "headquarters_only": true
    }
  }
}

company_headcount_rangeenum[]optional

Bucketed headcount range (see Employee ranges). 1-8 buckets.

Example

{
  "filters": {
    "company_headcount_range": [
      "51-200",
      "201-500"
    ]
  }
}

company_headcount_customobjectoptional
Inclusive numeric range (min / max), used by Company Search company_headcount_custom and company_founded.
Field Type Description
min number Lower bound (inclusive). Optional.
max number Upper bound (inclusive). Must be >= min. Optional.
Example
```
{
  "filters": {
    "company_headcount_custom": {
      "min": 100,
      "max": 5000
    }
  }
}
```
company_foundedobjectoptional
Inclusive numeric range (min / max), used by Company Search company_headcount_custom and company_founded.
Field Type Description
min number Lower bound (inclusive). Optional.
max number Upper bound (inclusive). Must be >= min. Optional.
Example
```
{
  "filters": {
    "company_founded": {
      "min": 2010,
      "max": 2020
    }
  }
}
```

Field	Type	Description
`min`	number	Lower bound (inclusive). Optional.
`max`	number	Upper bound (inclusive). Must be >= min. Optional.

Field	Type	Description
`min`	number	Lower bound (inclusive). Optional.
`max`	number	Upper bound (inclusive). Must be >= min. Optional.

company_naicsobjectoptional

Include/exclude list of numbers, used by Company Search company_naics.

Field	Type	Description
`include`	number[]	Match companies whose value is in this list - any single value qualifies. Optional - provide include and/or exclude. Max 500 items.
`exclude`	number[]	Reject companies whose value is in this list. 0-500 items.

Example

{
  "filters": {
    "company_naics": {
      "include": [
        541511,
        541512
      ]
    }
  }
}

company_technologiesobjectoptional

Filter on technologies detected on the company website, by suggest id, shared by company_technologies in People Search and Company Search.

Field	Type	Description
`include`	string[]	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[]	Reject companies using any of these technology ids. Max 500.
`match_mode`	enum	How `include` combines: `ANY` (default) - at least one; `ALL` - every one, on the same company. Allowed values: `ANY` `ALL`

Example

{
  "filters": {
    "company_technologies": {
      "include": [
        "3421"
      ],
      "match_mode": "ANY"
    }
  }
}

company_technology_categoriesobjectoptional
Filter on technology categories, by suggest id, shared by company_technology_categories in People Search and Company Search.
Field Type Description
include string[] Category ids to match (any of). Max 200.
Example: ["1"]
exclude string[] Reject companies using any technology in these category ids. Max 200.
Example
```
{
  "filters": {
    "company_technology_categories": {
      "include": [
        "1"
      ]
    }
  }
}
```

Field	Type	Description
`include`	string[]	Category ids to match (any of). Max 200. Example: `["1"]`
`exclude`	string[]	Reject companies using any technology in these category ids. Max 200.

company_keywordsobjectoptional

Phrase filter on company keyword fields (Keyword sources), shared by company_keywords in People Search and Company Search.

Field	Type	Description
`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[]	Phrases that disqualify a company. 0-20 items. Matched as phrases, same as `include`.
`include_all`	boolean	When true, every phrase in `include` must match; otherwise any single match qualifies. default: false.
`sources`	enum[]	Restrict matching to these source fields (see Keyword sources). Omit to use the default source set - see this `company_keywords` filter's own description above for what that is.

Example

{
  "filters": {
    "company_keywords": {
      "include": [
        "customer support",
        "help desk"
      ],
      "include_all": true,
      "sources": [
        "specialties"
      ]
    }
  }
}

listsobjectoptional

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.

Field	Type	Description
`saved`	enum	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[]	Only companies your workspace filed into these company list ids (`GET /v2/lists?type=companies`). Max 100.
`exclude`	string[]	Hide companies your workspace filed into these company list ids. Max 100.

Example

{
  "filters": {
    "lists": {
      "include": [
        "66f1a2b3c4d5e6f7a8b9c0d1"
      ]
    }
  }
}

sort_byenumoptional
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_directionenumoptional
Ignored without sort_by.
Allowed values: asc desc
limitnumberoptionalmin: 1max: 25000
With filters: how many companies at most.
exclude_idsstring[]optional
With filters: company ids taken out of the match.
extra_idsstring[]optional
With filters: hand-ticked company ids outside the match, added to it.
list_idsstring[]required
The company lists the selection ends up in, exactly (1-100).

Responses

200 Done inline: the done job.
202 Queued: the running job; poll Location.
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).
401 Missing, unknown or inactive credentials (UNAUTHORIZED).
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).
429 Over the jobs rate limit (RATE_LIMIT); wait Retry-After seconds. Sent only where rate limits are enforced.
500 Unexpected server error.

For error handling see Errors. Response objects are described in Person object and Company object.

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

{
  "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"
  }
}