# Set People Lists

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

Sets the lists of a selection of saved people to exactly `list_ids` (1-100 people 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/people/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): contacts-v2 person ids (1-25000). Exactly one of `ids` and `filters`.
- `filters` (object, optional): The People Search filter set, also taken by the whole-search save, enrich and credits preview.
  - `person` (object, optional): Filter on the person themselves for People Search: by GetProspect person id, by name, or a lookup of specific profiles by LinkedIn URL. Example: `{"filters":{"person":{"name":{"include":["Dmytro Shulha"]}}}}`
    - `id` (object, optional): Filter on GetProspect person ids for People Search: only these people, or reject them (up to 100 ids each).
      - `include` (string[], optional): Only these people. Use the `id` values returned by People Search results, People Enrich, or Search Suggestions with `type: "person"`. Max 100 ids.
      - `exclude` (string[], optional): Reject these people (same `id` values). Max 100 ids.
    - `name` (object, optional): Filter on the person's name for People Search: include or exclude names, each term matching when all its words appear in the name.
      - `include` (string[], optional): Names to match. Every word of a term must appear somewhere in the name, in any order, so "Dmytro Shulha" matches "Dmytro Shulha, PhD" and "Helena Calero" matches "Helena Montoya-Calero". Case-insensitive; diacritics are significant ("Jose" does not match "José"). Any single term qualifies. Max 500 items.
      - `exclude` (string[], optional): Names to reject, matched the same way. Max 500 items.
    - `linkedin_url` (object, optional): Lookup of specific people for People Search by LinkedIn profile URL (1-50); the other filters narrow the result.
      - `include` (string[], optional): Look up specific profiles by LinkedIn URL. The URLs pick the people and every other filter narrows them - except `company.name.include`, which here only picks which position is returned as `primary_position`. Cannot be combined with `person.id` or `person.name`. Results keep the order of the URLs (`sort_by` does not apply) and each carries the `matched_url` it was found by. 1-50 urls. Example: `["https://linkedin.com/in/emily-carter-sample"]`
  - `person_location` (object, optional): Include/exclude filter on unified location strings (country, state, city or region), used by People Search `person_location`. Example: `{"filters":{"person_location":{"include":["California, United States","Austin, Texas, United States"],"exclude":["San Francisco, California, United States"]}}}`
    - `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.
  - `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":["email marketing"],"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`.
  - `person_job_title` (object, optional): Filter on the person's job title for People Search: include or exclude titles matched per `match_mode`, or one `boolean_search` expression instead. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager","Growth Marketing Manager"],"exclude":["Assistant"],"match_mode":"CONTAINS"}}}`
    - `include` (string[], optional): Job titles to match. Max 100 items, each 2-100 chars. Combined per match_mode. Known abbreviations also match their canonical spelling and vice versa (e.g. "CEO" matches "Chief Executive Officer"), however you spell them - "VP of Marketing", "VP, Marketing" and "Marketing VP" all match what "VP Marketing" matches. Under CONTAINS, terms match any of the roles a position carries - including the secondary roles of combined titles like "Founder & CEO" and the original title text.
    - `exclude` (string[], optional): Job titles to reject. Max 100 items, each 2-100 chars.
    - `match_mode` (enum, optional): CONTAINS = the title contains every word of the term, in any order; connector words (of, and, the, ...) are ignored, so "Director of Sales Enablement" also matches "Director, Sales Enablement". EXACT = the person's LinkedIn title is exactly the term, so "founder" does not match "Founder & CEO", "Founder of Acme LLC" or "Fondateur" - use CONTAINS for those. Applies to include/exclude; ignored when boolean_search is set. Allowed values: `CONTAINS`, `EXACT`.
    - `boolean_search` (string, optional, max length: 20000): Boolean / Cartesian title query, e.g. "(CEO OR CTO) AND !Intern". Syntax: bareword=contains; 'single quotes'=contains too, and the way to write a title with a space in it - 'vp marketing' matches exactly what include: ["vp marketing"] matches; "double quotes"=exact; `backticks`=words in order with connectors bridged, so `vp marketing` finds "VP of Marketing" but not "VP Sales and Marketing" or "Marketing VP"; !=exclude, AND/OR, ()=grouping. Max 500 terms, depth 5, each term 2-100 chars. AND and OR cannot be mixed at the same nesting level - use parentheses to group. Mutually exclusive with include/exclude.
  - `person_seniority` (object, optional): Filter on the seniority level of the person's position for People Search: include or exclude values from GET /v2/enums/seniorities. Example: `{"filters":{"person_seniority":{"include":["Chief Officer","VP","Director"]}}}`
    - `include` (enum[], optional): Seniority levels to match (any of). See GET /v2/enums/seniorities. Allowed values: `Owner`, `Partner`, `Chief Officer`, `VP`, `Director`, `Senior`, `Manager`, `Entry`, `Intern`, `Unpaid`.
    - `exclude` (enum[], optional): Seniority levels to reject. See GET /v2/enums/seniorities. Allowed values: `Owner`, `Partner`, `Chief Officer`, `VP`, `Director`, `Senior`, `Manager`, `Entry`, `Intern`, `Unpaid`.
  - `person_department` (object, optional): Filter on the department of the person's position for People Search: include or exclude department groups or sub-departments. Example: `{"filters":{"person_department":{"include":["Marketing","Sales"],"exclude":["Accounting"]}}}`
    - `include` (enum[], optional): Departments to match (any of). Accepts a department group ("Sales", "Legal") or a specific sub-department ("Sales Operations", "Founder"). A group matches everyone in it; a sub-department matches only that sub-department. See GET /v2/enums/departments. Allowed values: `C-Suite`, `Consulting`, `Design`, `Education`, `Engineering & Technical`, `Finance`, `Human Resources`, `Information Technology`, `Legal`, `Marketing`, `Medical & Health`, `Operations`, `Sales`, `Account Management`, `Accounting`, `Advertising`, `Anesthesiology`, `Artificial Intelligence & Machine Learning`, `Bioengineering`, `Brand Management`, `Business Development`, `Business Intelligence`, `Call Center`, `Channel Sales`, `Chemical Engineering`, `Chiropractics`, `Clinical Systems`, `Cloud & Infrastructure`, `Compensation & Benefits`, `Compliance`, `Construction`, `Consultant`, `Content Marketing`, `Contracts`, `Corporate Secretary`, `Culture, Diversity & Inclusion`, `Customer Experience`, `Customer Marketing`, `Customer Retention & Development`, `Customer Service & Support`, `Customer Success`, `Data Center`, `Data Science`, `Database Administration`, `Demand Generation`, `Dentistry`, `Dermatology`, `DevOps`, `Digital Marketing`, `Doctors & Physicians`, `eCommerce Development`, `eCommerce Marketing`, `eDiscovery`, `Employee & Labor Relations`, `Engineering Management`, `Enterprise Architecture`, `Epidemiology`, `ERP Systems`, `Event Marketing`, `Executive`, `Facilities Management`, `Field & Outside Sales`, `Finance Executive`, `Financial Planning & Analysis`, `Financial Reporting`, `Financial Risk`, `Financial Systems`, `Founder`, `Governmental Affairs & Regulatory Law`, `Graphic & Visual & Brand Design`, `Help Desk & Desktop Services`, `HR Business Partner`, `Human Resources Executive`, `Industrial Engineering`, `Infectious Disease`, `Information Security`, `Information Technology Executive`, `Inside Sales`, `Intellectual Property & Patent`, `Internal Audit & Control`, `Investor Relations`, `IT Asset Management`, `IT Audit & IT Compliance`, `IT Operations`, `Labor & Employment`, `Lawyer & Attorney`, `Lead Generation`, `Learning & Development`, `Legal Counsel`, `Legal Executive`, `Legal Operations`, `Litigation`, `Logistics`, `Marketing Analytics & Insights`, `Marketing Communications`, `Marketing Executive`, `Marketing Operations`, `Medical & Health Executive`, `Medical Administration`, `Medical Education & Training`, `Medical Research`, `Mergers & Acquisitions`, `Mobile Development`, `Networking`, `Neurology`, `Nursing`, `Nutrition & Dietetics`, `Obstetrics & Gynecology`, `Oncology`, `Operations Executive`, `Ophthalmology`, `Optometry`, `Organizational Development`, `Orthopedics`, `Pathology`, `Pediatrics`, `People Operations`, `Pharmacy`, `Physical Security`, `Physical Therapy`, `Principal`, `Privacy`, `Product Management`, `Product Marketing`, `Product or UI&UX Design`, `Professor`, `Project Management`, `Psychiatry`, `Psychology`, `Public Health`, `Public Relations`, `Quality Management`, `Radiology`, `Real Estate`, `Real Estate Finance`, `Recruiting & Talent Acquisition`, `Revenue Operations`, `Safety`, `Sales Enablement`, `Sales Engineering`, `Sales Leader`, `Sales Operations`, `Scrum Master & Agile Coach`, `Search Engine Optimization & Pay Per Click`, `Servers & Cloud Infrastructure`, `Social Media Marketing`, `Software Development`, `Sourcing & Procurement`, `Superintendent`, `Supply Chain`, `Talent Management`, `Tax`, `Teacher`, `Telecommunications`, `Test & Quality Assurance`, `Treasury`, `Web Design`, `Web Development`, `Workforce Management`.
    - `exclude` (enum[], optional): Departments to reject. A group rejects everyone in it; a sub-department rejects only that sub-department. See GET /v2/enums/departments. Allowed values: `C-Suite`, `Consulting`, `Design`, `Education`, `Engineering & Technical`, `Finance`, `Human Resources`, `Information Technology`, `Legal`, `Marketing`, `Medical & Health`, `Operations`, `Sales`, `Account Management`, `Accounting`, `Advertising`, `Anesthesiology`, `Artificial Intelligence & Machine Learning`, `Bioengineering`, `Brand Management`, `Business Development`, `Business Intelligence`, `Call Center`, `Channel Sales`, `Chemical Engineering`, `Chiropractics`, `Clinical Systems`, `Cloud & Infrastructure`, `Compensation & Benefits`, `Compliance`, `Construction`, `Consultant`, `Content Marketing`, `Contracts`, `Corporate Secretary`, `Culture, Diversity & Inclusion`, `Customer Experience`, `Customer Marketing`, `Customer Retention & Development`, `Customer Service & Support`, `Customer Success`, `Data Center`, `Data Science`, `Database Administration`, `Demand Generation`, `Dentistry`, `Dermatology`, `DevOps`, `Digital Marketing`, `Doctors & Physicians`, `eCommerce Development`, `eCommerce Marketing`, `eDiscovery`, `Employee & Labor Relations`, `Engineering Management`, `Enterprise Architecture`, `Epidemiology`, `ERP Systems`, `Event Marketing`, `Executive`, `Facilities Management`, `Field & Outside Sales`, `Finance Executive`, `Financial Planning & Analysis`, `Financial Reporting`, `Financial Risk`, `Financial Systems`, `Founder`, `Governmental Affairs & Regulatory Law`, `Graphic & Visual & Brand Design`, `Help Desk & Desktop Services`, `HR Business Partner`, `Human Resources Executive`, `Industrial Engineering`, `Infectious Disease`, `Information Security`, `Information Technology Executive`, `Inside Sales`, `Intellectual Property & Patent`, `Internal Audit & Control`, `Investor Relations`, `IT Asset Management`, `IT Audit & IT Compliance`, `IT Operations`, `Labor & Employment`, `Lawyer & Attorney`, `Lead Generation`, `Learning & Development`, `Legal Counsel`, `Legal Executive`, `Legal Operations`, `Litigation`, `Logistics`, `Marketing Analytics & Insights`, `Marketing Communications`, `Marketing Executive`, `Marketing Operations`, `Medical & Health Executive`, `Medical Administration`, `Medical Education & Training`, `Medical Research`, `Mergers & Acquisitions`, `Mobile Development`, `Networking`, `Neurology`, `Nursing`, `Nutrition & Dietetics`, `Obstetrics & Gynecology`, `Oncology`, `Operations Executive`, `Ophthalmology`, `Optometry`, `Organizational Development`, `Orthopedics`, `Pathology`, `Pediatrics`, `People Operations`, `Pharmacy`, `Physical Security`, `Physical Therapy`, `Principal`, `Privacy`, `Product Management`, `Product Marketing`, `Product or UI&UX Design`, `Professor`, `Project Management`, `Psychiatry`, `Psychology`, `Public Health`, `Public Relations`, `Quality Management`, `Radiology`, `Real Estate`, `Real Estate Finance`, `Recruiting & Talent Acquisition`, `Revenue Operations`, `Safety`, `Sales Enablement`, `Sales Engineering`, `Sales Leader`, `Sales Operations`, `Scrum Master & Agile Coach`, `Search Engine Optimization & Pay Per Click`, `Servers & Cloud Infrastructure`, `Social Media Marketing`, `Software Development`, `Sourcing & Procurement`, `Superintendent`, `Supply Chain`, `Talent Management`, `Tax`, `Teacher`, `Telecommunications`, `Test & Quality Assurance`, `Treasury`, `Web Design`, `Web Development`, `Workforce Management`.
  - `person_months_in_current_role` (object, optional): An inclusive range of whole months (0-600), used by the People Search tenure filters for the current role and the current company. Example: `{"filters":{"person_months_in_current_role":{"min":6,"max":24}}}`
    - `min` (integer, optional, min: 0, max: 600): Minimum whole months (inclusive), 0-600. Optional.
    - `max` (integer, optional, min: 0, max: 600): Maximum whole months (inclusive), 0-600, must be >= min. Optional.
  - `person_months_in_current_company` (object, optional): An inclusive range of whole months (0-600), used by the People Search tenure filters for the current role and the current company. Example: `{"filters":{"person_months_in_current_company":{"min":12}}}`
    - `min` (integer, optional, min: 0, max: 600): Minimum whole months (inclusive), 0-600. Optional.
    - `max` (integer, optional, min: 0, max: 600): Maximum whole months (inclusive), 0-600, must be >= min. Optional.
  - `person_job_change` (object, optional): Filter for People Search on a recent job change: the current role started within `timeframe_months`, optionally narrowed by `change_type`. Example: `{"filters":{"person_job_change":{"timeframe_months":3,"change_type":"new_company"}}}`
    - `timeframe_months` (integer, required, min: 1, max: 1000): Months since the current role started, counted in CALENDAR months the way LinkedIn counts them: a role is "N months" if it spans N calendar months inclusive, so a role begun any time in August is 2 months old on 1 September. `timeframe_months: 1` therefore matches only roles begun in the current month. Any whole number from 1 to 1000. Replaces the former `timeframe_days`, which accepted only 30, 60, 90, 180, 270 or 365. Example: `3`
    - `change_type` (enum, optional): any = any recent role change; new_company = also changed company; promotion = changed role at the same company (approximation, includes lateral moves). Allowed values: `any`, `promotion`, `new_company`.
  - `company` (object, optional): Filter on the person's company for People Search: by company id, website domain, name or LinkedIn company id. Example: `{"filters":{"company":{"name":{"include":["Intercom","Stripe"]}}}}`
    - `id` (object, optional): Filter on the person's company for People Search by GetProspect company id: include or exclude companies.
      - `include` (string[], optional): Only people who work at one of these companies. Use the `id` values returned by Company Search or in People Search results. Combines with an exact `company.name` as OR (a person at any listed id or any listed name); `company.domain`, `company_keywords` and a CONTAINS `company.name` still narrow it. Max 20000 ids.
      - `exclude` (string[], optional): Reject people who work at any of these companies (same `id` values). Max 20000 ids.
    - `domain` (object, optional): Filter on the person's company for People Search by website domain: include or exclude domains, with `match_mode` for which company pages count. Example: `{"filters":{"company":{"domain":{"include":["stripe.com"]}}}}`
      - `include` (string[], optional): Only people who work at the organization that owns one of these domains, e.g. "stripe.com" - see `match_mode` for which of its company pages count. Scheme, "www." and any path are stripped. Max 100 items.
      - `exclude` (string[], optional): Reject people whose company is on one of these domains.
      - `match_mode` (enum, optional): Which company pages an `include` domain stands for. ORGANIZATION (default) = every company page that belongs to the organization owning the domain: its main page, its regional, brand and subsidiary pages. A small page that only links to the domain - a business hosted on a platform, a same-named company - is left out. PRIMARY = only the one main company page of the domain, leaving out the organization's other pages. LINKEDIN_WEBSITE = only the organization's pages whose own LinkedIn website is on the domain, so the domain is never inferred: "stripe.com", "stripe.com/jobs" and "jobs.stripe.com" all match "stripe.com"; a page that lists another site, or no website, does not. `exclude` is not affected: it always rejects every company on the domain. Allowed values: `ORGANIZATION`, `PRIMARY`, `LINKEDIN_WEBSITE`.
    - `name` (object, optional): Filter on the person's company for People Search by name: include or exclude names, matched exactly or as a substring per `match_mode`.
      - `include` (string[], optional): Company names to match. Combined per match_mode. With EXACT, a value shaped like a website ("stripe.com", "https://www.stripe.com/about") also matches the company on that domain. Max 500 items.
      - `exclude` (string[], optional): Company names to reject. With EXACT, a website-shaped value also rejects the company on that domain.
      - `match_mode` (enum, optional): EXACT (default) = the whole company name equals the term, case-insensitive. CONTAINS = the name contains the term as a substring ("Haven Health" matches "Haven Health Management") - resolved against the company index, so it is slower and capped; narrow the term if the request is rejected. Allowed values: `EXACT`, `CONTAINS`.
    - `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): Filter on the industry of the person's company for People Search: include or exclude industries or whole industry groups. Example: `{"filters":{"company_industry":{"include":["Software Development","IT Services & IT Consulting"],"exclude":["Staffing & Recruiting"]}}}`
    - `include` (string[], optional): Industries or industry GROUPS to match (any of). A group name matches every industry in that category. See GET /v2/enums/industries for both. Example: `["Agriculture & Mining","Software Development"]`
    - `exclude` (string[], optional): Industries or industry GROUPS to reject. A group name rejects every industry in that category. See GET /v2/enums/industries for both.
  - `company_headcount_range` (enum[], optional): Bucketed headcount range of the company (see GET /v2/enums/employee_ranges). 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_country` (object, optional): Filter on the country of the person's company for People Search: include or exclude ISO alpha-2 codes, optionally headquarters only. Example: `{"filters":{"company_country":{"include":["US","CA","GB"],"headquarters_only":true}}}`
    - `include` (string[], optional): Match values in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude.
    - `exclude` (string[], optional): Reject values in this list. 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_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_founded` (object, optional): An inclusive numeric range (`min` / `max`, either optional), used by the People Search company founded-year and headcount filters. Example: `{"filters":{"company_founded":{"min":2015,"max":2023}}}`
    - `min` (number, optional): Lower bound (inclusive). Optional.
    - `max` (number, optional): Upper bound (inclusive). Must be >= min. Optional.
  - `company_headcount_custom` (object, optional): An inclusive numeric range (`min` / `max`, either optional), used by the People Search company founded-year and headcount filters. Example: `{"filters":{"company_headcount_custom":{"min":50,"max":1000}}}`
    - `min` (number, optional): Lower bound (inclusive). Optional.
    - `max` (number, optional): Upper bound (inclusive). Must be >= min. Optional.
  - `company_naics` (object, optional): Include or exclude a list of numeric values, used by the People Search `company_naics` filter. Example: `{"filters":{"company_naics":{"include":[541511,541512]}}}`
    - `include` (number[], optional): Match numeric values in this list - any single value qualifies. Optional - provide include and/or exclude.
    - `exclude` (number[], optional): Reject numeric values in this list. 0-500 items.
  - `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_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"]}}}`
    - `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.
  - `contact_details` (object, optional): Filter for People Search on contact data: email and phone status, and whether your workspace already revealed them. Example: `{"filters":{"contact_details":{"email":{"status":["valid","accept_all"],"revealed":false},"phone":{"status":["found"]}}}}`
    - `email` (object, optional): Email part of the People Search `contact_details` filter: the email status to match and whether your workspace revealed it.
      - `status` (enum[], optional): Contact-level email status (best stored email; valid wins). Match-any: valid (>=1 valid email, or an email your workspace entered for the person), invalid, accept_all, not_found (no stored email and none entered by your workspace). Allowed values: `valid`, `invalid`, `accept_all`, `not_found`.
      - `revealed` (boolean, optional): true = only contacts whose email your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace.
    - `phone` (object, optional): Phone part of the People Search `contact_details` filter: the phone status to match and whether your workspace revealed it.
      - `status` (enum[], optional): Contact-level phone status from our lookup store. Match-any: found (number on file), not_found (looked up, none), unknown (never looked up). Allowed values: `found`, `not_found`, `unknown`.
      - `revealed` (boolean, optional): true = only contacts whose phone your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace.
  - `lists` (object, optional): Filter for People Search on your workspace's saved people: list membership, saved or not, and when they were saved. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager"]},"lists":{"saved":"none"}}}`
    - `include` (string[], optional): Only contacts your workspace saved into these list ids. Max 100 ids, each 1-64 chars.
    - `exclude` (string[], optional): Hide contacts your workspace saved into these list ids. Max 1000 ids, each 1-64 chars.
    - `saved` (enum, optional): any = only contacts your workspace saved, in a list or not; none = only contacts your workspace has not saved; without_list = only contacts your workspace saved but did not file into any list. Allowed values: `any`, `none`, `without_list`.
    - `saved_at` (object, optional): An inclusive date range (ISO 8601 `from` / `to`) for when a person was saved, used by the People Search `lists.saved_at` filter.
      - `from` (string, optional): Saved on/after this date (ISO 8601). Optional.
      - `to` (string, optional): Saved on/before this date (ISO 8601). Optional.
  - `duplicates` (object, optional): Filter for People Search that hides people your workspace already exported through POST /v2/people/export. Example: `{"filters":{"duplicates":{"exclude_exported":true}}}`
    - `exclude_exported` (boolean, optional): true = hide people your workspace already exported through POST /v2/people/export. Exclude-only: it removes rows and never counts as an include condition. Requires an authenticated workspace.
  - `max_person_per_company` (integer, optional, min: 1, max: 100): Cap the number of people returned per company across the whole result set (1-100). A person is counted against the company of the position that matched your company filters, or their current/primary position when no company filter is set. Of the colleagues competing for a company slot, one we hold a valid email for is kept, and your sort decides between them (and picks the representative outright when none of them has one). Results stay in your sort order either way. For result sets above 25000 matches the representative is simply whoever leads your sort, and total_count is a rounded PRE-cap estimate (pagination.total_is_estimate=true) - an upper bound, so an export of that selection returns fewer people. At or below it both are exact. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager"]},"max_person_per_company":2}}`
