---
title: "Search for people in bulk"
method: POST
path: "/api/v1/people/search/bulk"
tags: ["People Search"]
---

# Search for people in bulk

`POST /api/v1/people/search/bulk`

## Request

- Base URL: `https://api.scalelist.com`
- URL: `https://api.scalelist.com/api/v1/people/search/bulk`
- Auth: API key in header `x-api-key`

Pull a whole audience across many pages in one call. Returns a task id straight away; results arrive later.

Set `start_page`, and `end_page` to stop at a given page; omit it to pull everything that matches.

• The merged results are POSTed to your `webhook_url` on completion.
• Or poll `GET /people/search/bulk?job_id=<task_id>` whenever you like.

**1 credit per profile found.** Send an `Idempotency-Key` header to make retries safe for 24h.

## Headers

- `idempotency-key` string

## Request body

- object: Webhook + page-span envelope (kept separate from the search filters).
  - `job_titles` string[]: Job titles to match (OR logic). Free text, e.g. ["CTO", "VP of Engineering"].
  - `job_functions` string[]: Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership.
  - `seniority` string[]: Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern.
  - `locations` object[]: Locations with explicit granularity (OR logic). Each entry: { type: "city"|"state"|"country", value, country? }.
    - `type` 'city' | 'state' | 'country', required: Granularity: city | state | country
    - `value` string, required: Location value at the chosen granularity, e.g. "San Francisco", "California", "United States".
    - `country` string: City entries only: the country the city is in, e.g. { type: "city", value: "Toronto", country: "Canada" }. Removes same-name places in other countries ("Toronto" otherwise also matches Trento, Italy).
  - `exclude_locations` object[]: Locations to exclude, same shape as `locations`. Example: "US except California".
    - `type` 'city' | 'state' | 'country', required: Granularity: city | state | country
    - `value` string, required: Location to exclude at the chosen granularity.
  - `industries` string[]: Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ...
  - `company_size` object: Employee count range: { min, max }. Either bound optional.
    - `min` integer: Minimum employee count (inclusive)
    - `max` integer: Maximum employee count (inclusive)
  - `recently_changed_jobs` boolean: Only people whose current role started in roughly the last 3 months. High-intent buying signal.
  - `min_followers` integer: Only people with at least this many LinkedIn followers.
  - `keyword` string: A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead.
  - `keywords` string[]: Free-text keywords, OR logic: a person matches if ANY term appears on their profile.
  - `exclude_keywords` string[]: Free-text keywords to exclude: a person is dropped if any term appears on their profile.
  - `open_to` string[]: Person-level buying signals from their own profile badges, e.g. ["hiring"].
  - `years_in_current_role` object: Years at the current employer: { min, max }. Either bound optional.
    - `min` number: Minimum years (inclusive)
    - `max` number: Maximum years (inclusive)
  - `years_of_experience` object: Total years of professional experience: { min, max }. Either bound optional.
    - `min` number: Minimum years (inclusive)
    - `max` number: Maximum years (inclusive)
  - `skills` string[]: Skills listed on the profile (OR logic), e.g. ["Salesforce", "Python"]. Search results do not show skills.
  - `languages` string[]: Languages the person speaks (OR logic), e.g. ["French", "German"].
  - `schools` string[]: Schools or universities attended (OR logic), e.g. ["Stanford", "HEC Paris"].
  - `certifications` string[]: Certifications held (OR logic), e.g. ["PMP"]. Search results do not show certifications.
  - `companies` string[]: Company names (OR logic), e.g. ["Salesforce", "HubSpot"].
  - `company_domains` string[]: Company domains (OR logic), e.g. ["stripe.com"].
  - `past_companies` string[]: Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role.
  - `past_job_titles` string[]: Job titles held in a past role (OR logic), e.g. ["Founder"]. With past_companies / past_seniority, all must hold for the SAME past role.
  - `past_seniority` string[]: Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training.
  - `company_hq_countries` string[]: Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. ["Germany", "USA"].
  - `company_type` string[]: Company category filter, e.g. ["public company"] or ["non-profit"] (OR logic).
  - `exclude_job_titles` string[]: Job titles to exclude from results.
  - `exclude_companies` string[]: Company names to exclude from results.
  - `exclude_company_domains` string[]: Company websites to exclude from results, e.g. ["stripe.com"].
  - `exclude_industries` string[]: Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422.
  - `exclude_seniority` string[]: Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training.
  - `exclude_job_functions` string[]: Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422.
  - `exclude_past_companies` string[]: Drop anyone who previously worked at any of these companies, by name.
  - `exclude_past_job_titles` string[]: Drop anyone who held any of these job titles in a past role.
  - `exclude_past_seniority` string[]: Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training.
  - `exclude_company_hq_countries` string[]: Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code.
  - `exclude_skills` string[]: Drop anyone who lists any of these skills.
  - `exclude_languages` string[]: Drop anyone who lists any of these languages.
  - `exclude_schools` string[]: Drop anyone who attended any of these schools.
  - `exclude_certifications` string[]: Drop anyone who holds any of these certifications.
  - `metadata` object, required
    - `webhook_url` string, uri, required: Destination URL for the completion callback
    - `start_page` integer: First page to fetch
    - `end_page` integer: Last page to fetch (optional). When omitted, pages through to the last page sized from the result total.
    - `page_size` integer: Profiles per page (max 100)
    - `skip_first` integer: Skip (and do not bill) the first N profiles of start_page, for resuming a run that stopped mid-page without re-delivering the overlap.
    - `max_results` integer: Deliver (and bill) at most this many profiles across the whole run, trimming the final page, for an exact target instead of a whole-page multiple.
  - `custom` object: Arbitrary metadata echoed back verbatim in the webhook payload and poll response

## Response `202`

Default Response

- object
  - `taskId` string
  - `status` 'queued'
  - `startPage` integer
  - `endPage` integer, nullable

---

[API](https://skmtc.dev/scalelist/apis/scalelist-api.md) · [All operations](https://skmtc.dev/scalelist/apis/scalelist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalelist/apis/scalelist-api/revisions/4863f1805423?raw)