# People Search `POST https://api.getprospect.com/v2/people/search` Search our people database by who a person is, what they do and where they work. Combine person filters (name, location), job filters (title, seniority, department, tenure, recent job change) and company filters (industry, headcount, location, keywords and more): filters AND together, and at least one include condition is required. Searching is free and every result reports email availability; set enrich_email or enrich_phone to reveal contact data for credits. Results return 25 per page by default (per_page: 25, 50 or 100), sorted by followers desc by default - see the body parameters below for every filter and its nuances. Every position is a current one and carries its start_date (YYYY-MM, LinkedIn month precision). Authenticate with your API key in the x-api-key header. > **How are credits spent?** > > Searching is free. Setting `enrich_email: true` also reveals each result's > email, which costs 1 email credit per revealed email. Results always > include `has_email` and `email_status` for free. ## How filtering works Send one `filters` object. Every filter is optional, but at least one `include` condition is required, and a request can carry at most 20,000 filter values in total. Most filters share the same shape - an `include` list ("match any of these") and an `exclude` list ("reject these") - and all active filters combine with AND: - **Person filters** describe the person themselves: `person` (by `id`, by `name`, or by `linkedin_url`), `person_location`, and free-text `company_keywords` matched against the company the person works at. - **Job filters** describe what they do: `person_job_title` (structured include/exclude or a `boolean_search` expression), `person_seniority`, `person_department`, tenure (`person_months_in_current_role`, `person_months_in_current_company`), and `person_job_change`. - **Company filters** (`company`, `company_industry`, `company_country`, `company_location`, `company_headcount_range`, and the rest) describe the company of the job being matched. ### Matching a person `person.name` matches when **every word** of your term appears somewhere in the person's name, in any order. `"Dmytro Shulha"` finds `Dmytro Shulha, PhD`; `"Helena Calero"` finds `Helena Montoya-Calero`; `"Shulha Dmytro"` finds the same people as `"Dmytro Shulha"`. Matching is case-insensitive, and diacritics are significant - `Jose` does not match `José`. `person.id` matches exactly the people you name, using the `id` from search results, enrichment, or [Search Suggestions](https://getprospect.com/api-docs/search-suggestions.md). The two OR together: a request carrying both returns everyone matching either, and that set is then narrowed by every other filter. That is what lets a picker mix people chosen from a typeahead with names typed as free text. `company_keywords` searches company specialties only by default (`sources: ["specialties"]`) - deliberately narrower than Company Search, which searches every text source unless scoped. Widen it with `sources` (see [Enums](https://getprospect.com/api-docs/enums.md) for the full list); the broader sources match far more companies. A keyword that resolves to more than 50,000 companies is rejected with a 400 rather than silently truncated - use a more specific phrase, or add `company_industry`, `company_headcount_range` or `company_country` to the same request: those narrow the company resolution too, not just the final result set. To see which values a keyword accepts, query [Search Suggestions](https://getprospect.com/api-docs/search-suggestions.md) with `type: "company_keywords"`. Job and company filters must all match **the same position**: a person is returned only when one of their jobs satisfies every job and company condition at once. Filtering by CTO titles plus the Retail industry finds CTOs of retail companies - not a bank's CTO who once held a retail job. Enum-backed filters only accept values from [Enums](https://getprospect.com/api-docs/enums.md); each parameter below links to its own value list. ## Looking up people by LinkedIn URL `person.linkedin_url` takes 1-50 profile URLs and returns the people behind them. Every other filter in the same request still applies and narrows that set - for example, add `contact_details.email.status: ["valid"]` to keep only the profiles with a valid email on file. Two rules are specific to this filter: - `company.name.include` does not narrow the results. It picks which of a person's positions is returned as `primary_position` (`company.name.exclude` still filters). When another job or company filter matched a specific position, that position is returned instead. - Combining it with `person.id` or `person.name` is rejected with a `400`. Results keep the order of the URLs you sent (`sort_by` does not apply), and URLs that match nobody are skipped. Each result carries `matched_url`, the URL from your request it was found by. Map results back by it: the response's `linkedin_url` is the person's canonical profile URL and can differ from the one you sent. ## Sorting and pagination Results come back 25 per page by default; set `per_page` to `50` or `100` for bigger pages (not together with `enrich_email` or `enrich_phone`). A search reaches 25,000 results at any page size: page 1000 at 25, page 250 at 100. The default order is follower count, descending. `company_keywords` does not change it: the filter resolves to a set of companies and contributes no relevance score, so there is nothing for a relevance sort to rank by. Override the default with `sort_by` and `sort_direction`. Explicit sorting applies while the result set stays under 500,000 people - above that, the search falls back to the default order. See [Pagination](https://getprospect.com/api-docs/pagination.md) for the response envelope and paging patterns. ## Authentication Pass your API key in the `x-api-key` header. ## Body parameters - `filters` (object, required): Filter configuration. Active filters AND together and at least one include condition is required. Job filters (person_job_title, person_seniority, person_department, tenure) and company filters must all match within the same position: a person qualifies only when one of their jobs satisfies every one of them at once. A request can carry at most 20,000 filter values in total. See GET /v2/enums for allowed values per enum filter. - `person` (object, optional): Match the person themselves, by id, by name, or by LinkedIn URL. `id` and `name` are OR-ed with each other - a person matching either is returned - and the result AND-s with every other filter, so a picked person and a typed name can sit side by side in one request. `linkedin_url` looks up specific profiles and cannot be combined with the other two. Example: `{"filters":{"person":{"name":{"include":["Dmytro Shulha"]}}}}` - `id` (object, optional): Match by person id. - `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): Match by 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): Look up specific profiles by URL. - `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): Person location filter. Unified location strings resolved to country / state / city. 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): Free-text keyword match against the person's COMPANY (see GET /v2/enums/keywords_sources). Defaults to the `specialties` source only - the broader text sources match far more companies and are much likelier to exceed the resolution limit. Use POST /v2/search/suggest with `type: "company_keywords"` for accepted values. Does NOT affect ordering: this resolves to a company-id filter and contributes no relevance score. 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): Job title match. Structured include/exclude + match_mode (CONTAINS/EXACT), or a boolean_search expression. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager","Growth Marketing Manager"],"exclude":["Assistant"],"match_mode":"CONTAINS"}}}` or `{"filters":{"person_job_title":{"boolean_search":"(CEO OR CTO) AND !Intern"}}}` - `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, default: "CONTAINS"): 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): 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): Seniority (see 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): Department (see GET /v2/enums/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): Months in the current role (tenure of the active position). Integer months 0-600. Example: `{"filters":{"person_months_in_current_role":{"min":6,"max":24}}}` - `min` (number, optional, min: 0, max: 600): Minimum whole months (inclusive), 0-600. Optional. - `max` (number, optional, min: 0, max: 600): Maximum whole months (inclusive), 0-600, must be >= min. Optional. - `person_months_in_current_company` (object, optional): Months at the current company (tenure since joining). Integer months 0-600. Example: `{"filters":{"person_months_in_current_company":{"min":12}}}` - `min` (number, optional, min: 0, max: 600): Minimum whole months (inclusive), 0-600. Optional. - `max` (number, optional, min: 0, max: 600): Maximum whole months (inclusive), 0-600, must be >= min. Optional. - `person_job_change` (object, optional): Recent job change: 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` (number, 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, default: "any"): 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): Company the person works at - by our company `id`, by `domain`, by `name`, or by LinkedIn numeric `linkedin_id`. Example: `{"filters":{"company":{"name":{"include":["Intercom","Stripe"]}}}}` or `{"filters":{"company":{"id":{"include":["64f1a2b3c4d5e6f7a8b9c0d2"]}}}}` - `id` (object, optional): Match by company id (the `id` returned by Company Search and in People Search results). Composes with every other filter: pair it with person_job_title to narrow a company list down to the roles you want. An exact `company.name` combines with it as OR (people at any listed id or any listed name); `company.domain`, `company_keywords` and a CONTAINS `company.name` AND with it. - `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): Match by company website domain. Resolved to the same company-id constraint as `company.id`, so the two AND together when both are given. Example: `{"filters":{"company":{"domain":{"include":["stripe.com"]}}}}` - `include` (string[], optional): Only people who work at a company on one of these domains, e.g. "stripe.com". Scheme, "www." and any path are stripped. Max 100 items. - `exclude` (string[], optional): Reject people whose company is on one of these domains. - `name` (object, optional): Match by company name - exact by default, or substring with match_mode: CONTAINS. An exact name combines with `company.id` as OR (people at any listed name or any listed id); a CONTAINS name ANDs with it. Beside `person.linkedin_url`, `include` is only a primary-position hint, not a filter (`exclude` still filters). - `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, default: "EXACT"): 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): Only people who work at these LinkedIn companies, by LinkedIn's numeric company id. Composes with every other filter as an AND, including with `company.name` (unlike `company.id`, which ORs with an exact name); from a company URL, enrich the company first (POST /v2/companies/enrich) and filter by the `id` it returns. - `include` (number[], 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` (number[], 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): Industry of the person's company (see GET /v2/enums/industries). 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` (string[], optional): Bucketed headcount range of the company (see GET /v2/enums/employee_ranges). Example: `{"filters":{"company_headcount_range":["51-200","201-500"]}}` - `company_country` (object, optional): Country of the person's company, as ISO alpha-2 codes (GET /v2/enums/countries). Any resolved office country counts by default (headquarters included) - same contract as company_location and as Company Search; see headquarters_only. For city/state-level filtering use company_location. sort_by=company_country always orders by the registered headquarters country, independent of 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): Legal/ownership type of the person's company (see GET /v2/enums/company_types). 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): Audience type of the person's company (see GET /v2/enums/business_types). Values: B2B, B2C, Nonprofit, Unknown. 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): Revenue model of the person's company (see GET /v2/enums/revenue_streams). 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): Founded-year range of the person's company. min/max are inclusive; either may be omitted. 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): Raw headcount range of the person's company. min/max are inclusive; either may be omitted. 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): NAICS codes (numeric) of the person's company. Matches if any code on the company is in the list. 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): Location of the person's company (the matched position's company), as unified location strings - same format as person_location. Any resolved office counts by default; see headquarters_only. 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). - `contact_details` (object, optional): Contact data: email/phone availability and status (global), plus your workspace's reveal state. Example: `{"filters":{"contact_details":{"email":{"status":["valid","accept_all"],"revealed":false},"phone":{"status":["found"]}}}}` - `email` (object, optional): Email availability/quality (global) + your workspace reveal state. - `status` (enum[], optional): Contact-level email status (best stored email; valid wins). Match-any: valid (>=1 valid email), invalid, accept_all, not_found (no stored email). 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 availability (global) + your workspace reveal state. - `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): Your workspace CRM list membership: include/exclude list ids, saved any/none, and saved-at range. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager"]},"lists":{"saved":"none"}}}` or `{"filters":{"lists":{"include":["64f1a2b3c4d5e6f7a8b9c0e5"],"saved_at":{"from":"2026-01-01","to":"2026-06-30"}}}}` - `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): Filter by when the contact was saved into a list (workspace-scoped). - `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): Deduplication against your workspace's history: hide people already exported. 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` (number, 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`. - `page` (number, optional, min: 1, max: 1000, default: 1): Page number, 1-based. The deepest reachable page is 25,000 / per_page: 1,000 at 25, 500 at 50 and 250 at 100 (metadata.pagination.max_page). A result set that runs past it has total_pages clamped to max_page and pagination.truncated=true, while total_count stays the real match count - narrow the filters to reach the rest. - `per_page` (enum, optional, default: 25): Results per page: 25, 50 or 100. Above 25 is not available with enrich_email or enrich_phone. Allowed values: `25`, `50`, `100`. - `enrich_email` (boolean, optional, default: false): When true, reveal each result's stored email and charge 1 credit per revealed email. - `enrich_phone` (boolean, optional, default: false): When true, reveal each result's phone via a live lookup and charge 1 phone credit per result with a LinkedIn URL. Up to 25 lookups per page - slow. ## Example request ```bash curl --request POST \ --url https://api.getprospect.com/v2/people/search \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' \ --data ' { "filters": { "person_job_title": { "include": [ "Product Marketing Manager" ], "match_mode": "CONTAINS" }, "company": { "name": { "include": [ "Intercom" ] } }, "company_location": { "include": [ "United States" ] }, "contact_details": { "email": { "status": [ "valid" ] } } }, "page": 1, "enrich_email": true, "enrich_phone": false } ' ``` ## Response 200 Entity given ```json { "success": true, "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "full_name": "Emily Carter", "first_name": "Emily", "last_name": "Carter", "email": { "status": "valid", "address": "emily.carter.sample@intercom.com", "verified_at": "2026-06-18T09:12:44.000Z", "checked_at": "2026-06-18T09:12:44.000Z", "revealed": true }, "mobile_phone": { "status": "not_requested", "number": null, "revealed": false }, "location": { "city": "San Francisco", "state": "California", "state_code": "CA", "country": "United States", "country_code": "US", "time_zone": "America/Los_Angeles", "time_zone_offset": -7 }, "linkedin_url": "https://linkedin.com/in/emily-carter-sample", "primary_position": { "job_title": "Senior Product Marketing Manager", "seniority": "Senior", "departments": [ "Marketing" ], "company": { "id": "64f1a2b3c4d5e6f7a8b9c0d2", "name": "Intercom", "logo": "https://logos.getprospect.com/64f1a2b3c4d5e6f7a8b9c0d2.jpg", "industry": "Software Development", "keywords": [ "customer messaging", "AI customer service", "help desk software" ], "naics_codes": [ 511210 ], "type": "Privately Held", "business_type": "B2B", "revenue_stream": "Subscriptions / Recurring", "founded": 2011, "employee_count": 900, "employee_range": "501-1000", "location": { "city": "San Francisco", "state": "California", "state_code": "CA", "country": "United States", "country_code": "US", "raw_address": "55 2nd St, San Francisco, CA 94105" }, "other_locations": [ { "city": "Chicago", "state": "Illinois", "state_code": "IL", "country": "United States", "country_code": "US", "raw_address": "222 W Merchandise Mart Plaza, Chicago, IL 60654" }, { "city": "Dublin", "state": null, "state_code": null, "country": "Ireland", "country_code": "IE", "raw_address": "2 Dockland Central, Dublin, Ireland" } ] } }, "other_positions": [ { "job_title": "Product Marketing Lead (Advisor)", "seniority": "Director", "departments": [ "Marketing" ], "company": { "id": "64f1a2b3c4d5e6f7a8b9c0d3", "name": "Northwind Analytics", "domain": "northwindanalytics-sample.com", "logo": "https://logos.getprospect.com/64f1a2b3c4d5e6f7a8b9c0d3.jpg", "industry": "Software Development", "employee_count": 120, "location": { "city": "Austin", "state": "Texas", "state_code": "TX", "country": "United States", "country_code": "US", "raw_address": null } } } ], "saved": null } ], "metadata": { "timestamp": "2026-07-25T14:02:31.000Z", "sort_by": "followers", "sort_direction": "desc", "pagination": { "page": 1, "per_page": 25, "total_pages": 1, "total_count": 1, "total_is_estimate": false } } } ``` ## Response 400 Bad model ## Response 401 Unauthorized user ## Response 402 Insufficiently credits