# Smart Job Titles `POST https://api.getprospect.com/v2/search/smart-job-titles` AI-suggested job titles that reach more of the people your titles are meant to find: other ways the same role is written (synonyms, abbreviations, plurals, translations into the languages of your locations), closely related roles, and broader roles in the same function. Each title carries the narrowest `smart_level` that includes it (SAME_ROLE, SIMILAR, RELATED) and `new_people`: how many people it adds to the search you describe in `filters`. Titles that add nobody - a variant your own titles already match, or a title nobody in your search holds - are left out, and so are titles adding fewer than 0.1% of your search (at most 100 people). Search the titles you keep with CONTAINS; `person_job_title.match_mode: SMART` does the same server-side but, having no counts, keeps every AI title, so it can find a few more people. Free: costs no credits. A new answer uses one of the workspace's daily AI suggestions (by plan); the same titles and filters again are answered from cache for free. Counts against the per-second window of the search rate limit (0 units). Authenticate with your API key in the x-api-key header. > **How are credits spent?** > > Smart Job Titles is free and consumes no credits. A new AI answer uses one > of your workspace's daily AI suggestions (see Daily AI allowance below); > asking again for the same titles and filters is answered from cache and > uses nothing. ## What it does Send the job titles you would search with, and the AI suggests the other titles the same people hold on their profiles, so a [People Search](https://getprospect.com/api-docs/people-search.md) reaches more of the right people: - other ways to write the same role: synonyms, abbreviations, plurals and translations into the languages of your locations (`Germany` brings `Leiter Einkauf` for "Head of Procurement"); - closely related roles of the same function and level; - broader roles in the same function. Pass the People Search `filters` you will search with. Locations decide which languages the suggestions come in; industry, seniority and department sharpen what the AI reads into your titles; and every filter scopes the counts. `person_job_title` inside `filters` is ignored apart from its `exclude`, which is used when `exclude_job_titles` is absent. You can use the answer two ways: - show the titles to a user, let them pick, and search the picked ones with `person_job_title.match_mode: "CONTAINS"`; - or skip this call and send `match_mode: "SMART"` to People Search, which adds the titles itself (see Smart match mode in People Search below). ## Three levels Every title carries `level`, the narrowest level that includes it. The levels are nested: `SAME_ROLE` < `SIMILAR` < `RELATED`. | Level | In the App | Adds | Example | | --- | --- | --- | --- | | `SAME_ROLE` | Same role | Other ways to write the same role: synonyms, abbreviations, plurals, translations | VP of Sales -> Sales VP | | `SIMILAR` (default) | Similar | Also closely related roles of the same function and level | Head of Sales -> Sales Director | | `RELATED` | Related | Also broader roles in the same function | SDR -> Account Executive | One call answers all three levels. To show a level, keep the titles whose `level` is at or below it; switching levels needs no new request. ## Reading the counts - **`new_people`** - how many people the title adds on top of your own titles, under your `filters` and after every exclusion. Each title is counted on its own, so the numbers overlap and do not add up to the total. `null` when the count could not be taken. - **Titles that add nobody are left out.** A variant your own titles already match (CONTAINS matches every word in any order, so "Founder & CEO" adds no one when "CEO" is listed), or a title too few people in your search hold, is not returned. `titles` can be empty: that is still a `200`. - `titles` is ordered by level, then by `new_people`, most first. ## Exclusions `exclude_titles` lists other spellings of the roles you exclude ("Intern" -> "Trainee", "Praktikant"), each with `removed_people`: how many people excluding it takes out of your search. They are same-role spellings only, whatever the level, and are empty without exclusions of your own. An exclusion can show `removed_people: 0` and still be worth keeping. Job title filters apply **per position**: a person matches when one of their positions has an included title and no excluded one. A spelling of a role you did not include rarely removes anyone from today's search, but it keeps that role out once your include list widens. That is why every spelling is returned, even at 0. Nothing your exclusions reject is ever suggested in `titles`. ## Smart match mode in People Search People Search does the same work when you send `match_mode: "SMART"`: ```json POST /v2/people/search { "filters": { "person_job_title": { "include": ["Head of Sales"], "exclude": ["Intern"], "match_mode": "SMART", "smart_level": "SIMILAR" } } } ``` The AI titles at or below `smart_level` are added to `include`, the other spellings of the excluded roles to `exclude`, and the filter then runs as CONTAINS. Search, count, save, enrich and export all match the same people. `metadata.smart_job_titles` lists what was added, without counts. See [People Search](https://getprospect.com/api-docs/people-search.md) (Smart job-title match) for the response shape. ## Caching - An AI answer is cached for **30 days** and shared by every workspace: the same titles, exclusions and context (locations, industries, seniorities, departments) are answered from cache. Case and order do not matter. - The counts are cached for an hour per workspace. - `metadata.cached` is `true` when the answer came from cache. A cached answer is free and does not use your daily allowance. ## Daily AI allowance Only a new AI answer (one not in the cache) uses the workspace's daily allowance. It resets at 00:00 UTC, and a call that fails is not counted. The allowance follows the same plan tiers as [Rate limits](https://getprospect.com/api-docs/credits-and-limits.md): | Plan | New AI answers per day | | --- | --- | | Free | 30 | | Starter | 200 | | Growth 5K | 500 | | Growth 20K | 1,000 | | Growth 50K and above | 2,000 | When it is used up, a request that needs a new answer gets `429` with the error name `RATE_LIMIT` and `payload.code: "ai_daily_limit"`. Cached answers keep working, and People Search with `match_mode: "SMART"` answers the same `429` when it needs a new answer. Search with `match_mode: "CONTAINS"` until the reset. The endpoint also counts against the per-second window of the `search` rate limit, at 0 units: it never spends your per-minute or per-day search units. ## Errors | Status | Error | When | | --- | --- | --- | | `400` | `VALIDATION_ERROR` | `job_titles` is empty or has more than 20 items, a title is shorter than 2 or longer than 100 characters, or `filters` that People Search itself would refuse. | | `429` | `RATE_LIMIT` with `payload.code: "ai_daily_limit"` | The daily AI allowance is used up. | | `429` | `RATE_LIMIT` | The per-second window of the `search` rate limit; wait `Retry-After` seconds. | | `503` | `UNAVAILABLE` | The AI could not answer right now. Retry shortly, or search with `match_mode: "CONTAINS"`. | In People Search, the AI being unavailable never fails the search: it runs on your own titles and `metadata.smart_job_titles.error` is `"unavailable"`. ## Authentication Pass your API key in the `x-api-key` header. ## Body parameters - `job_titles` (string[], required): Your own job-title terms (what you would send as person_job_title.include). 1-20 items, 2-100 characters each. Example: `{"job_titles":["Head of Sales"]}` - `exclude_job_titles` (string[], optional): Your own excluded job-title terms (person_job_title.exclude). Nothing they reject is suggested, and `exclude_titles` answers their other spellings ("Intern" -> "Trainee", "Praktikant"). Up to 20 items, 2-100 characters each. Absent: the exclude inside `filters`. Example: `{"job_titles":["Head of Sales"],"exclude_job_titles":["Intern"]}` - `filters` (object, optional): The People Search filters you will search with (same shape as POST /v2/people/search `filters`). Locations decide which languages the suggestions come in, industry, seniority and department sharpen the intent, and every filter scopes the counts. `person_job_title` in here is ignored apart from its `exclude` (used when `exclude_job_titles` is absent). - `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://www.linkedin.com/in/emily-carter-sample/"]` - `person_location` (object, optional): Where the person is based (their profile location), not their employer - for the company HQ use company_location with headquarters_only: true. Unified location strings resolved to country / state / city, or a region (Europe, EMEA, APAC...); a region minus a country is include ["Europe"], exclude ["Germany"]. Example: `{"filters":{"person_location":{"include":["Europe"],"exclude":["Germany"]}}}` - `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. Any value that does not resolve fails the whole request with 400 (`invalid_value`, naming it in `invalid_values`), even beside values that do: nothing is silently dropped. Look values up with POST /v2/search/suggest (type location). - `exclude` (string[], optional): Reject these locations (same unified-string format; a region minus a country works: include ["Europe"], exclude ["Germany"]). Max 100 items, each 2-200 chars. A value that does not resolve is skipped, so check the spelling: a misspelled exclude ("Germny") leaves that place in the results. - `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/SMART), or a boolean_search expression. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager","Growth Marketing Manager"],"exclude":["Assistant"],"match_mode":"CONTAINS"}}}` - `include` (string[], optional): Job titles to match. Max 100 items, each 2-100 chars. Combined per match_mode. Known abbreviations also match their canonical spelling and vice versa (e.g. "CEO" matches "Chief Executive Officer"), however you spell them - "VP of Marketing", "VP, Marketing" and "Marketing VP" all match what "VP Marketing" matches. Under CONTAINS, terms match any of the roles a position carries - including the secondary roles of combined titles like "Founder & CEO" and the original title text. - `exclude` (string[], optional): Job titles to reject. Max 100 items, each 2-100 chars. - `match_mode` (enum, optional, 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. SMART = CONTAINS plus AI-suggested titles the same people hold (synonyms, translations for your locations, related roles - see smart_level), and `exclude` widened with the other spellings of the excluded roles ("Intern" also excludes "Trainee", "Praktikant"); what was added is listed in `metadata.smart_job_titles`, and POST /v2/search/smart-job-titles previews them with how many people each adds. Applies to include/exclude; ignored when boolean_search is set. Allowed values: `CONTAINS`, `EXACT`, `SMART`. - `smart_level` (enum, optional, default: "SIMILAR"): How far match_mode SMART reaches. SAME_ROLE = other ways to write the same role (synonyms, abbreviations, plurals, translations): "VP of Sales" -> "Sales VP". SIMILAR (default) = also closely related roles of the same function and level: "Head of Sales" -> "Sales Director". RELATED = also broader roles in the same function: "SDR" -> "Account Executive". Ignored unless match_mode is SMART. Allowed values: `SAME_ROLE`, `SIMILAR`, `RELATED`. - `boolean_search` (string, optional, max length: 20000): Boolean / Cartesian title query, e.g. "(CEO OR CTO) AND !Intern". Syntax: bareword=contains; 'single quotes'=contains too, and the way to write a title with a space in it - 'vp marketing' matches exactly what include: ["vp marketing"] matches; "double quotes"=exact; `backticks`=words in order with connectors bridged, so `vp marketing` finds "VP of Marketing" but not "VP Sales and Marketing" or "Marketing VP"; !=exclude, AND/OR, ()=grouping. Max 500 terms, depth 5, each term 2-100 chars. AND and OR cannot be mixed at the same nesting level - use parentheses to group. Mutually exclusive with include/exclude. - `person_seniority` (object, optional): Seniority (see GET /v2/enums/seniorities). Example: `{"filters":{"person_seniority":{"include":["C-Suite","VP","Director"]}}}` - `include` (enum[], optional): Seniority levels to match (any of). See GET /v2/enums/seniorities. Allowed values: `Owner`, `C-Suite`, `Partner`, `VP`, `Head`, `Director`, `Manager`, `Senior`, `Mid-level`, `Entry`, `Intern`, `Unpaid`. - `exclude` (enum[], optional): Seniority levels to reject. See GET /v2/enums/seniorities. Allowed values: `Owner`, `C-Suite`, `Partner`, `VP`, `Head`, `Director`, `Manager`, `Senior`, `Mid-level`, `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, including people with no specific sub-department; a sub-department matches only that sub-department. See GET /v2/enums/departments. Allowed values: `C-Suite`, `Consulting`, `Design`, `Education & Coaching`, `Engineering & Technical`, `Finance`, `Human Resources`, `Information Technology`, `Legal`, `Marketing`, `Medical & Health`, `Operations`, `Procurement & Purchasing`, `Product`, `Sales`, `Account Executive`, `Account Management`, `Accounting`, `Administrative & Office Support`, `Advertising`, `Anesthesiology`, `Architecture & Interior Design`, `Artificial Intelligence & Machine Learning`, `Banking & Investment`, `Bioengineering`, `Brand Management`, `Business Analysis`, `Business Development`, `Business Intelligence & Data Warehouse`, `Buying & Merchandising`, `Call Center`, `Channel Sales`, `Chemical Engineering`, `Chiropractics`, `Civil & Structural Engineering`, `Clinical Research`, `Clinical Systems`, `Cloud & Infrastructure`, `Coach & Trainer`, `Compensation & Benefits`, `Compliance & Privacy`, `Construction`, `Consultant`, `Content Marketing`, `Contracts`, `Corporate Secretary`, `Culture, Diversity & Inclusion`, `Customer Experience`, `Customer Marketing`, `Customer Retention & Development`, `Customer Service & Support`, `Customer Success`, `Data Center & Servers`, `Data Engineering`, `Data Management & Governance`, `Data Science & Analytics`, `Database Administration`, `Dentistry`, `Dermatology`, `DevOps & SRE`, `Digital Marketing`, `Doctors & Physicians`, `eCommerce Development`, `eCommerce Marketing`, `Education Administration`, `Electrical & Hardware Engineering`, `Emergency Medical Services`, `Employee & Labor Relations`, `Engineering Management`, `Enterprise Architecture`, `Epidemiology`, `ERP Systems`, `Ethics & Governance`, `Event & Field Marketing`, `Executive`, `Facilities Management`, `Field & Outside Sales`, `Finance Executive`, `Financial Planning & Analysis`, `Financial Reporting`, `Financial Risk`, `Financial Systems`, `Founder`, `Governmental Affairs & Regulatory Law`, `Graphic, Web & Brand Design`, `Growth & Demand Generation`, `Health & Safety`, `Help Desk & Desktop Services`, `Hospitality & Food Service`, `HR Business Partner`, `Human Resources Executive`, `Implementation & Onboarding`, `Industrial & Fashion Design`, `Industrial Engineering`, `Infectious Disease`, `Information Security`, `Information Technology Executive`, `Inside Sales`, `Insurance & Actuarial`, `Intellectual Property & Patent`, `Internal Audit & Control`, `Investor Relations`, `IT Asset Management`, `IT Audit & IT Compliance`, `IT Operations`, `IT Procurement`, `IT Strategy`, `Lawyer & Attorney`, `Lead Generation`, `Learning & Development`, `Legal Counsel`, `Legal Executive`, `Legal Operations`, `Litigation & eDiscovery`, `Logistics & Transportation`, `Maintenance & Repair`, `Manufacturing & Production`, `Marketing Analytics & Insights`, `Marketing Communications`, `Marketing Executive`, `Marketing Operations`, `Mechanical Engineering`, `Medical & Health Executive`, `Medical Administration`, `Medical Assistants & Technicians`, `Medical Education & Training`, `Mergers & Acquisitions`, `Mobile Development`, `Networking`, `Neurology`, `Nursing`, `Nutrition & Dietetics`, `Obstetrics & Gynecology`, `Oncology`, `Operations Executive`, `Ophthalmology & Optometry`, `Organizational Development`, `Orthopedics`, `Paralegal & Legal Support`, `Partnerships & Alliances`, `Pathology`, `Pediatrics`, `People Operations`, `Pharmacy`, `Photography, Video & Media Production`, `Physical Security`, `Physical Therapy`, `Principal`, `Product & UX/UI Design`, `Product Development`, `Product Executive`, `Product Management`, `Product Marketing`, `Product Operations`, `Professor`, `Project Management`, `Psychiatry`, `Psychology`, `Public Health`, `Public Relations`, `Quality Management`, `Radiology`, `Real Estate`, `Real Estate Finance`, `Recruiting & Talent Acquisition`, `Research & Development`, `Retail Sales`, `Revenue Operations`, `Sales Development (SDR/BDR)`, `Sales Enablement & Training`, `Sales Engineering & Solutions`, `Sales Leader`, `Sales Operations`, `Scrum Master & Agile Coach`, `SEO & Paid Search`, `Social Media & Influencer Marketing`, `Social Work & Counseling`, `Software Development`, `Store & Retail Operations`, `Strategic Sourcing`, `Strategy, Innovation & Transformation`, `Supply Chain`, `Sustainability & ESG`, `Talent Management`, `Tax`, `Teacher`, `Technical Support`, `Technician`, `Telecommunications`, `Test & Quality Assurance`, `Treasury`, `Vendor & Supplier Management`, `Veterinary`, `Web Development`, `Workforce Management`, `Writing & Editing`. - `exclude` (enum[], optional): Departments to reject. A group rejects everyone in it, including people with no specific sub-department; a sub-department rejects only that sub-department. See GET /v2/enums/departments. Allowed values: `C-Suite`, `Consulting`, `Design`, `Education & Coaching`, `Engineering & Technical`, `Finance`, `Human Resources`, `Information Technology`, `Legal`, `Marketing`, `Medical & Health`, `Operations`, `Procurement & Purchasing`, `Product`, `Sales`, `Account Executive`, `Account Management`, `Accounting`, `Administrative & Office Support`, `Advertising`, `Anesthesiology`, `Architecture & Interior Design`, `Artificial Intelligence & Machine Learning`, `Banking & Investment`, `Bioengineering`, `Brand Management`, `Business Analysis`, `Business Development`, `Business Intelligence & Data Warehouse`, `Buying & Merchandising`, `Call Center`, `Channel Sales`, `Chemical Engineering`, `Chiropractics`, `Civil & Structural Engineering`, `Clinical Research`, `Clinical Systems`, `Cloud & Infrastructure`, `Coach & Trainer`, `Compensation & Benefits`, `Compliance & Privacy`, `Construction`, `Consultant`, `Content Marketing`, `Contracts`, `Corporate Secretary`, `Culture, Diversity & Inclusion`, `Customer Experience`, `Customer Marketing`, `Customer Retention & Development`, `Customer Service & Support`, `Customer Success`, `Data Center & Servers`, `Data Engineering`, `Data Management & Governance`, `Data Science & Analytics`, `Database Administration`, `Dentistry`, `Dermatology`, `DevOps & SRE`, `Digital Marketing`, `Doctors & Physicians`, `eCommerce Development`, `eCommerce Marketing`, `Education Administration`, `Electrical & Hardware Engineering`, `Emergency Medical Services`, `Employee & Labor Relations`, `Engineering Management`, `Enterprise Architecture`, `Epidemiology`, `ERP Systems`, `Ethics & Governance`, `Event & Field Marketing`, `Executive`, `Facilities Management`, `Field & Outside Sales`, `Finance Executive`, `Financial Planning & Analysis`, `Financial Reporting`, `Financial Risk`, `Financial Systems`, `Founder`, `Governmental Affairs & Regulatory Law`, `Graphic, Web & Brand Design`, `Growth & Demand Generation`, `Health & Safety`, `Help Desk & Desktop Services`, `Hospitality & Food Service`, `HR Business Partner`, `Human Resources Executive`, `Implementation & Onboarding`, `Industrial & Fashion Design`, `Industrial Engineering`, `Infectious Disease`, `Information Security`, `Information Technology Executive`, `Inside Sales`, `Insurance & Actuarial`, `Intellectual Property & Patent`, `Internal Audit & Control`, `Investor Relations`, `IT Asset Management`, `IT Audit & IT Compliance`, `IT Operations`, `IT Procurement`, `IT Strategy`, `Lawyer & Attorney`, `Lead Generation`, `Learning & Development`, `Legal Counsel`, `Legal Executive`, `Legal Operations`, `Litigation & eDiscovery`, `Logistics & Transportation`, `Maintenance & Repair`, `Manufacturing & Production`, `Marketing Analytics & Insights`, `Marketing Communications`, `Marketing Executive`, `Marketing Operations`, `Mechanical Engineering`, `Medical & Health Executive`, `Medical Administration`, `Medical Assistants & Technicians`, `Medical Education & Training`, `Mergers & Acquisitions`, `Mobile Development`, `Networking`, `Neurology`, `Nursing`, `Nutrition & Dietetics`, `Obstetrics & Gynecology`, `Oncology`, `Operations Executive`, `Ophthalmology & Optometry`, `Organizational Development`, `Orthopedics`, `Paralegal & Legal Support`, `Partnerships & Alliances`, `Pathology`, `Pediatrics`, `People Operations`, `Pharmacy`, `Photography, Video & Media Production`, `Physical Security`, `Physical Therapy`, `Principal`, `Product & UX/UI Design`, `Product Development`, `Product Executive`, `Product Management`, `Product Marketing`, `Product Operations`, `Professor`, `Project Management`, `Psychiatry`, `Psychology`, `Public Health`, `Public Relations`, `Quality Management`, `Radiology`, `Real Estate`, `Real Estate Finance`, `Recruiting & Talent Acquisition`, `Research & Development`, `Retail Sales`, `Revenue Operations`, `Sales Development (SDR/BDR)`, `Sales Enablement & Training`, `Sales Engineering & Solutions`, `Sales Leader`, `Sales Operations`, `Scrum Master & Agile Coach`, `SEO & Paid Search`, `Social Media & Influencer Marketing`, `Social Work & Counseling`, `Software Development`, `Store & Retail Operations`, `Strategic Sourcing`, `Strategy, Innovation & Transformation`, `Supply Chain`, `Sustainability & ESG`, `Talent Management`, `Tax`, `Teacher`, `Technical Support`, `Technician`, `Telecommunications`, `Test & Quality Assurance`, `Treasury`, `Vendor & Supplier Management`, `Veterinary`, `Web Development`, `Workforce Management`, `Writing & Editing`. - `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` (integer, optional, min: 0, max: 600): Minimum whole months (inclusive), 0-600. Optional. - `max` (integer, optional, min: 0, max: 600): Maximum whole months (inclusive), 0-600, must be >= min. Optional. - `person_months_in_current_company` (object, optional): Months at the current company (tenure since joining). Integer months 0-600. Example: `{"filters":{"person_months_in_current_company":{"min":12}}}` - `min` (integer, optional, min: 0, max: 600): Minimum whole months (inclusive), 0-600. Optional. - `max` (integer, optional, min: 0, max: 600): Maximum whole months (inclusive), 0-600, must be >= min. Optional. - `person_job_change` (object, optional): 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` (integer, required, min: 1, max: 1000): Months since the current role started, counted in CALENDAR months the way LinkedIn counts them: a role is "N months" if it spans N calendar months inclusive, so a role begun any time in August is 2 months old on 1 September. `timeframe_months: 1` therefore matches only roles begun in the current month. Any whole number from 1 to 1000. Replaces the former `timeframe_days`, which accepted only 30, 60, 90, 180, 270 or 365. Example: `3` - `change_type` (enum, optional, 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"]}}}}` - `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 the organization that owns one of these domains, e.g. "stripe.com" - see `match_mode` for which of its company pages count. Scheme, "www." and any path are stripped. Max 100 items. - `exclude` (string[], optional): Reject people whose company is on one of these domains. - `match_mode` (enum, optional, default: "ORGANIZATION"): Which company pages an `include` domain stands for. ORGANIZATION (default) = every company page that belongs to the organization owning the domain: its main page, its regional, brand and subsidiary pages. A small page that only links to the domain - a business hosted on a platform, a same-named company - is left out. PRIMARY = only the one main company page of the domain, leaving out the organization's other pages. LINKEDIN_WEBSITE = only the organization's pages whose own LinkedIn website is on the domain, so the domain is never inferred: "stripe.com", "stripe.com/jobs" and "jobs.stripe.com" all match "stripe.com"; a page that lists another site, or no website, does not. `exclude` is not affected: it always rejects every company on the domain. Allowed values: `ORGANIZATION`, `PRIMARY`, `LINKEDIN_WEBSITE`. - `name` (object, optional): Match by company name - exact by default, or the term within the name 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 written, case-insensitive, starting at a word ("Haven Health" matches "Haven Health Management" and "New Haven Healthcare"). A match inside a longer word ("nails" in "AllNailSpa") comes back only for a term that matches no name at a word start, and reliably only for a single-word term. A multi-word term that matches no name as written falls back to names holding all of its words in any order ("Oak Park River Forest High School" matches "Oak Park and River Forest High School"). An `exclude` term matches anywhere in the name ("soft" also rejects "Microsoft"). Resolved against the company index 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). Have a company LinkedIn URL instead? Use `company.linkedin_url`. Example: `{"filters":{"company":{"linkedin_id":{"include":[2135371]}}}}` - `include` (integer[], optional): Match these LinkedIn companies. LinkedIn's numeric company id. Company LinkedIn URLs are not accepted here: People Search takes them as `company.linkedin_url`; elsewhere enrich the company by `linkedin_url` and put the `id` it returns in `company.id`. Max 500 items. Example: `[162479]` - `exclude` (integer[], optional): Reject these LinkedIn companies. LinkedIn's numeric company id. Company LinkedIn URLs are not accepted here: People Search takes them as `company.linkedin_url`; elsewhere enrich the company by `linkedin_url` and put the `id` it returns in `company.id`. Max 500 items. - `linkedin_url` (object, optional): Match by LinkedIn company URL (https://www.linkedin.com/company/stripe/ - vanity slug or numeric id). Each URL is resolved to the companies we hold for that LinkedIn page and then works exactly like `company.id`: its includes join the `company.id` includes (people at any of them), its excludes the `company.id` excludes. A URL we know no company for matches nobody (200, empty page); a value that is not a LinkedIn company URL is a 400 (`invalid_format`). Example: `{"filters":{"company":{"linkedin_url":{"include":["https://www.linkedin.com/company/stripe/"]}}}}` - `include` (string[], optional): Only people who work at these companies, by LinkedIn company page URL (vanity slug or numeric id, Sales Navigator company URLs too). A URL we know no company for matches nobody. Max 500 items. Example: `["https://www.linkedin.com/company/stripe/"]` - `exclude` (string[], optional): Reject people who work at these companies, by LinkedIn company page URL. Max 500 items. - `company_industry` (object, optional): Industry of the person's company (see GET /v2/enums/industries; any casing). An unknown value, even one in a list of good ones, fails the request with 400 `value_not_allowed`, with `suggested_values` for near spellings. Example: `{"filters":{"company_industry":{"include":["Software Development","IT Services & IT Consulting"],"exclude":["Staffing & Recruiting"]}}}` - `include` (string[], optional): Industries or industry GROUPS to match (any of). A group name matches every industry in that category. See GET /v2/enums/industries for both. Example: `["Agriculture & Mining","Software Development"]` - `exclude` (string[], optional): Industries or industry GROUPS to reject. A group name rejects every industry in that category. See GET /v2/enums/industries for both. - `company_headcount_range` (enum[], optional): Bucketed headcount range of the company (see GET /v2/enums/employee_ranges). Allowed values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Example: `{"filters":{"company_headcount_range":["51-200","201-500"]}}` - `company_country` (object, optional): 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_ai_industry` (object, optional): AI industry of the person's company (see GET /v2/enums/ai_industries): an industry group or a sub-industry. A group matches all its sub-industries. Casing does not matter, and "&" is read as "and". Example: `{"filters":{"company_ai_industry":{"include":["Finance and Insurance"],"exclude":["Banking and Lending"]}}}` - `include` (enum[], optional): AI industries to match (any of). A group matches all its sub-industries; a sub-industry matches only itself. Allowed values: `Software and IT`, `Healthcare and Life Sciences`, `Finance and Insurance`, `Energy, Utilities and Environmental Services`, `Industrial Manufacturing and Materials`, `Real Estate and Construction`, `Retail and Consumer Channels`, `Transportation and Logistics`, `Professional, Business and Legal Services`, `Education and Training`, `Media, Entertainment and Culture`, `Hospitality, Food and Travel Services`, `Personal and Home Services`, `Agriculture, Forestry and Fisheries`, `Automotive, Aerospace and Defense Manufacturing`, `Non-Profit, Public Sector and Education (Non-Commercial)`, `AI and ML Platforms`, `Agriculture and Forestry Software`, `Blockchain and Web3`, `Carriers and ISPs`, `Cloud and Infrastructure Software`, `Consumer Software`, `Data and Analytics Software`, `Developer Tools and Platforms`, `Enterprise Software Solutions`, `Financial Services Software`, `Government and Public Sector Software`, `Hardware and Networking`, `Healthcare Software`, `IoT and Embedded Systems Software`, `IT Services and Cybersecurity`, `Manufacturing Software`, `Metaverse, AR/VR and Other Emerging Platforms`, `Quantum Computing Software`, `Real Estate and PropTech Software`, `Retail and Ecommerce Software`, `Security and Identity Software`, `Biotechnology and Pharmaceuticals`, `Digital Health and Telemedicine`, `Hospitals, Clinics and Outpatient Care`, `Medical Devices and Diagnostic Equipment`, `Medical Testing and Clinical Laboratories`, `Mental Health and Rehabilitation Services`, `Pharma Distribution and CRO Services`, `Banking and Lending`, `Capital Markets and Cryptocurrency`, `Cryptocurrency and Blockchain Services`, `Financial Services Platforms`, `Insurance and InsurTech`, `Investment Management and WealthTech`, `Venture Capital and Private Equity`, `Electric Power and Grid Management`, `Nuclear and Advanced Generation`, `Oil and Gas Exploration, Production and Services`, `Renewable Energy and Clean Tech`, `Sustainability Tech and Environmental Consulting`, `Water, Waste and Environmental Management`, `3D Printing and Advanced Manufacturing`, `Building Materials and Chemicals`, `Consumer Goods and Appliances`, `Electronics and Computer Equipment`, `Food, Beverage and Tobacco Production`, `Industrial Machinery and Equipment`, `Mining, Metals and Natural Resources`, `Architecture, Urban Planning and Green Building`, `Commercial Real Estate Development and Leasing`, `Construction and Civil Engineering Services`, `Property and Facility Management`, `Residential Real Estate Development and Brokerage`, `Specialty Construction Products`, `Automotive Service and Collision Repair`, `Brick-and-Mortar Retail`, `Media and Entertainment Retail`, `Online Commerce and Marketplaces`, `Retail Technology`, `Specialty Auctions and Collectibles`, `Wholesale and Distribution`, `Autonomous Vehicles and Drone Delivery`, `Car and Truck Rental`, `Freight and Cargo`, `Logistics Technology`, `Passenger Transit and Mobility`, `Warehousing, Fulfillment and 3PL Services`, `Accounting, Audit and Financial Advisory`, `Advertising, Marketing and Multimedia Design`, `Defense and Government Services`, `Facilities Management and Commercial Cleaning`, `Human Resources, Staffing and Recruitment`, `Legal Services and Regulatory Compliance`, `Management Consulting and Strategy Consulting`, `Translation, Document and Information Management`, `Corporate Training and Learning and Development`, `E-Learning Platforms and EdTech`, `K-12 and Higher Education Institutions`, `Test Prep, Tutoring and After-School Services`, `Vocational Training and Certification Programs`, `Digital Publishing and Streaming Platforms`, `Film, Television and Broadcasting`, `Gaming, Esports and Interactive Entertainment`, `Live Events, Experiences and Ticketed Attractions`, `Museums, Art Galleries and Cultural Preservation`, `Music, Audio and Podcast Services`, `Sports and Recreation`, `Food and Beverage Services`, `Hospitality and Lodging`, `Travel Agencies and Leisure Services`, `Funeral Homes and Related Services`, `Home Services`, `Personal Care and Wellness`, `Veterinary Care and Pet Services`, `AgriTech and Precision Farming`, `Aquaculture and Fisheries`, `Crop Farming and Livestock Production`, `Farming Equipment and Supplies`, `Forestry, Logging and Wood Products`, `Mining and Extraction`, `Aviation and Aerospace Component Manufacturing`, `Automotive and Rental Retail`, `Commercial Space Innovation`, `Defense Systems and Marine Manufacturing`, `Motor Vehicle and Parts Manufacturing`, `Government Administration and Municipal Services`, `NGOs, Charities and Community Organizations`, `Public Healthcare and Social Services`, `Public/Private Research Institutions and Educational Foundations`, `Student Organizations and Campus Services`. - `exclude` (enum[], optional): AI industries to reject. A group rejects all its sub-industries; a sub-industry rejects only itself. Allowed values: `Software and IT`, `Healthcare and Life Sciences`, `Finance and Insurance`, `Energy, Utilities and Environmental Services`, `Industrial Manufacturing and Materials`, `Real Estate and Construction`, `Retail and Consumer Channels`, `Transportation and Logistics`, `Professional, Business and Legal Services`, `Education and Training`, `Media, Entertainment and Culture`, `Hospitality, Food and Travel Services`, `Personal and Home Services`, `Agriculture, Forestry and Fisheries`, `Automotive, Aerospace and Defense Manufacturing`, `Non-Profit, Public Sector and Education (Non-Commercial)`, `AI and ML Platforms`, `Agriculture and Forestry Software`, `Blockchain and Web3`, `Carriers and ISPs`, `Cloud and Infrastructure Software`, `Consumer Software`, `Data and Analytics Software`, `Developer Tools and Platforms`, `Enterprise Software Solutions`, `Financial Services Software`, `Government and Public Sector Software`, `Hardware and Networking`, `Healthcare Software`, `IoT and Embedded Systems Software`, `IT Services and Cybersecurity`, `Manufacturing Software`, `Metaverse, AR/VR and Other Emerging Platforms`, `Quantum Computing Software`, `Real Estate and PropTech Software`, `Retail and Ecommerce Software`, `Security and Identity Software`, `Biotechnology and Pharmaceuticals`, `Digital Health and Telemedicine`, `Hospitals, Clinics and Outpatient Care`, `Medical Devices and Diagnostic Equipment`, `Medical Testing and Clinical Laboratories`, `Mental Health and Rehabilitation Services`, `Pharma Distribution and CRO Services`, `Banking and Lending`, `Capital Markets and Cryptocurrency`, `Cryptocurrency and Blockchain Services`, `Financial Services Platforms`, `Insurance and InsurTech`, `Investment Management and WealthTech`, `Venture Capital and Private Equity`, `Electric Power and Grid Management`, `Nuclear and Advanced Generation`, `Oil and Gas Exploration, Production and Services`, `Renewable Energy and Clean Tech`, `Sustainability Tech and Environmental Consulting`, `Water, Waste and Environmental Management`, `3D Printing and Advanced Manufacturing`, `Building Materials and Chemicals`, `Consumer Goods and Appliances`, `Electronics and Computer Equipment`, `Food, Beverage and Tobacco Production`, `Industrial Machinery and Equipment`, `Mining, Metals and Natural Resources`, `Architecture, Urban Planning and Green Building`, `Commercial Real Estate Development and Leasing`, `Construction and Civil Engineering Services`, `Property and Facility Management`, `Residential Real Estate Development and Brokerage`, `Specialty Construction Products`, `Automotive Service and Collision Repair`, `Brick-and-Mortar Retail`, `Media and Entertainment Retail`, `Online Commerce and Marketplaces`, `Retail Technology`, `Specialty Auctions and Collectibles`, `Wholesale and Distribution`, `Autonomous Vehicles and Drone Delivery`, `Car and Truck Rental`, `Freight and Cargo`, `Logistics Technology`, `Passenger Transit and Mobility`, `Warehousing, Fulfillment and 3PL Services`, `Accounting, Audit and Financial Advisory`, `Advertising, Marketing and Multimedia Design`, `Defense and Government Services`, `Facilities Management and Commercial Cleaning`, `Human Resources, Staffing and Recruitment`, `Legal Services and Regulatory Compliance`, `Management Consulting and Strategy Consulting`, `Translation, Document and Information Management`, `Corporate Training and Learning and Development`, `E-Learning Platforms and EdTech`, `K-12 and Higher Education Institutions`, `Test Prep, Tutoring and After-School Services`, `Vocational Training and Certification Programs`, `Digital Publishing and Streaming Platforms`, `Film, Television and Broadcasting`, `Gaming, Esports and Interactive Entertainment`, `Live Events, Experiences and Ticketed Attractions`, `Museums, Art Galleries and Cultural Preservation`, `Music, Audio and Podcast Services`, `Sports and Recreation`, `Food and Beverage Services`, `Hospitality and Lodging`, `Travel Agencies and Leisure Services`, `Funeral Homes and Related Services`, `Home Services`, `Personal Care and Wellness`, `Veterinary Care and Pet Services`, `AgriTech and Precision Farming`, `Aquaculture and Fisheries`, `Crop Farming and Livestock Production`, `Farming Equipment and Supplies`, `Forestry, Logging and Wood Products`, `Mining and Extraction`, `Aviation and Aerospace Component Manufacturing`, `Automotive and Rental Retail`, `Commercial Space Innovation`, `Defense Systems and Marine Manufacturing`, `Motor Vehicle and Parts Manufacturing`, `Government Administration and Municipal Services`, `NGOs, Charities and Community Organizations`, `Public Healthcare and Social Services`, `Public/Private Research Institutions and Educational Foundations`, `Student Organizations and Campus Services`. - `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_headcount_by_department` (object[], optional): Headcount of the person's company by department, optionally within one country or state. Rows AND together; each row is a `department` plus `min` and/or `max` people (a `max` also matches companies with nobody in the department). 1-10 rows. Example: `{"filters":{"company_headcount_by_department":[{"department":"Sales","min":10}]}}` - `department` (enum, required): Department group ("Sales") or sub-department ("Sales Operations"); see GET /v2/enums/departments. Casing does not matter. Allowed values: `C-Suite`, `Consulting`, `Design`, `Education & Coaching`, `Engineering & Technical`, `Finance`, `Human Resources`, `Information Technology`, `Legal`, `Marketing`, `Medical & Health`, `Operations`, `Procurement & Purchasing`, `Product`, `Sales`, `Account Executive`, `Account Management`, `Accounting`, `Administrative & Office Support`, `Advertising`, `Anesthesiology`, `Architecture & Interior Design`, `Artificial Intelligence & Machine Learning`, `Banking & Investment`, `Bioengineering`, `Brand Management`, `Business Analysis`, `Business Development`, `Business Intelligence & Data Warehouse`, `Buying & Merchandising`, `Call Center`, `Channel Sales`, `Chemical Engineering`, `Chiropractics`, `Civil & Structural Engineering`, `Clinical Research`, `Clinical Systems`, `Cloud & Infrastructure`, `Coach & Trainer`, `Compensation & Benefits`, `Compliance & Privacy`, `Construction`, `Consultant`, `Content Marketing`, `Contracts`, `Corporate Secretary`, `Culture, Diversity & Inclusion`, `Customer Experience`, `Customer Marketing`, `Customer Retention & Development`, `Customer Service & Support`, `Customer Success`, `Data Center & Servers`, `Data Engineering`, `Data Management & Governance`, `Data Science & Analytics`, `Database Administration`, `Dentistry`, `Dermatology`, `DevOps & SRE`, `Digital Marketing`, `Doctors & Physicians`, `eCommerce Development`, `eCommerce Marketing`, `Education Administration`, `Electrical & Hardware Engineering`, `Emergency Medical Services`, `Employee & Labor Relations`, `Engineering Management`, `Enterprise Architecture`, `Epidemiology`, `ERP Systems`, `Ethics & Governance`, `Event & Field Marketing`, `Executive`, `Facilities Management`, `Field & Outside Sales`, `Finance Executive`, `Financial Planning & Analysis`, `Financial Reporting`, `Financial Risk`, `Financial Systems`, `Founder`, `Governmental Affairs & Regulatory Law`, `Graphic, Web & Brand Design`, `Growth & Demand Generation`, `Health & Safety`, `Help Desk & Desktop Services`, `Hospitality & Food Service`, `HR Business Partner`, `Human Resources Executive`, `Implementation & Onboarding`, `Industrial & Fashion Design`, `Industrial Engineering`, `Infectious Disease`, `Information Security`, `Information Technology Executive`, `Inside Sales`, `Insurance & Actuarial`, `Intellectual Property & Patent`, `Internal Audit & Control`, `Investor Relations`, `IT Asset Management`, `IT Audit & IT Compliance`, `IT Operations`, `IT Procurement`, `IT Strategy`, `Lawyer & Attorney`, `Lead Generation`, `Learning & Development`, `Legal Counsel`, `Legal Executive`, `Legal Operations`, `Litigation & eDiscovery`, `Logistics & Transportation`, `Maintenance & Repair`, `Manufacturing & Production`, `Marketing Analytics & Insights`, `Marketing Communications`, `Marketing Executive`, `Marketing Operations`, `Mechanical Engineering`, `Medical & Health Executive`, `Medical Administration`, `Medical Assistants & Technicians`, `Medical Education & Training`, `Mergers & Acquisitions`, `Mobile Development`, `Networking`, `Neurology`, `Nursing`, `Nutrition & Dietetics`, `Obstetrics & Gynecology`, `Oncology`, `Operations Executive`, `Ophthalmology & Optometry`, `Organizational Development`, `Orthopedics`, `Paralegal & Legal Support`, `Partnerships & Alliances`, `Pathology`, `Pediatrics`, `People Operations`, `Pharmacy`, `Photography, Video & Media Production`, `Physical Security`, `Physical Therapy`, `Principal`, `Product & UX/UI Design`, `Product Development`, `Product Executive`, `Product Management`, `Product Marketing`, `Product Operations`, `Professor`, `Project Management`, `Psychiatry`, `Psychology`, `Public Health`, `Public Relations`, `Quality Management`, `Radiology`, `Real Estate`, `Real Estate Finance`, `Recruiting & Talent Acquisition`, `Research & Development`, `Retail Sales`, `Revenue Operations`, `Sales Development (SDR/BDR)`, `Sales Enablement & Training`, `Sales Engineering & Solutions`, `Sales Leader`, `Sales Operations`, `Scrum Master & Agile Coach`, `SEO & Paid Search`, `Social Media & Influencer Marketing`, `Social Work & Counseling`, `Software Development`, `Store & Retail Operations`, `Strategic Sourcing`, `Strategy, Innovation & Transformation`, `Supply Chain`, `Sustainability & ESG`, `Talent Management`, `Tax`, `Teacher`, `Technical Support`, `Technician`, `Telecommunications`, `Test & Quality Assurance`, `Treasury`, `Vendor & Supplier Management`, `Veterinary`, `Web Development`, `Workforce Management`, `Writing & Editing`. Example: `"Product Development"` - `location` (string, optional): Count only people located in this ONE location, which must resolve to a country or a state ("Germany", "California, United States"). A city or a multi-country region answers 400. Omit for anywhere. 2-200 chars. Example: `"California, United States"` - `min` (integer, optional): At least this many people (inclusive). Integer 0-1,000,000. Example: `10` - `max` (integer, optional): At most this many people (inclusive). Integer 0-1,000,000, at least min. Companies with no people in the department count as 0 and match. Example: `20` - `company_headcount_growth` (object, optional): Headcount growth (percent) of the person's company in each listed department group over the last 3, 6, 12 or 24 months. Companies with too little history have no growth figure and never match. Example: `{"filters":{"company_headcount_growth":{"departments":["Sales"],"timeframe_months":6,"min":20}}}` - `departments` (enum[], required): Department GROUPS (not sub-departments), 1-15. A company must match the range in every one of them. Allowed values: `C-Suite`, `Consulting`, `Design`, `Education & Coaching`, `Engineering & Technical`, `Finance`, `Human Resources`, `Information Technology`, `Legal`, `Marketing`, `Medical & Health`, `Operations`, `Procurement & Purchasing`, `Product`, `Sales`. Example: `["Sales","Product"]` - `timeframe_months` (enum, required): Window in months, ending now. Allowed values: `3`, `6`, `12`, `24`. Example: `3` - `min` (number, optional): Growth of at least this many percent (inclusive). -100 to 10000. Example: `10` - `max` (number, optional): Growth of at most this many percent (inclusive). -100 to 10000, at least min. Example: `20` - `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. Any value that does not resolve fails the whole request with 400 (`invalid_value`, naming it in `invalid_values`), even beside values that do: nothing is silently dropped. Look values up with POST /v2/search/suggest (type location). - `exclude` (string[], optional): Reject these locations (same unified-string format; a region minus a country works: include ["Europe"], exclude ["Germany"]). Max 100 items, each 2-200 chars. A value that does not resolve is skipped, so check the spelling: a misspelled exclude ("Germny") leaves that place in the results. - `headquarters_only` (boolean, optional, default: false): When true, match the company headquarters location only. When false (default), any office location we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). - `company_technologies` (object, optional): Web technologies detected on the company website, by id: the `value` of a `POST /v2/search/suggest` row with `type: technology` and `kind: technology`. Websites are rescanned every 30 days. Matches the company of the matched position. Not available yet: answers 400 until the people index carries company technologies. Example: `{"filters":{"company_technologies":{"include":["3421"]}}}` - `include` (string[], optional): Technology ids to match. `match_mode: ANY` (default): a company using any of them qualifies; `ALL`: it must use every one. Max 500. Example: `["3421"]` - `exclude` (string[], optional): Reject companies using any of these technology ids. Max 500. - `match_mode` (enum, optional, default: "ANY"): How `include` combines: `ANY` (default) - at least one; `ALL` - every one, on the same company. Allowed values: `ANY`, `ALL`. - `company_technology_categories` (object, optional): Technology categories (CMS, Ecommerce, Analytics, ...), by id: the `value` of a suggest row with `kind: category`. A category matches a company using any technology in it. Matches the company of the matched position. Not available yet: answers 400 until the people index carries company technologies. Example: `{"filters":{"company_technology_categories":{"include":["1"]}}}` - `include` (string[], optional): Category ids to match (any of). Max 200. Example: `["1"]` - `exclude` (string[], optional): Reject companies using any technology in these category ids. Max 200. - `contact_details` (object, optional): 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, or an email your workspace entered for the person), invalid, accept_all, not_found (no stored email and none entered by your workspace). Allowed values: `valid`, `invalid`, `accept_all`, `not_found`. - `revealed` (boolean, optional): true = only contacts whose email your workspace already revealed; false = only those NOT revealed. Requires an authenticated workspace. - `phone` (object, optional): Phone 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"}}}` - `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` (integer, optional, min: 1, max: 100): Cap the number of people returned per company across the whole result set (1-100). A person is counted against the company of the position that matched your company filters, or their current/primary position when no company filter is set. Of the colleagues competing for a company slot, one we hold a valid email for is kept, and your sort decides between them (and picks the representative outright when none of them has one). Results stay in your sort order either way. For result sets above 25000 matches the representative is simply whoever leads your sort, and total_count is a rounded PRE-cap estimate (pagination.total_is_estimate=true) - an upper bound, so an export of that selection returns fewer people. At or below it both are exact. Example: `{"filters":{"person_job_title":{"include":["Product Marketing Manager"]},"max_person_per_company":2}}` ## Example request ```bash curl --request POST \ --url https://api.getprospect.com/v2/search/smart-job-titles \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' \ --data ' { "job_titles": [ "Head of Procurement" ], "exclude_job_titles": [ "Intern" ], "filters": { "person_location": { "include": [ "Germany" ] } } } ' ``` ## Response 200 The suggested titles; an empty `titles` when there is nothing to add (still a 200). ```json { "success": true, "data": { "intent": "Senior procurement leaders in Germany", "titles": [ { "title": "Leiter Einkauf", "level": "SAME_ROLE", "new_people": 2616 }, { "title": "Head of Purchasing", "level": "SAME_ROLE", "new_people": 2092 }, { "title": "Einkaufsleiter", "level": "SAME_ROLE", "new_people": 1898 }, { "title": "Head of Sourcing", "level": "SAME_ROLE", "new_people": 319 }, { "title": "Leiterin Einkauf", "level": "SAME_ROLE", "new_people": 219 }, { "title": "Purchasing Director", "level": "SIMILAR", "new_people": 1635 }, { "title": "Procurement Director", "level": "SIMILAR", "new_people": 1633 }, { "title": "Leitung Einkauf", "level": "SIMILAR", "new_people": 1162 }, { "title": "Einkaufsleiterin", "level": "SIMILAR", "new_people": 215 }, { "title": "Leiter Beschaffung", "level": "SIMILAR", "new_people": 192 }, { "title": "Chief Procurement Officer", "level": "SIMILAR", "new_people": 161 }, { "title": "Purchasing Manager", "level": "RELATED", "new_people": 9826 }, { "title": "Category Manager", "level": "RELATED", "new_people": 6581 }, { "title": "Procurement Manager", "level": "RELATED", "new_people": 5534 }, { "title": "Sourcing Manager", "level": "RELATED", "new_people": 1799 }, { "title": "Einkaufsmanager", "level": "RELATED", "new_people": 252 }, { "title": "Einkaufsmanagerin", "level": "RELATED", "new_people": 35 } ], "exclude_titles": [ { "title": "Interns", "removed_people": 0 }, { "title": "becario", "removed_people": 0 }, { "title": "Praktikant", "removed_people": 0 }, { "title": "internship", "removed_people": 0 }, { "title": "praktykant", "removed_people": 0 }, { "title": "Praktikantin", "removed_people": 0 }, { "title": "Praktikanten", "removed_people": 0 }, { "title": "Praktikantinnen", "removed_people": 0 }, { "title": "co op", "removed_people": 0 }, { "title": "practicante profesional", "removed_people": 0 }, { "title": "thực tập sinh", "removed_people": 0 }, { "title": "empleado en prácticas", "removed_people": 0 }, { "title": "estudiante en prácticas", "removed_people": 0 } ] }, "metadata": { "timestamp": "2026-11-04T20:52:00.910Z", "cached": false } } ``` ## Response 400 Invalid request (`VALIDATION_ERROR`, `payload.code` says which kind): `job_titles` empty or too long, or `filters` that People Search itself would refuse. ## Response 401 Missing, unknown or inactive credentials (`UNAUTHORIZED`). ## Response 429 Either the per-second window of the `search` rate limit (`RATE_LIMIT`; this route spends no units), or the workspace used today's allowance of new AI suggestions (`RATE_LIMIT` with `payload.code: ai_daily_limit`, resets at 00:00 UTC; cached answers stay free). ```json { "success": false, "data": null, "metadata": { "timestamp": "2026-10-05T10:00:00.000Z" }, "errors": [ { "name": "RATE_LIMIT", "message": "Smart job titles: the daily limit of 200 new AI suggestions is used up; it resets at 00:00 UTC.", "payload": { "code": "ai_daily_limit" } } ] } ``` ## Response 500 Unexpected server error. ## Response 503 The AI could not answer right now (`UNAVAILABLE`); retry shortly, or search with match_mode CONTAINS.