- `sort_by` (enum, optional): Sort key. Omit for the default: followers desc. Sorting applies when the result set is under 500,000 people; larger result sets fall back to the default order. Allowed values: `person_first_name`, `person_last_name`, `person_seniority`, `company_employee_count`, `company_name`, `company_industry`, `person_country`, `company_founded`, `person_email_available`, `person_job_title`, `company_country`, `company_type`, `company_business_type`, `company_revenue_stream`, `person_saved_at`.
- `sort_direction` (enum, optional): Sort direction. Per-key defaults apply; ignored when sort_by is omitted. Allowed values: `asc`, `desc`.
- `limit` (number, optional, min: 1, max: 25000): With `filters`: how many people at most.
- `exclude_ids` (string[], optional): With `filters`: person ids taken out of the match.
- `extra_ids` (string[], optional): With `filters`: hand-ticked person ids outside the match, added to it.
- `list_ids` (string[], required): The people lists the selection ends up in, exactly (1-100).

## Example request

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/people/lists/set \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "ids": [
    "65a1b2c3d4e5f6a7b8c9d0e1",
    "65a1b2c3d4e5f6a7b8c9d0e2",
    "65a1b2c3d4e5f6a7b8c9d0e3"
  ],
  "list_ids": [
    "66f1a2b3c4d5e6f7a8b9c0d1",
    "66f1a2b3c4d5e6f7a8b9c0e7"
  ]
}
'
```

## Response 200

Done inline: the `done` job.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2d4e5f6a7b8c9d0e1",
    "type": "people_lists_set",
    "status": "done",
    "total": 3,
    "processed": 3,
    "progress_percent": 100,
    "result": {
      "updated": 3,
      "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": "people_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.