Set People Lists

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.

Body parameters

• idsstring[]optional

  contacts-v2 person ids (1-25000). Exactly one of ids and filters.

• filtersobjectoptional

  The People Search filter set, also taken by the whole-search save, enrich and credits preview.

  Child attributes

  • personobjectoptional

    Filter on the person themselves for People Search: by GetProspect person id, by name, or a lookup of specific profiles by LinkedIn URL.

    Child attributes

    • idobjectoptional

      Filter on GetProspect person ids for People Search: only these people, or reject them (up to 100 ids each).

      Field	Type	Description
      include	string[]	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[]	Reject these people (same id values). Max 100 ids.

    • nameobjectoptional

      Filter on the person's name for People Search: include or exclude names, each term matching when all its words appear in the name.

      Field	Type	Description
      include	string[]	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[]	Names to reject, matched the same way. Max 500 items.

    • linkedin_urlobjectoptional

      Lookup of specific people for People Search by LinkedIn profile URL (1-50); the other filters narrow the result.

      Field	Type	Description
      include	string[]	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"]

    Example

    {
      "filters": {
        "person": {
          "name": {
            "include": [
              "Dmytro Shulha"
            ]
          }
        }
      }
    }

  • person_locationobjectoptional

    Include/exclude filter on unified location strings (country, state, city or region), used by People Search person_location.

    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.

    Example

    {
      "filters": {
        "person_location": {
          "include": [
            "California, United States",
            "Austin, Texas, United States"
          ],
          "exclude": [
            "San Francisco, California, United States"
          ]
        }
      }
    }

  • 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": [
            "email marketing"
          ],
          "sources": [
            "specialties"
          ]
        }
      }
    }

  • person_job_titleobjectoptional

    Filter on the person's job title for People Search: include or exclude titles matched per match_mode, or one boolean_search expression instead.

    Field	Type	Description
    include	string[]	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[]	Job titles to reject. Max 100 items, each 2-100 chars.
    match_mode	enum	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	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. max length: 20000.

    Example

    {
      "filters": {
        "person_job_title": {
          "include": [
            "Product Marketing Manager",
            "Growth Marketing Manager"
          ],
          "exclude": [
            "Assistant"
          ],
          "match_mode": "CONTAINS"
        }
      }
    }

  • person_seniorityobjectoptional

    Filter on the seniority level of the person's position for People Search: include or exclude values from Seniorities.

    Field	Type	Description
    include	enum[]	Seniority levels to match (any of). See Seniorities.
    exclude	enum[]	Seniority levels to reject. See Seniorities.

    Example

    {
      "filters": {
        "person_seniority": {
          "include": [
            "Chief Officer",
            "VP",
            "Director"
          ]
        }
      }
    }

  • person_departmentobjectoptional

    Filter on the department of the person's position for People Search: include or exclude department groups or sub-departments.

    Field	Type	Description
    include	enum[]	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 Departments.
    exclude	enum[]	Departments to reject. A group rejects everyone in it; a sub-department rejects only that sub-department. See Departments.

    Example

    {
      "filters": {
        "person_department": {
          "include": [
            "Marketing",
            "Sales"
          ],
          "exclude": [
            "Accounting"
          ]
        }
      }
    }

  • person_months_in_current_roleobjectoptional

    An inclusive range of whole months (0-600), used by the People Search tenure filters for the current role and the current company.

    Field	Type	Description
    min	integer	Minimum whole months (inclusive), 0-600. Optional. min: 0, max: 600.
    max	integer	Maximum whole months (inclusive), 0-600, must be >= min. Optional. min: 0, max: 600.

    Example

    {
      "filters": {
        "person_months_in_current_role": {
          "min": 6,
          "max": 24
        }
      }
    }

  • person_months_in_current_companyobjectoptional

    An inclusive range of whole months (0-600), used by the People Search tenure filters for the current role and the current company.

    Field	Type	Description
    min	integer	Minimum whole months (inclusive), 0-600. Optional. min: 0, max: 600.
    max	integer	Maximum whole months (inclusive), 0-600, must be >= min. Optional. min: 0, max: 600.

    Example

    {
      "filters": {
        "person_months_in_current_company": {
          "min": 12
        }
      }
    }

  • person_job_changeobjectoptional

    Filter for People Search on a recent job change: the current role started within timeframe_months, optionally narrowed by change_type.

    Field	Type	Description
    timeframe_months	integerrequired	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. min: 1, max: 1000. Example: 3
    change_type	enum	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

    Example

    {
      "filters": {
        "person_job_change": {
          "timeframe_months": 3,
          "change_type": "new_company"
        }
      }
    }

  • companyobjectoptional

    Filter on the person's company for People Search: by company id, website domain, name or LinkedIn company id.

    Child attributes

    • idobjectoptional

      Filter on the person's company for People Search by GetProspect company id: include or exclude companies.

      Field	Type	Description
      include	string[]	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[]	Reject people who work at any of these companies (same id values). Max 20000 ids.

    • domainobjectoptional

      Filter on the person's company for People Search by website domain: include or exclude domains, with match_mode for which company pages count.

      Field	Type	Description
      include	string[]	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[]	Reject people whose company is on one of these domains.
      match_mode	enum	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

      Example

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

    • nameobjectoptional

      Filter on the person's company for People Search by name: include or exclude names, matched exactly or as a substring per match_mode.

      Field	Type	Description
      include	string[]	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[]	Company names to reject. With EXACT, a website-shaped value also rejects the company on that domain.
      match_mode	enum	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_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": {
          "name": {
            "include": [
              "Intercom",
              "Stripe"
            ]
          }
        }
      }
    }

  • company_industryobjectoptional

    Filter on the industry of the person's company for People Search: include or exclude industries or whole industry groups.

    Field	Type	Description
    include	string[]	Industries or industry GROUPS to match (any of). A group name matches every industry in that category. See Industries for both. Example: ["Agriculture & Mining","Software Development"]
    exclude	string[]	Industries or industry GROUPS to reject. A group name rejects every industry in that category. See Industries for both.

    Example

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

  • company_headcount_rangeenum[]optional

    Bucketed headcount range of the company (see Employee ranges).

    Example

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

  • company_countryobjectoptional

    Filter on the country of the person's company for People Search: include or exclude ISO alpha-2 codes, optionally headquarters only.

    Field	Type	Description
    include	string[]	Match values in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude.
    exclude	string[]	Reject values in this list. 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",
            "GB"
          ],
          "headquarters_only": true
        }
      }
    }

  • 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"
          ]
        }
      }
    }

  • 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_foundedobjectoptional

    An inclusive numeric range (min / max, either optional), used by the People Search company founded-year and headcount filters.

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

    Example

    {
      "filters": {
        "company_founded": {
          "min": 2015,
          "max": 2023
        }
      }
    }

  • company_headcount_customobjectoptional

    An inclusive numeric range (min / max, either optional), used by the People Search company founded-year and headcount filters.

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

    Example

    {
      "filters": {
        "company_headcount_custom": {
          "min": 50,
          "max": 1000
        }
      }
    }

  • company_naicsobjectoptional

    Include or exclude a list of numeric values, used by the People Search company_naics filter.

    Field	Type	Description
    include	number[]	Match numeric values in this list - any single value qualifies. Optional - provide include and/or exclude.
    exclude	number[]	Reject numeric values in this list. 0-500 items.

    Example

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

  • 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_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"
          ]
        }
      }
    }

  • 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"
          ]
        }
      }
    }

  • contact_detailsobjectoptional

    Filter for People Search on contact data: email and phone status, and whether your workspace already revealed them.

    Child attributes

    • emailobjectoptional

      Email part of the People Search contact_details filter: the email status to match and whether your workspace revealed it.

      Field	Type	Description
      status	enum[]	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	true = only contacts whose email your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace.

    • phoneobjectoptional

      Phone part of the People Search contact_details filter: the phone status to match and whether your workspace revealed it.

      Field	Type	Description
      status	enum[]	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	true = only contacts whose phone your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace.

    Example

    {
      "filters": {
        "contact_details": {
          "email": {
            "status": [
              "valid",
              "accept_all"
            ],
            "revealed": false
          },
          "phone": {
            "status": [
              "found"
            ]
          }
        }
      }
    }

  • listsobjectoptional

    Filter for People Search on your workspace's saved people: list membership, saved or not, and when they were saved.

    Child attributes

    • includestring[]optional

      Only contacts your workspace saved into these list ids. Max 100 ids, each 1-64 chars.

    • excludestring[]optional

      Hide contacts your workspace saved into these list ids. Max 1000 ids, each 1-64 chars.

    • savedenumoptional

      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_atobjectoptional

      An inclusive date range (ISO 8601 from / to) for when a person was saved, used by the People Search lists.saved_at filter.

      Field	Type	Description
      from	string	Saved on/after this date (ISO 8601). Optional.
      to	string	Saved on/before this date (ISO 8601). Optional.

    Example

    {
      "filters": {
        "person_job_title": {
          "include": [
            "Product Marketing Manager"
          ]
        },
        "lists": {
          "saved": "none"
        }
      }
    }

  • duplicatesobjectoptional

    Filter for People Search that hides people your workspace already exported through POST /v2/people/export.

    Field	Type	Description
    exclude_exported	boolean	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.

    Example

    {
      "filters": {
        "duplicates": {
          "exclude_exported": true
        }
      }
    }

  • max_person_per_companyintegeroptionalmin: 1max: 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_byenumoptional

  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_directionenumoptional

  Sort direction. Per-key defaults apply; ignored when sort_by is omitted.

  Allowed values: asc desc

• limitnumberoptionalmin: 1max: 25000

  With filters: how many people at most.

• exclude_idsstring[]optional

  With filters: person ids taken out of the match.

• extra_idsstring[]optional

  With filters: hand-ticked person ids outside the match, added to it.

• list_idsstring[]required

  The people 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.