> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blitz-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Find People
# Find People
> Search decision-makers across your entire ICP. Combine company-level filters with person-level filters in a single call.
> **Agents & LLMs**: a Markdown version of this page is available by appending `.md` to the URL, and the full documentation index is at [llms.txt](https://docs.blitz-api.ai/llms.txt).
**API Reference**: [`Find People` endpoint](/api-reference/people-search/find-people) — full request/response schema and try-it console.
The **Find People** endpoint (`POST /v2/search/people`) is the most powerful entry point in the People Search family. Instead of being scoped to a single company (like [Employee Finder](/guide/concepts/employee-finder)) or returning a single best contact (like [Waterfall ICP Search](/guide/concepts/waterfall-logic)), Find People runs a **two-stage match**: it first qualifies companies that fit your ICP, then surfaces the people inside them that match your persona criteria.
It is the right tool to build large, multi-account prospecting lists in one call — without first having to resolve every company URL.
**Paid plans**: Unlimited — included in your flat monthly subscription.
***
## When to Use Find People vs. Other Endpoints
| Use Case | Best Endpoint |
| :----------------------------------------------------------------- | :------------------------------------------------- |
| Build a prospecting list across **many companies** matching an ICP | **Find People** |
| Map *all* employees inside one specific company | [Employee Finder](/guide/concepts/employee-finder) |
| Find the *single best* decision-maker at a known company | [Waterfall ICP](/guide/concepts/waterfall-logic) |
| Combine company filters (industry, size, HQ) with persona filters | **Find People** |
| Iterate through a long result set with stable pagination | **Find People** (cursor-based) |
***
## How It Works
Find People accepts three top-level objects:
1. **`company`** — qualifies the accounts (industry, NAICS/SIC code, employee range, revenue, HQ, type, keywords, founded year, follower count, web traffic, Google ad spend, funding signals — total funding, last round amount/year/type, lead investors — or explicit `linkedin_url` list).
2. **`people`** — qualifies the contacts inside those accounts (job title keywords, job function, job level, location, minimum connections, education).
3. **`max_results`** + **`cursor`** — control how many results come back per call and how you paginate.
The engine evaluates the company filter first, then walks the matching companies and returns people that satisfy the person filter — up to `max_results` per call.
***
## Request Parameters
### Top-Level Parameters
| Parameter | Type | Required | Default | Description |
| :------------ | :------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------- |
| `company` | `object` | No\* | — | Company-level filters. See below. |
| `people` | `object` | No\* | — | Person-level filters. See below. |
| `max_results` | `number` | No | `10` | Results per page. Min: `1`, Max: `50`. |
| `cursor` | `string` | No | `null` | Cursor returned by a previous call. Omit (or pass `null`) for the first call. (Hard limit on the 1,000th page) |
\* You should provide at least one of `company` or `people` — otherwise the search is unbounded and will be rejected.
### `company` Filters
| Field | Type | Description |
| :-------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `linkedin_url` | `array` | Exact LinkedIn company URLs to target. Bypasses other company filters. |
| `name.include` | `array` | Keywords that must appear in the company name. |
| `name.exclude` | `array` | Keywords to exclude from the company name. |
| `industry.include` | `array` | Normalized industry names. Case-sensitive — see [Field Normalization](/guide/reference/normalization/industries). |
| `industry.exclude` | `array` | Industries to exclude. |
| `type.include` | `array` | LinkedIn company type (`Privately Held`, `Public Company`, `Nonprofit`, `Government Agency`, …). |
| `type.exclude` | `array` | Company types to exclude. |
| `employee_range` | `array` | LinkedIn employee buckets: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. |
| `employee_count.min` | `number` | Minimum employee count (numeric). |
| `employee_count.max` | `number` | Maximum employee count (numeric). |
| `min_linkedin_followers` | `number` | Minimum number of LinkedIn followers on the company page. |
| `revenue.min` | `number` | Minimum annual revenue (USD). `0` = unset. |
| `revenue.max` | `number` | Maximum annual revenue (USD). `0` = unset. |
| `naics_code.include` | `array` | Exact NAICS codes the company must match (e.g. `"541511"`). |
| `naics_code.exclude` | `array` | NAICS codes to exclude. |
| `sic_code.include` | `array` | Exact SIC codes the company must match (e.g. `"7372"`). |
| `sic_code.exclude` | `array` | SIC codes to exclude. |
| `web_traffic.min` | `number` | Minimum estimated monthly web visits. `0` = unset. |
| `web_traffic.max` | `number` | Maximum estimated monthly web visits. `0` = unset. |
| `ad_spend.min` | `number` | Minimum estimated monthly Google ad spend (USD). `0` = unset. |
| `ad_spend.max` | `number` | Maximum estimated monthly Google ad spend (USD). `0` = unset. |
| `total_funding.min` | `number` | Minimum total funding raised across all rounds (USD). `0` = unset. |
| `total_funding.max` | `number` | Maximum total funding raised across all rounds (USD). `0` = unset. |
| `last_funding_amount.min` | `number` | Minimum amount raised in the most recent funding round (USD). `0` = unset. |
| `last_funding_amount.max` | `number` | Maximum amount raised in the most recent funding round (USD). `0` = unset. |
| `last_funding_year.min` | `number` | Earliest year of the most recent funding round. `0` = unset. |
| `last_funding_year.max` | `number` | Latest year of the most recent funding round. `0` = unset. |
| `last_funding_type.include` | `array` | Last funding round types to include. Case-sensitive enum — see [Companies → Funding](/guide/reference/normalization/companies#funding). |
| `last_funding_type.exclude` | `array` | Last funding round types to exclude. |
| `lead_investors.include` | `array` | Keywords matched against lead investor names (e.g. `"Sequoia"`). |
| `lead_investors.exclude` | `array` | Lead investor name keywords to exclude. |
| `keywords.include` | `array` | Keywords searched across the company description, specialties, NAICS/SIC descriptions, and Crunchbase/G2 categories. Tokens within a phrase must all match in the same field. |
| `keywords.exclude` | `array` | Phrases to exclude — companies that match in any of the above fields are filtered out. |
| `founded_year.min` | `number` | Earliest founded year. |
| `founded_year.max` | `number` | Latest founded year. |
| `hq.city.include` | `array` | Keywords matched against the HQ city. |
| `hq.city.exclude` | `array` | Keywords to exclude from the HQ city. |
| `hq.country_code` | `array` | HQ country (2-letter ISO codes, e.g., `US`, `FR`). |
| `hq.continent` | `array` | HQ continent. See [accepted values](/guide/reference/normalization/geography#continents). |
| `hq.sales_region` | `array` | HQ sales region: `NORAM`, `LATAM`, `EMEA`, `APAC`. |
### `people` Filters
| Field | Type | Description |
| :-------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_title.include` | `array` | Keywords that must match the job title. |
| `job_title.exclude` | `array` | Keywords to exclude from the job title. |
| `include_linkedin_headline` | `boolean` | If `true`, `job_title` keywords also match the LinkedIn headline (not just the formal job title). Default: `false`. |
| `job_function` | `array` | Department / function. Case-sensitive enum — see [Field Normalization](/guide/reference/normalization/job-levels#job-functions). |
| `job_level` | `array` | Seniority: `C-Team`, `VP`, `Director`, `Manager`, `Staff`, `Other`. |
| `min_connections` | `number` | Minimum LinkedIn connections (0–500). Useful to filter out inactive profiles. |
| `location.city` | `array` | Cities the person is based in. |
| `location.country_code` | `array` | Person country (2-letter ISO codes). |
| `location.continent` | `array` | Person continent. |
| `location.sales_region` | `array` | Person sales region: `NORAM`, `LATAM`, `EMEA`, `APAC`. |
| `education.include` | `array` | Phrases matched against the person's education entries. Tokens within a phrase must co-occur in the same entry — wrap the year in the phrase (e.g. `"Stanford 2025"`) to correlate school and year. Token order does not matter (`"Stanford CS"` matches `"CS Stanford"`). |
| `education.exclude` | `array` | Phrases to exclude — people with an education entry matching one of these phrases are filtered out. |
All enum values (`industry`, `type`, `employee_range`, `last_funding_type`, `job_level`, `job_function`, `continent`, `sales_region`) are **case-sensitive**. Passing `"vp"` instead of `"VP"` or `"sales"` instead of `"Sales & Business Development"` will silently return 0 results. Copy-paste from the [Field Normalization reference](/guide/reference/normalization).
***
## Example Request
Find VPs and Directors of Sales at IT Services companies between 51 and 500 employees, headquartered in EMEA:
```json cURL theme={null}
curl -X POST "https://api.blitz-api.ai/v2/search/people" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"company": {
"industry": { "include": ["IT Services and IT Consulting"] },
"employee_range": ["51-200", "201-500"],
"hq": { "sales_region": ["EMEA"] }
},
"people": {
"job_level": ["VP", "Director"],
"job_function": ["Sales & Business Development"],
"min_connections": 200
},
"max_results": 25
}'
```
```javascript Node.js theme={null}
const people = await client.search.people({
company: {
industry: { include: ["IT Services and IT Consulting"] },
employee_range: ["51-200", "201-500"],
hq: { sales_region: ["EMEA"] },
},
people: {
job_level: ["VP", "Director"],
job_function: ["Sales & Business Development"],
min_connections: 200,
},
max_results: 25,
});
for (const person of people.data) {
console.log(`${person.full_name} — ${person.headline}`);
console.log(` LinkedIn: ${person.linkedin_url}`);
}
```
```python Python theme={null}
people = client.search.people(
company={
"industry": {"include": ["IT Services and IT Consulting"]},
"employee_range": ["51-200", "201-500"],
"hq": {"sales_region": ["EMEA"]},
},
people={
"job_level": ["VP", "Director"],
"job_function": ["Sales & Business Development"],
"min_connections": 200,
},
max_results=25,
)
for person in people.results:
print(f"{person.full_name} — {person.headline}")
print(f" LinkedIn: {person.linkedin_url}")
```
***
## Response Schema
The JSON below is the **raw HTTP response**. The SDKs wrap this page and expose its items under a language-specific property — in the examples above, `people.data` (TypeScript/Node.js) and `people.results` (Python) refer to the same `results[]` array shown here. See [Page object shape](/sdks/pagination#page-object-shape) for the full mapping.
```json theme={null}
{
"total_results": 100,
"results_length": 25,
"max_results": 25,
"cursor": "eyJvZmZzZXQiOjI1fQ==",
"results": [
{
"first_name": "Jane",
"last_name": "Doe",
"full_name": "Jane Doe",
"nickname": null,
"civility_title": null,
"headline": "VP of Sales at Acme",
"about_me": "Experienced sales leader...",
"location": {
"city": "Paris",
"state_code": null,
"country_code": "FR",
"continent": "Europe"
},
"linkedin_url": "https://www.linkedin.com/in/janedoe",
"connections_count": 2500,
"profile_picture_url": "https://media.licdn.com/...",
"experiences": [
{
"job_title": "VP of Sales",
"company_linkedin_url": "https://www.linkedin.com/company/acme",
"company_linkedin_id": "c51425c5-1b38-578d-a700-c5ca850261ae",
"job_description": "Leading the EMEA sales team...",
"job_start_date": "2024-01-15",
"job_end_date": null,
"job_is_current": true,
"job_location": {
"city": "Paris",
"state_code": null,
"country_code": "FR"
}
}
],
"education": [],
"skills": ["Sales Strategy", "B2B", "SaaS"],
"certifications": []
}
]
}
```
### Top-Level Response Fields
| Field | Type | Description | |
| :--------------- | :------- | :------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `total_results` | `number` | Total number of people matching the filters across all pages. | |
| `results_length` | `number` | Number of results on this page. | |
| `max_results` | `number` | The `max_results` value you sent. | |
| `cursor` | \`string | null\` | Pass this back as `cursor` to fetch the next page. `null` means there are no more results. |
| `results` | `array` | Array of person profiles (same shape as Employee Finder). | |
The person object (`results[]`) is identical to [Employee Finder](/guide/concepts/employee-finder#person-fields-results) — same `experiences`, `education`, `skills`, and `certifications` structures. Person fields are returned **directly** in `results[]`, not nested in `.person`.
**Cursor vs. page**: Find People uses **cursor-based** pagination, while Employee Finder uses **page-based** pagination. Cursors are stable even if new profiles are added between calls — you will not see duplicates.
***
## Pagination
Find People uses cursor-based pagination. With the SDK you don't manage cursors — iterate the returned page and it fetches each subsequent page for you.
```javascript theme={null}
// Stream every match across all pages.
for await (const person of client.search.people({
company: {
industry: { include: ["IT Services and IT Consulting"] },
hq: { sales_region: ["EMEA"] },
},
people: {
job_level: ["VP", "Director"],
job_function: ["Sales & Business Development"],
},
max_results: 50,
})) {
console.log(`${person.full_name} — ${person.headline}`);
}
```
Pagination is limited to 1k pages. Maximum to 50k results
***
## Combining with Enrichment
Find People returns LinkedIn profile URLs but **not** emails or phone numbers. Chain with enrichment endpoints to complete the data:
Use Find People to get `linkedin_url` for each matching person across the ICP.
Pass each `linkedin_url` to `POST /v2/enrichment/email` to get verified work emails.
Pass each `linkedin_url` to `POST /v2/enrichment/phone` for direct mobile numbers.
Map the enriched payload to your CRM fields and sync.
Need every employee at *one* company? Use Employee Finder.
Need the *single best* contact at a known account? Use Waterfall.
Want only the company list (no people)? Use Company Search.
Accepted values for industry, job\_level, job\_function, sales\_region…