{"openapi":"3.0.3","info":{"title":"Scalelist API","version":"1.0.0","description":"# Introduction\n\nFind verified work emails and direct mobile numbers for the people you want to reach.\n\nEvery lookup runs through a waterfall of specialist data providers, reaching for a paid source only when the cheaper ones come up empty. **You are charged only when we find something.**\n\n## What you can do\n\n- **Find an email** from a name and a company.\n- **Find a mobile number** from a LinkedIn URL, an email, or a name and a company.\n- **Find emails at a company**, with no names needed.\n- **Search for people** by title, seniority, industry and location.\n\nEach of these runs one at a time, or in bulk up to 100 per call with results delivered by webhook or polling.\n\n## Getting started\n\n1. Sign in to your [Scalelist account](https://app.scalelist.com/auth/login).\n2. Create an API key on the [API keys page](https://app.scalelist.com/app/api-key).\n3. Send it as the `x-api-key` header on every request:\n\n```http\nPOST /email/find/single\nx-api-key: YOUR_API_KEY\n```\n\nA missing or unrecognised key returns `401`; a malformed body returns `400` or `422`.\n\n## Using this API from an LLM or coding agent\n\nThis whole reference is also published as one plain-markdown file at [`/llms.txt`](/llms.txt). One fetch, with no JavaScript to render and no pages to crawl. It is generated from this same specification on every request, so it can never fall behind the endpoints below.\n\nWant a tour first? **[Summarise with ChatGPT](https://chatgpt.com/?hint=search&q=Read%20the%20Scalelist%20API%20reference%20at%20https%3A%2F%2Fapi.scalelist.com%2Fllms.txt%2C%20then%20give%20me%20a%20short%20tour%3A%20what%20the%20API%20can%20do%2C%20how%20authentication%20works%2C%20and%20what%20each%20endpoint%20costs%20in%20credits.)** · **[Summarise with Claude](https://claude.ai/new?q=Read%20the%20Scalelist%20API%20reference%20at%20https%3A%2F%2Fapi.scalelist.com%2Fllms.txt%2C%20then%20give%20me%20a%20short%20tour%3A%20what%20the%20API%20can%20do%2C%20how%20authentication%20works%2C%20and%20what%20each%20endpoint%20costs%20in%20credits.)**. Each opens a chat already pointed at `/llms.txt`.\n\n## Credits\n\n| Result | Credits |\n| --- | --- |\n| Work email | 1 |\n| Mobile number | 10 |\n| Person profile | 1 |\n\n# Rate limits\n\nOnly single lookups are metered. Bulk work runs on a queue that paces itself, and polling a task is free.\n\n## Single lookups\n\nEach family of endpoints holds its own allowance, per API key — so a burst of email lookups never slows down a phone call. The numbers differ because each family leans on a different set of upstream sources.\n\n| Single lookups | Allowance |\n| --- | --- |\n| `/email/…` — find, company domain | 500 / minute |\n| `/phone/…` — find | 1,000 / minute |\n| `/people/…` — search, count, industries | 150 / minute |\n\nEvery response tells you where you stand:\n\n| Header | What it tells you |\n| --- | --- |\n| `x-ratelimit-limit` | the allowance for that family |\n| `x-ratelimit-remaining` | how much of it is left this minute |\n| `retry-after` | on a `429` only — seconds until it refills |\n\nGo past the allowance and you get `429 Too Many Requests`. Wait the seconds `retry-after` names, then carry on. The allowance refills whole once a minute rather than sliding, and it is counted per key — a second key brings a second allowance.\n\n## Bulk queue\n\nBulk is not rate-limited. A bulk call takes up to **100 leads**, hands back a task id immediately, and the work runs on a queue — so a long batch never touches your per-minute allowance, and neither does polling it.\n\nWhat paces bulk is how much of it runs at once:\n\n| At once | Free | Standard | Enterprise |\n| --- | :-: | :-: | :-: |\n| Bulk tasks | 5 | 5 | 10 |\n| Emails per task | 1 | 10 | 50 |\n| Mobiles per task | 1 | 5 | 5 |\n\nSubmit more than that and the extra tasks wait their turn — nothing is rejected and nothing is lost. Email, phone and people bulk jobs share the same queues, so a large email batch and a phone batch compete for the same slots.\n\nSend an `Idempotency-Key` header to make retries safe for 24 hours.\n\n## People Search\n\n`POST /people/search` returns up to **100 profiles a page**, and never more than your balance can pay for — 20 credits caps that page at 20 profiles.\n\n`POST /people/count` costs 1 credit a call, so size an audience once and reuse the number.\n\nA bulk people search walks the audience one page at a time, so a large run arrives steadily over several minutes rather than in one burst.\n\nNeed more headroom than any of this? Ask us — these are per-account settings, not hard ceilings.\n"},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{}},"paths":{"/health":{"get":{"summary":"System health check","tags":["Health"],"description":"Check whether the API is running.\n\nReturns `ok` while everything the API depends on is reachable, and\n`degraded` with a 503 status if something is not — useful for uptime\nmonitors and status pages.\n\nNo API key needed, and it never costs credits.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"services":{"type":"object","properties":{"database":{"type":"string"},"cache":{"type":"string"}}}}}}}}}}},"/api/v1/account":{"get":{"summary":"Get your account details","tags":["Account Info"],"description":"Your profile, plan, and remaining credit balance.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"credits":{"type":"number"},"subscriptionPlan":{"type":"string"}}}}}}}}},"/api/v1/email/find/single":{"post":{"summary":"Find an email address","tags":["Email Enrichment"],"description":"Find a verified professional email from a person's name and company.\n\nProvide a **name** (`first_name` or `full_name`) and a **company** (`company_domain` or `company_name`). `last_name` is optional.\n\n**1 credit**, charged only when an email is found.","requestBody":{"content":{"application/json":{"schema":{"type":"object","allOf":[{"anyOf":[{"required":["first_name"]},{"required":["full_name"]}]},{"anyOf":[{"required":["company_domain"]},{"required":["company_name"]}]}],"properties":{"first_name":{"type":"string","description":"Provide first_name (last_name optional), OR full_name"},"last_name":{"type":"string","description":"Optional, may be omitted or empty"},"full_name":{"type":"string","description":"Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name"},"company_domain":{"type":"string","description":"Company domain without @ (provide this OR company_name)"},"company_name":{"type":"string","description":"Company name, used to resolve a domain if company_domain is omitted"},"custom":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata echoed back in the response and webhook payload"},"webhook_url":{"type":"string","format":"uri","description":"If supplied, the result is POSTed here once resolution completes"},"sync":{"type":"boolean","default":true,"description":"When false, returns 202 immediately and delivers the result only via webhook_url"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/find/bulk":{"post":{"summary":"Find emails in bulk","tags":["Email Enrichment"],"description":"Find up to 100 emails in one call. Returns a task id straight away; results arrive later.\n\n• Supply `webhook_url` and the results are POSTed there when the batch finishes.\n• Or poll `GET /email/find/bulk?job_id=<task_id>` whenever you like.\n\n**1 credit per email found.** Send an `Idempotency-Key` header to make retries safe for 24h.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","items":{"type":"object","allOf":[{"anyOf":[{"required":["first_name"]},{"required":["full_name"]}]},{"anyOf":[{"required":["company_domain"]},{"required":["company_name"]}]}],"properties":{"first_name":{"type":"string","description":"Provide first_name (last_name optional), OR full_name"},"last_name":{"type":"string","description":"Optional, may be omitted or empty"},"full_name":{"type":"string","description":"Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name"},"company_domain":{"type":"string","description":"Company domain without @ (provide this OR company_name)"},"company_name":{"type":"string","description":"Company name, used to resolve a domain if company_domain is omitted"},"custom":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata echoed back in the per-lead result and webhook payload"}}},"minItems":1,"maxItems":100},"webhook_url":{"type":"string","format":"uri","description":"Optional destination URL for the completion callback. When omitted, poll GET /email/find/bulk?job_id=... for results."}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]+$"},"in":"header","name":"idempotency-key","required":false,"description":"Optional. Per-submission UUID (recommended) so client-side retries on network blips don't create duplicate tasks or extra charges. Replay window: 24h."}],"responses":{"202":{"description":"Task accepted (or idempotent replay of an earlier submission).","content":{"application/json":{"schema":{"description":"Task accepted (or idempotent replay of an earlier submission).","type":"object","properties":{"taskId":{"type":"string","description":"Mongo ObjectId of the durable search task."},"status":{"type":"string","enum":["queued"]},"total":{"type":"integer","description":"Number of lead requests queued."}}}}}},"400":{"description":"Validation error. `code` discriminates the specific cause: `idempotency_key_invalid` (bad header format) or `idempotency_key_reused` (same key, different body within 24h).","content":{"application/json":{"schema":{"description":"Validation error. `code` discriminates the specific cause: `idempotency_key_invalid` (bad header format) or `idempotency_key_reused` (same key, different body within 24h).","type":"object","properties":{"statusCode":{"type":"integer","enum":[400]},"error":{"type":"string","enum":["Bad Request"]},"code":{"type":"string","enum":["idempotency_key_invalid","idempotency_key_reused"]},"message":{"type":"string"}}}}}},"401":{"description":"Missing or unrecognised API key.","content":{"application/json":{"schema":{"description":"Missing or unrecognised API key.","type":"object","properties":{"statusCode":{"type":"integer","enum":[401]},"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Insufficient credits to start the batch.","content":{"application/json":{"schema":{"description":"Insufficient credits to start the batch.","type":"object","properties":{"statusCode":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"get":{"summary":"Get bulk email results","tags":["Email Enrichment"],"description":"Check the status and collect the results of a bulk email task.\n\nPolling does not consume credits.","parameters":[{"schema":{"type":"string"},"in":"query","name":"job_id","required":true,"description":"Task id returned by `POST /email/find/bulk`."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/phone/find/single":{"post":{"summary":"Find a mobile number","tags":["Phone Enrichment"],"description":"Find a direct mobile number for a person.\n\nProvide **any one** of:\n• `linkedin_profile_url` or `linkedin_id` (most accurate)\n• `email`\n• a **name** (`first_name` or `full_name`) **and** a **company** (`company_name` or `company_domain`)\n\n`job_title` and `city` are optional and sharpen the match on common names.\n\n**10 credits**, charged only when a number is found.","requestBody":{"content":{"application/json":{"schema":{"type":"object","anyOf":[{"required":["linkedin_id"]},{"required":["linkedin_profile_url"]},{"required":["email"]},{"allOf":[{"anyOf":[{"required":["first_name"]},{"required":["full_name"]}]},{"anyOf":[{"required":["company_name"]},{"required":["company_domain"]}]}]}],"properties":{"linkedin_id":{"type":"string","description":"LinkedIn numeric member id (strongest signal, sufficient on its own)"},"first_name":{"type":"string","description":"Pair with a company signal, or omit in favor of full_name"},"last_name":{"type":"string","description":"Optional, may be omitted or empty"},"full_name":{"type":"string","description":"Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name"},"company_name":{"type":"string","description":"Required alongside a name signal (provide this OR company_domain)"},"company_domain":{"type":"string","description":"Company domain without protocol or @ (provide this OR company_name)"},"email":{"type":"string","description":"Known email, sufficient on its own; also boosts match precision when combined with other signals"},"job_title":{"type":"string","description":"Optional, disambiguates same-name matches at the same company"},"city":{"type":"string","description":"Optional, disambiguates same-name matches across regions"},"linkedin_profile_url":{"type":"string","format":"uri","description":"Full LinkedIn profile URL (sufficient on its own)"},"custom":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/phone/find/bulk":{"post":{"summary":"Find mobile numbers in bulk","tags":["Phone Enrichment"],"description":"Find up to 100 mobile numbers in one call. Returns a task id straight away; results arrive later.\n\n• Supply `webhook_url` and the results are POSTed there when the batch finishes.\n• Or poll `GET /phone/find/bulk?job_id=<task_id>` whenever you like.\n\n**10 credits per number found.** Send an `Idempotency-Key` header to make retries safe for 24h.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","items":{"type":"object","anyOf":[{"required":["linkedin_id"]},{"required":["linkedin_profile_url"]},{"required":["email"]},{"allOf":[{"anyOf":[{"required":["first_name"]},{"required":["full_name"]}]},{"anyOf":[{"required":["company_name"]},{"required":["company_domain"]}]}]}],"properties":{"linkedin_id":{"type":"string","description":"LinkedIn numeric member id (strongest signal, sufficient on its own)"},"first_name":{"type":"string","description":"Pair with a company signal, or omit in favor of full_name"},"last_name":{"type":"string","description":"Optional, may be omitted or empty"},"full_name":{"type":"string","description":"Alternative to first_name + last_name. Split on whitespace; everything after the first token becomes the last name"},"company_name":{"type":"string","description":"Required alongside a name signal (provide this OR company_domain)"},"company_domain":{"type":"string","description":"Company domain without protocol or @ (provide this OR company_name)"},"email":{"type":"string","description":"Known email, sufficient on its own; also boosts match precision when combined with other signals"},"job_title":{"type":"string","description":"Optional, disambiguates same-name matches at the same company"},"city":{"type":"string","description":"Optional, disambiguates same-name matches across regions"},"linkedin_profile_url":{"type":"string","format":"uri","description":"Full LinkedIn profile URL (sufficient on its own)"},"custom":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata echoed back verbatim in the per-lead result and webhook payload"}}},"minItems":1,"maxItems":100},"webhook_url":{"type":"string","format":"uri","description":"Optional destination URL for the completion callback. When omitted, poll GET /phone/find/bulk?job_id=... for results."}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]+$"},"in":"header","name":"idempotency-key","required":false,"description":"Optional. Per-submission UUID (recommended) so client-side retries on network blips don't create duplicate tasks or extra charges. Replay window: 24h."}],"responses":{"202":{"description":"Task accepted (or idempotent replay of an earlier submission).","content":{"application/json":{"schema":{"description":"Task accepted (or idempotent replay of an earlier submission).","type":"object","properties":{"taskId":{"type":"string","description":"Mongo ObjectId of the durable search task."},"status":{"type":"string","enum":["queued"]},"total":{"type":"integer","description":"Number of lead requests queued."}}}}}},"400":{"description":"Validation error. `code` discriminates the specific cause: `idempotency_key_invalid` (bad header format) or `idempotency_key_reused` (same key, different body within 24h).","content":{"application/json":{"schema":{"description":"Validation error. `code` discriminates the specific cause: `idempotency_key_invalid` (bad header format) or `idempotency_key_reused` (same key, different body within 24h).","type":"object","properties":{"statusCode":{"type":"integer","enum":[400]},"error":{"type":"string","enum":["Bad Request"]},"code":{"type":"string","enum":["idempotency_key_invalid","idempotency_key_reused"]},"message":{"type":"string"}}}}}},"401":{"description":"Missing or unrecognised API key.","content":{"application/json":{"schema":{"description":"Missing or unrecognised API key.","type":"object","properties":{"statusCode":{"type":"integer","enum":[401]},"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Insufficient credits to start the batch.","content":{"application/json":{"schema":{"description":"Insufficient credits to start the batch.","type":"object","properties":{"statusCode":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"get":{"summary":"Get bulk phone results","tags":["Phone Enrichment"],"description":"Check the status and collect the results of a bulk phone task.\n\nPolling does not consume credits.","parameters":[{"schema":{"type":"string"},"in":"query","name":"job_id","required":true,"description":"Task id returned by `POST /phone/find/bulk`."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/find/domain":{"post":{"summary":"Find emails by company domain","tags":["Email Enrichment"],"description":"Find the professional emails Scalelist knows at a company, with no names needed.\n\nProvide `domain`, or `company` to look the domain up for you. `limit` caps how many come back (default 10, max 100).\n\n**1 credit per email returned.**","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Company domain to search (without @). Optional if `company` is provided."},"company":{"type":"string","description":"Company name. Used to look up the domain when `domain` is not supplied."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of emails to return"},"webhook_url":{"type":"string","format":"uri","description":"Optional delivery target for async completion"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/people/search":{"post":{"summary":"Search for people","tags":["People Search"],"description":"Build an audience: find people by job title, seniority, industry, location, company and more.\n\nAt least one filter is required. Page through results with `page`.\n\n**How filters combine.** Values inside one list are OR; separate fields are AND. So `industries: [\"Banking\", \"Insurance\"]` matches either, and adding `seniority` narrows that set rather than widening it. Locations behave the same way across city, state and country: `[{city: \"Paris\"}, {country: \"Germany\"}]` means Paris **or** Germany, never both at once.\n\n**1 credit per profile returned**, up to 100 per page. Page size is capped to your remaining balance, so 20 credits returns at most 20 profiles.\n\nTip: size your audience first with `POST /people/count`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to match (OR logic). Free text, e.g. [\"CTO\", \"VP of Engineering\"]."},"job_functions":{"type":"array","items":{"type":"string"},"description":"Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership."},"seniority":{"type":"array","items":{"type":"string"},"description":"Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern."},"locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location value at the chosen granularity, e.g. \"San Francisco\", \"California\", \"United States\"."},"country":{"type":"string","description":"City entries only: the country the city is in, e.g. { type: \"city\", value: \"Toronto\", country: \"Canada\" }. Removes same-name places in other countries (\"Toronto\" otherwise also matches Trento, Italy)."}}},"description":"Locations with explicit granularity (OR logic). Each entry: { type: \"city\"|\"state\"|\"country\", value, country? }."},"exclude_locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location to exclude at the chosen granularity."}}},"description":"Locations to exclude, same shape as `locations`. Example: \"US except California\"."},"industries":{"type":"array","items":{"type":"string"},"description":"Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ..."},"company_size":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"description":"Minimum employee count (inclusive)"},"max":{"type":"integer","minimum":0,"description":"Maximum employee count (inclusive)"}},"description":"Employee count range: { min, max }. Either bound optional."},"recently_changed_jobs":{"type":"boolean","description":"Only people whose current role started in roughly the last 3 months. High-intent buying signal."},"min_followers":{"type":"integer","minimum":0,"description":"Only people with at least this many LinkedIn followers."},"keyword":{"type":"string","deprecated":true,"description":"A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead."},"keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords, OR logic: a person matches if ANY term appears on their profile."},"exclude_keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords to exclude: a person is dropped if any term appears on their profile."},"open_to":{"type":"array","items":{"type":"string","enum":["hiring","open_to_work","volunteering"]},"description":"Person-level buying signals from their own profile badges, e.g. [\"hiring\"]."},"years_in_current_role":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Years at the current employer: { min, max }. Either bound optional."},"years_of_experience":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Total years of professional experience: { min, max }. Either bound optional."},"skills":{"type":"array","items":{"type":"string"},"description":"Skills listed on the profile (OR logic), e.g. [\"Salesforce\", \"Python\"]. Search results do not show skills."},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the person speaks (OR logic), e.g. [\"French\", \"German\"]."},"schools":{"type":"array","items":{"type":"string"},"description":"Schools or universities attended (OR logic), e.g. [\"Stanford\", \"HEC Paris\"]."},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications held (OR logic), e.g. [\"PMP\"]. Search results do not show certifications."},"companies":{"type":"array","items":{"type":"string"},"description":"Company names (OR logic), e.g. [\"Salesforce\", \"HubSpot\"]."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains (OR logic), e.g. [\"stripe.com\"]."},"past_companies":{"type":"array","items":{"type":"string"},"description":"Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role."},"past_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held in a past role (OR logic), e.g. [\"Founder\"]. With past_companies / past_seniority, all must hold for the SAME past role."},"past_seniority":{"type":"array","items":{"type":"string"},"description":"Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. [\"Germany\", \"USA\"]."},"company_type":{"type":"array","items":{"type":"string"},"description":"Company category filter, e.g. [\"public company\"] or [\"non-profit\"] (OR logic)."},"exclude_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to exclude from results."},"exclude_companies":{"type":"array","items":{"type":"string"},"description":"Company names to exclude from results."},"exclude_company_domains":{"type":"array","items":{"type":"string"},"description":"Company websites to exclude from results, e.g. [\"stripe.com\"]."},"exclude_industries":{"type":"array","items":{"type":"string"},"description":"Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422."},"exclude_seniority":{"type":"array","items":{"type":"string"},"description":"Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_job_functions":{"type":"array","items":{"type":"string"},"description":"Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422."},"exclude_past_companies":{"type":"array","items":{"type":"string"},"description":"Drop anyone who previously worked at any of these companies, by name."},"exclude_past_job_titles":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these job titles in a past role."},"exclude_past_seniority":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code."},"exclude_skills":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these skills."},"exclude_languages":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these languages."},"exclude_schools":{"type":"array","items":{"type":"string"},"description":"Drop anyone who attended any of these schools."},"exclude_certifications":{"type":"array","items":{"type":"string"},"description":"Drop anyone who holds any of these certifications."},"page":{"type":"integer","minimum":1,"default":1},"page_size":{"type":"integer","minimum":1,"maximum":100,"description":"Profiles per page (max 100). Billed 1 credit per profile returned."},"offset":{"type":"integer","minimum":0,"description":"Absolute row offset for the window; overrides page when set. Exactly [offset, offset + page_size) is returned and billed."},"cursor":{"type":"string","description":"Bookmark returned as `next_cursor` by the previous page. Pass it when walking pages sequentially, since it is the cheapest and most stable way to page. Without it, page/offset addressing still works."}},"allOf":[{"title":"Person attributes","description":"Filter people by their personal profile: job title / function / seniority, industry, location, company size, keyword, and recency signals.","type":"object","properties":{"job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to match (OR logic). Free text, e.g. [\"CTO\", \"VP of Engineering\"]."},"job_functions":{"type":"array","items":{"type":"string"},"description":"Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership."},"seniority":{"type":"array","items":{"type":"string"},"description":"Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern."},"locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location value at the chosen granularity, e.g. \"San Francisco\", \"California\", \"United States\"."},"country":{"type":"string","description":"City entries only: the country the city is in, e.g. { type: \"city\", value: \"Toronto\", country: \"Canada\" }. Removes same-name places in other countries (\"Toronto\" otherwise also matches Trento, Italy)."}}},"description":"Locations with explicit granularity (OR logic). Each entry: { type: \"city\"|\"state\"|\"country\", value, country? }."},"exclude_locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location to exclude at the chosen granularity."}}},"description":"Locations to exclude, same shape as `locations`. Example: \"US except California\"."},"industries":{"type":"array","items":{"type":"string"},"description":"Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ..."},"company_size":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"description":"Minimum employee count (inclusive)"},"max":{"type":"integer","minimum":0,"description":"Maximum employee count (inclusive)"}},"description":"Employee count range: { min, max }. Either bound optional."},"recently_changed_jobs":{"type":"boolean","description":"Only people whose current role started in roughly the last 3 months. High-intent buying signal."},"min_followers":{"type":"integer","minimum":0,"description":"Only people with at least this many LinkedIn followers."},"keyword":{"type":"string","deprecated":true,"description":"A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead."},"keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords, OR logic: a person matches if ANY term appears on their profile."},"exclude_keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords to exclude: a person is dropped if any term appears on their profile."},"open_to":{"type":"array","items":{"type":"string","enum":["hiring","open_to_work","volunteering"]},"description":"Person-level buying signals from their own profile badges, e.g. [\"hiring\"]."},"years_in_current_role":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Years at the current employer: { min, max }. Either bound optional."},"years_of_experience":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Total years of professional experience: { min, max }. Either bound optional."},"skills":{"type":"array","items":{"type":"string"},"description":"Skills listed on the profile (OR logic), e.g. [\"Salesforce\", \"Python\"]. Search results do not show skills."},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the person speaks (OR logic), e.g. [\"French\", \"German\"]."},"schools":{"type":"array","items":{"type":"string"},"description":"Schools or universities attended (OR logic), e.g. [\"Stanford\", \"HEC Paris\"]."},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications held (OR logic), e.g. [\"PMP\"]. Search results do not show certifications."}}},{"title":"Company targeting","description":"Restrict results to people at specific companies or company domains.","type":"object","properties":{"companies":{"type":"array","items":{"type":"string"},"description":"Company names (OR logic), e.g. [\"Salesforce\", \"HubSpot\"]."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains (OR logic), e.g. [\"stripe.com\"]."},"past_companies":{"type":"array","items":{"type":"string"},"description":"Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role."},"past_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held in a past role (OR logic), e.g. [\"Founder\"]. With past_companies / past_seniority, all must hold for the SAME past role."},"past_seniority":{"type":"array","items":{"type":"string"},"description":"Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. [\"Germany\", \"USA\"]."},"company_type":{"type":"array","items":{"type":"string"},"description":"Company category filter, e.g. [\"public company\"] or [\"non-profit\"] (OR logic)."}}},{"title":"Exclusions","description":"Remove specific titles or companies from the result set.","type":"object","properties":{"exclude_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to exclude from results."},"exclude_companies":{"type":"array","items":{"type":"string"},"description":"Company names to exclude from results."},"exclude_company_domains":{"type":"array","items":{"type":"string"},"description":"Company websites to exclude from results, e.g. [\"stripe.com\"]."},"exclude_industries":{"type":"array","items":{"type":"string"},"description":"Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422."},"exclude_seniority":{"type":"array","items":{"type":"string"},"description":"Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_job_functions":{"type":"array","items":{"type":"string"},"description":"Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422."},"exclude_past_companies":{"type":"array","items":{"type":"string"},"description":"Drop anyone who previously worked at any of these companies, by name."},"exclude_past_job_titles":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these job titles in a past role."},"exclude_past_seniority":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code."},"exclude_skills":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these skills."},"exclude_languages":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these languages."},"exclude_schools":{"type":"array","items":{"type":"string"},"description":"Drop anyone who attended any of these schools."},"exclude_certifications":{"type":"array","items":{"type":"string"},"description":"Drop anyone who holds any of these certifications."}}},{"title":"Pagination","description":"Page + page size for the synchronous search.","type":"object","properties":{"page":{"type":"integer","minimum":1,"default":1},"page_size":{"type":"integer","minimum":1,"maximum":100,"description":"Profiles per page (max 100). Billed 1 credit per profile returned."},"offset":{"type":"integer","minimum":0,"description":"Absolute row offset for the window; overrides page when set. Exactly [offset, offset + page_size) is returned and billed."},"cursor":{"type":"string","description":"Bookmark returned as `next_cursor` by the previous page. Pass it when walking pages sequentially, since it is the cheapest and most stable way to page. Without it, page/offset addressing still works."}}}]}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/people/count":{"post":{"summary":"Count matching people","tags":["People Search"],"description":"See how many people match your filters before you pay for any profiles.\n\nTakes the same filters as `POST /people/search`, minus pagination.\n\nCosts **1 credit per call**, however large the audience — sizing an\naudience of 40,000 people still costs 1. `credits_charged` on the\nresponse says what you paid.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to match (OR logic). Free text, e.g. [\"CTO\", \"VP of Engineering\"]."},"job_functions":{"type":"array","items":{"type":"string"},"description":"Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership."},"seniority":{"type":"array","items":{"type":"string"},"description":"Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern."},"locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location value at the chosen granularity, e.g. \"San Francisco\", \"California\", \"United States\"."},"country":{"type":"string","description":"City entries only: the country the city is in, e.g. { type: \"city\", value: \"Toronto\", country: \"Canada\" }. Removes same-name places in other countries (\"Toronto\" otherwise also matches Trento, Italy)."}}},"description":"Locations with explicit granularity (OR logic). Each entry: { type: \"city\"|\"state\"|\"country\", value, country? }."},"exclude_locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location to exclude at the chosen granularity."}}},"description":"Locations to exclude, same shape as `locations`. Example: \"US except California\"."},"industries":{"type":"array","items":{"type":"string"},"description":"Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ..."},"company_size":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"description":"Minimum employee count (inclusive)"},"max":{"type":"integer","minimum":0,"description":"Maximum employee count (inclusive)"}},"description":"Employee count range: { min, max }. Either bound optional."},"recently_changed_jobs":{"type":"boolean","description":"Only people whose current role started in roughly the last 3 months. High-intent buying signal."},"min_followers":{"type":"integer","minimum":0,"description":"Only people with at least this many LinkedIn followers."},"keyword":{"type":"string","deprecated":true,"description":"A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead."},"keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords, OR logic: a person matches if ANY term appears on their profile."},"exclude_keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords to exclude: a person is dropped if any term appears on their profile."},"open_to":{"type":"array","items":{"type":"string","enum":["hiring","open_to_work","volunteering"]},"description":"Person-level buying signals from their own profile badges, e.g. [\"hiring\"]."},"years_in_current_role":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Years at the current employer: { min, max }. Either bound optional."},"years_of_experience":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Total years of professional experience: { min, max }. Either bound optional."},"skills":{"type":"array","items":{"type":"string"},"description":"Skills listed on the profile (OR logic), e.g. [\"Salesforce\", \"Python\"]. Search results do not show skills."},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the person speaks (OR logic), e.g. [\"French\", \"German\"]."},"schools":{"type":"array","items":{"type":"string"},"description":"Schools or universities attended (OR logic), e.g. [\"Stanford\", \"HEC Paris\"]."},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications held (OR logic), e.g. [\"PMP\"]. Search results do not show certifications."},"companies":{"type":"array","items":{"type":"string"},"description":"Company names (OR logic), e.g. [\"Salesforce\", \"HubSpot\"]."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains (OR logic), e.g. [\"stripe.com\"]."},"past_companies":{"type":"array","items":{"type":"string"},"description":"Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role."},"past_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held in a past role (OR logic), e.g. [\"Founder\"]. With past_companies / past_seniority, all must hold for the SAME past role."},"past_seniority":{"type":"array","items":{"type":"string"},"description":"Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. [\"Germany\", \"USA\"]."},"company_type":{"type":"array","items":{"type":"string"},"description":"Company category filter, e.g. [\"public company\"] or [\"non-profit\"] (OR logic)."},"exclude_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to exclude from results."},"exclude_companies":{"type":"array","items":{"type":"string"},"description":"Company names to exclude from results."},"exclude_company_domains":{"type":"array","items":{"type":"string"},"description":"Company websites to exclude from results, e.g. [\"stripe.com\"]."},"exclude_industries":{"type":"array","items":{"type":"string"},"description":"Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422."},"exclude_seniority":{"type":"array","items":{"type":"string"},"description":"Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_job_functions":{"type":"array","items":{"type":"string"},"description":"Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422."},"exclude_past_companies":{"type":"array","items":{"type":"string"},"description":"Drop anyone who previously worked at any of these companies, by name."},"exclude_past_job_titles":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these job titles in a past role."},"exclude_past_seniority":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code."},"exclude_skills":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these skills."},"exclude_languages":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these languages."},"exclude_schools":{"type":"array","items":{"type":"string"},"description":"Drop anyone who attended any of these schools."},"exclude_certifications":{"type":"array","items":{"type":"string"},"description":"Drop anyone who holds any of these certifications."}},"allOf":[{"title":"Person attributes","description":"Filter people by their personal profile: job title / function / seniority, industry, location, company size, keyword, and recency signals.","type":"object","properties":{"job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to match (OR logic). Free text, e.g. [\"CTO\", \"VP of Engineering\"]."},"job_functions":{"type":"array","items":{"type":"string"},"description":"Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership."},"seniority":{"type":"array","items":{"type":"string"},"description":"Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern."},"locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location value at the chosen granularity, e.g. \"San Francisco\", \"California\", \"United States\"."},"country":{"type":"string","description":"City entries only: the country the city is in, e.g. { type: \"city\", value: \"Toronto\", country: \"Canada\" }. Removes same-name places in other countries (\"Toronto\" otherwise also matches Trento, Italy)."}}},"description":"Locations with explicit granularity (OR logic). Each entry: { type: \"city\"|\"state\"|\"country\", value, country? }."},"exclude_locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location to exclude at the chosen granularity."}}},"description":"Locations to exclude, same shape as `locations`. Example: \"US except California\"."},"industries":{"type":"array","items":{"type":"string"},"description":"Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ..."},"company_size":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"description":"Minimum employee count (inclusive)"},"max":{"type":"integer","minimum":0,"description":"Maximum employee count (inclusive)"}},"description":"Employee count range: { min, max }. Either bound optional."},"recently_changed_jobs":{"type":"boolean","description":"Only people whose current role started in roughly the last 3 months. High-intent buying signal."},"min_followers":{"type":"integer","minimum":0,"description":"Only people with at least this many LinkedIn followers."},"keyword":{"type":"string","deprecated":true,"description":"A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead."},"keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords, OR logic: a person matches if ANY term appears on their profile."},"exclude_keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords to exclude: a person is dropped if any term appears on their profile."},"open_to":{"type":"array","items":{"type":"string","enum":["hiring","open_to_work","volunteering"]},"description":"Person-level buying signals from their own profile badges, e.g. [\"hiring\"]."},"years_in_current_role":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Years at the current employer: { min, max }. Either bound optional."},"years_of_experience":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Total years of professional experience: { min, max }. Either bound optional."},"skills":{"type":"array","items":{"type":"string"},"description":"Skills listed on the profile (OR logic), e.g. [\"Salesforce\", \"Python\"]. Search results do not show skills."},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the person speaks (OR logic), e.g. [\"French\", \"German\"]."},"schools":{"type":"array","items":{"type":"string"},"description":"Schools or universities attended (OR logic), e.g. [\"Stanford\", \"HEC Paris\"]."},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications held (OR logic), e.g. [\"PMP\"]. Search results do not show certifications."}}},{"title":"Company targeting","description":"Restrict results to people at specific companies or company domains.","type":"object","properties":{"companies":{"type":"array","items":{"type":"string"},"description":"Company names (OR logic), e.g. [\"Salesforce\", \"HubSpot\"]."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains (OR logic), e.g. [\"stripe.com\"]."},"past_companies":{"type":"array","items":{"type":"string"},"description":"Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role."},"past_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held in a past role (OR logic), e.g. [\"Founder\"]. With past_companies / past_seniority, all must hold for the SAME past role."},"past_seniority":{"type":"array","items":{"type":"string"},"description":"Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. [\"Germany\", \"USA\"]."},"company_type":{"type":"array","items":{"type":"string"},"description":"Company category filter, e.g. [\"public company\"] or [\"non-profit\"] (OR logic)."}}},{"title":"Exclusions","description":"Remove specific titles or companies from the result set.","type":"object","properties":{"exclude_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to exclude from results."},"exclude_companies":{"type":"array","items":{"type":"string"},"description":"Company names to exclude from results."},"exclude_company_domains":{"type":"array","items":{"type":"string"},"description":"Company websites to exclude from results, e.g. [\"stripe.com\"]."},"exclude_industries":{"type":"array","items":{"type":"string"},"description":"Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422."},"exclude_seniority":{"type":"array","items":{"type":"string"},"description":"Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_job_functions":{"type":"array","items":{"type":"string"},"description":"Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422."},"exclude_past_companies":{"type":"array","items":{"type":"string"},"description":"Drop anyone who previously worked at any of these companies, by name."},"exclude_past_job_titles":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these job titles in a past role."},"exclude_past_seniority":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code."},"exclude_skills":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these skills."},"exclude_languages":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these languages."},"exclude_schools":{"type":"array","items":{"type":"string"},"description":"Drop anyone who attended any of these schools."},"exclude_certifications":{"type":"array","items":{"type":"string"},"description":"Drop anyone who holds any of these certifications."}}}]}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/people/industries/resolve":{"post":{"summary":"Look up industry names","tags":["People Search"],"description":"Check which industry categories a search will actually match, before you run it.\n\nEach word comes back as one of:\n• `resolved`: with the exact category names a search will filter on\n• `unresolved`: no matching category, so a search would match it as profile text instead; `suggestions` lists nearby real categories\n• `unverified`: the lookup failed, try again","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["industries"],"properties":{"industries":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20}}}}},"required":true},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/people/search/bulk":{"post":{"summary":"Search for people in bulk","tags":["People Search"],"description":"Pull a whole audience across many pages in one call. Returns a task id straight away; results arrive later.\n\nSet `start_page`, and `end_page` to stop at a given page; omit it to pull everything that matches.\n\n• The merged results are POSTed to your `webhook_url` on completion.\n• Or poll `GET /people/search/bulk?job_id=<task_id>` whenever you like.\n\n**1 credit per profile found.** Send an `Idempotency-Key` header to make retries safe for 24h.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["metadata"],"properties":{"job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to match (OR logic). Free text, e.g. [\"CTO\", \"VP of Engineering\"]."},"job_functions":{"type":"array","items":{"type":"string"},"description":"Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership."},"seniority":{"type":"array","items":{"type":"string"},"description":"Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern."},"locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location value at the chosen granularity, e.g. \"San Francisco\", \"California\", \"United States\"."},"country":{"type":"string","description":"City entries only: the country the city is in, e.g. { type: \"city\", value: \"Toronto\", country: \"Canada\" }. Removes same-name places in other countries (\"Toronto\" otherwise also matches Trento, Italy)."}}},"description":"Locations with explicit granularity (OR logic). Each entry: { type: \"city\"|\"state\"|\"country\", value, country? }."},"exclude_locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location to exclude at the chosen granularity."}}},"description":"Locations to exclude, same shape as `locations`. Example: \"US except California\"."},"industries":{"type":"array","items":{"type":"string"},"description":"Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ..."},"company_size":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"description":"Minimum employee count (inclusive)"},"max":{"type":"integer","minimum":0,"description":"Maximum employee count (inclusive)"}},"description":"Employee count range: { min, max }. Either bound optional."},"recently_changed_jobs":{"type":"boolean","description":"Only people whose current role started in roughly the last 3 months. High-intent buying signal."},"min_followers":{"type":"integer","minimum":0,"description":"Only people with at least this many LinkedIn followers."},"keyword":{"type":"string","deprecated":true,"description":"A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead."},"keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords, OR logic: a person matches if ANY term appears on their profile."},"exclude_keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords to exclude: a person is dropped if any term appears on their profile."},"open_to":{"type":"array","items":{"type":"string","enum":["hiring","open_to_work","volunteering"]},"description":"Person-level buying signals from their own profile badges, e.g. [\"hiring\"]."},"years_in_current_role":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Years at the current employer: { min, max }. Either bound optional."},"years_of_experience":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Total years of professional experience: { min, max }. Either bound optional."},"skills":{"type":"array","items":{"type":"string"},"description":"Skills listed on the profile (OR logic), e.g. [\"Salesforce\", \"Python\"]. Search results do not show skills."},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the person speaks (OR logic), e.g. [\"French\", \"German\"]."},"schools":{"type":"array","items":{"type":"string"},"description":"Schools or universities attended (OR logic), e.g. [\"Stanford\", \"HEC Paris\"]."},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications held (OR logic), e.g. [\"PMP\"]. Search results do not show certifications."},"companies":{"type":"array","items":{"type":"string"},"description":"Company names (OR logic), e.g. [\"Salesforce\", \"HubSpot\"]."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains (OR logic), e.g. [\"stripe.com\"]."},"past_companies":{"type":"array","items":{"type":"string"},"description":"Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role."},"past_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held in a past role (OR logic), e.g. [\"Founder\"]. With past_companies / past_seniority, all must hold for the SAME past role."},"past_seniority":{"type":"array","items":{"type":"string"},"description":"Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. [\"Germany\", \"USA\"]."},"company_type":{"type":"array","items":{"type":"string"},"description":"Company category filter, e.g. [\"public company\"] or [\"non-profit\"] (OR logic)."},"exclude_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to exclude from results."},"exclude_companies":{"type":"array","items":{"type":"string"},"description":"Company names to exclude from results."},"exclude_company_domains":{"type":"array","items":{"type":"string"},"description":"Company websites to exclude from results, e.g. [\"stripe.com\"]."},"exclude_industries":{"type":"array","items":{"type":"string"},"description":"Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422."},"exclude_seniority":{"type":"array","items":{"type":"string"},"description":"Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_job_functions":{"type":"array","items":{"type":"string"},"description":"Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422."},"exclude_past_companies":{"type":"array","items":{"type":"string"},"description":"Drop anyone who previously worked at any of these companies, by name."},"exclude_past_job_titles":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these job titles in a past role."},"exclude_past_seniority":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code."},"exclude_skills":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these skills."},"exclude_languages":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these languages."},"exclude_schools":{"type":"array","items":{"type":"string"},"description":"Drop anyone who attended any of these schools."},"exclude_certifications":{"type":"array","items":{"type":"string"},"description":"Drop anyone who holds any of these certifications."},"metadata":{"type":"object","required":["webhook_url"],"properties":{"webhook_url":{"type":"string","format":"uri","description":"Destination URL for the completion callback"},"start_page":{"type":"integer","minimum":1,"default":1,"description":"First page to fetch"},"end_page":{"type":"integer","minimum":1,"description":"Last page to fetch (optional). When omitted, pages through to the last page sized from the result total."},"page_size":{"type":"integer","minimum":1,"maximum":100,"description":"Profiles per page (max 100)"},"skip_first":{"type":"integer","minimum":0,"maximum":100,"description":"Skip (and do not bill) the first N profiles of start_page, for resuming a run that stopped mid-page without re-delivering the overlap."},"max_results":{"type":"integer","minimum":1,"description":"Deliver (and bill) at most this many profiles across the whole run, trimming the final page, for an exact target instead of a whole-page multiple."}}},"custom":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata echoed back verbatim in the webhook payload and poll response"}},"allOf":[{"title":"Person attributes","description":"Filter people by their personal profile: job title / function / seniority, industry, location, company size, keyword, and recency signals.","type":"object","properties":{"job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to match (OR logic). Free text, e.g. [\"CTO\", \"VP of Engineering\"]."},"job_functions":{"type":"array","items":{"type":"string"},"description":"Functional areas (OR logic). Canonical values: Operations, Business Development, Sales, Education, Engineering, Healthcare Services, Information Technology, Administrative, Arts and Design, Customer Success and Support, Finance, Community and Social Services, Media and Communication, Accounting, Marketing, Human Resources, Research, Program and Project Management, Legal, Military and Protective Services, Consulting, Entrepreneurship, Real Estate, Quality Assurance, Purchasing, Product Management, Leadership."},"seniority":{"type":"array","items":{"type":"string"},"description":"Career levels (OR logic). Canonical values: Owner / Founder, CXO, Partner, VP, Head, Director, Manager, Senior, Entry, Intern."},"locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location value at the chosen granularity, e.g. \"San Francisco\", \"California\", \"United States\"."},"country":{"type":"string","description":"City entries only: the country the city is in, e.g. { type: \"city\", value: \"Toronto\", country: \"Canada\" }. Removes same-name places in other countries (\"Toronto\" otherwise also matches Trento, Italy)."}}},"description":"Locations with explicit granularity (OR logic). Each entry: { type: \"city\"|\"state\"|\"country\", value, country? }."},"exclude_locations":{"type":"array","items":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["city","state","country"],"description":"Granularity: city | state | country"},"value":{"type":"string","description":"Location to exclude at the chosen granularity."}}},"description":"Locations to exclude, same shape as `locations`. Example: \"US except California\"."},"industries":{"type":"array","items":{"type":"string"},"description":"Industries (OR logic). Free text; canonical Scalelist values recommended, e.g. Defense & Space, Computer Hardware, Computer Software, Computer Networking, Internet, Semiconductors, ..."},"company_size":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"description":"Minimum employee count (inclusive)"},"max":{"type":"integer","minimum":0,"description":"Maximum employee count (inclusive)"}},"description":"Employee count range: { min, max }. Either bound optional."},"recently_changed_jobs":{"type":"boolean","description":"Only people whose current role started in roughly the last 3 months. High-intent buying signal."},"min_followers":{"type":"integer","minimum":0,"description":"Only people with at least this many LinkedIn followers."},"keyword":{"type":"string","deprecated":true,"description":"A single free-text term matched anywhere on the profile. To match several terms with OR logic, use `keywords` (plural) instead."},"keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords, OR logic: a person matches if ANY term appears on their profile."},"exclude_keywords":{"type":"array","items":{"type":"string"},"description":"Free-text keywords to exclude: a person is dropped if any term appears on their profile."},"open_to":{"type":"array","items":{"type":"string","enum":["hiring","open_to_work","volunteering"]},"description":"Person-level buying signals from their own profile badges, e.g. [\"hiring\"]."},"years_in_current_role":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Years at the current employer: { min, max }. Either bound optional."},"years_of_experience":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Minimum years (inclusive)"},"max":{"type":"number","minimum":0,"description":"Maximum years (inclusive)"}},"description":"Total years of professional experience: { min, max }. Either bound optional."},"skills":{"type":"array","items":{"type":"string"},"description":"Skills listed on the profile (OR logic), e.g. [\"Salesforce\", \"Python\"]. Search results do not show skills."},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the person speaks (OR logic), e.g. [\"French\", \"German\"]."},"schools":{"type":"array","items":{"type":"string"},"description":"Schools or universities attended (OR logic), e.g. [\"Stanford\", \"HEC Paris\"]."},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications held (OR logic), e.g. [\"PMP\"]. Search results do not show certifications."}}},{"title":"Company targeting","description":"Restrict results to people at specific companies or company domains.","type":"object","properties":{"companies":{"type":"array","items":{"type":"string"},"description":"Company names (OR logic), e.g. [\"Salesforce\", \"HubSpot\"]."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains (OR logic), e.g. [\"stripe.com\"]."},"past_companies":{"type":"array","items":{"type":"string"},"description":"Companies the person previously worked at, by name (OR logic). With past_job_titles / past_seniority, all must hold for the SAME past role."},"past_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held in a past role (OR logic), e.g. [\"Founder\"]. With past_companies / past_seniority, all must hold for the SAME past role."},"past_seniority":{"type":"array","items":{"type":"string"},"description":"Career level of a past role (OR logic). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Country where the current employer is headquartered (OR logic). Full English name or ISO alpha-3 code, e.g. [\"Germany\", \"USA\"]."},"company_type":{"type":"array","items":{"type":"string"},"description":"Company category filter, e.g. [\"public company\"] or [\"non-profit\"] (OR logic)."}}},{"title":"Exclusions","description":"Remove specific titles or companies from the result set.","type":"object","properties":{"exclude_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles to exclude from results."},"exclude_companies":{"type":"array","items":{"type":"string"},"description":"Company names to exclude from results."},"exclude_company_domains":{"type":"array","items":{"type":"string"},"description":"Company websites to exclude from results, e.g. [\"stripe.com\"]."},"exclude_industries":{"type":"array","items":{"type":"string"},"description":"Industries to exclude (current employer). Resolved like `industries`; a word with no matching industry is refused with 422."},"exclude_seniority":{"type":"array","items":{"type":"string"},"description":"Career levels to exclude (current role). One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_job_functions":{"type":"array","items":{"type":"string"},"description":"Job functions to exclude (current role). Resolved like `job_functions`; a value with no matching function is refused with 422."},"exclude_past_companies":{"type":"array","items":{"type":"string"},"description":"Drop anyone who previously worked at any of these companies, by name."},"exclude_past_job_titles":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these job titles in a past role."},"exclude_past_seniority":{"type":"array","items":{"type":"string"},"description":"Drop anyone who held any of these career levels in a past role. One of: Owner / Partner, CXO, Vice President, Director, Experienced Manager, Entry Level Manager, Strategic, Senior, Entry Level, In Training."},"exclude_company_hq_countries":{"type":"array","items":{"type":"string"},"description":"Drop people whose current employer is headquartered in any of these countries. Full English name or ISO alpha-3 code."},"exclude_skills":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these skills."},"exclude_languages":{"type":"array","items":{"type":"string"},"description":"Drop anyone who lists any of these languages."},"exclude_schools":{"type":"array","items":{"type":"string"},"description":"Drop anyone who attended any of these schools."},"exclude_certifications":{"type":"array","items":{"type":"string"},"description":"Drop anyone who holds any of these certifications."}}},{"title":"Delivery","description":"Webhook + page-span envelope (kept separate from the search filters).","type":"object","required":["metadata"],"properties":{"metadata":{"type":"object","required":["webhook_url"],"properties":{"webhook_url":{"type":"string","format":"uri","description":"Destination URL for the completion callback"},"start_page":{"type":"integer","minimum":1,"default":1,"description":"First page to fetch"},"end_page":{"type":"integer","minimum":1,"description":"Last page to fetch (optional). When omitted, pages through to the last page sized from the result total."},"page_size":{"type":"integer","minimum":1,"maximum":100,"description":"Profiles per page (max 100)"},"skip_first":{"type":"integer","minimum":0,"maximum":100,"description":"Skip (and do not bill) the first N profiles of start_page, for resuming a run that stopped mid-page without re-delivering the overlap."},"max_results":{"type":"integer","minimum":1,"description":"Deliver (and bill) at most this many profiles across the whole run, trimming the final page, for an exact target instead of a whole-page multiple."}}},"custom":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata echoed back verbatim in the webhook payload and poll response"}}}]}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]+$"},"in":"header","name":"idempotency-key","required":false,"description":"Optional per-submission key so client retries don't create duplicate tasks. Replay window: 24h."}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"startPage":{"type":"integer"},"endPage":{"type":"integer","nullable":true}}}}}}}},"get":{"summary":"Get bulk people results","tags":["People Search"],"description":"Check the status and collect the merged results of a bulk people search.\n\nPolling does not consume credits; profiles were billed as they were found.","parameters":[{"schema":{"type":"string"},"in":"query","name":"job_id","required":true,"description":"Task id from `POST /people/search/bulk`."}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.scalelist.com"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Account Info","description":"Your profile, plan and credit balance."},{"name":"Email Enrichment","description":"Verified work emails, one at a time, in bulk, or every contact at a company."},{"name":"Phone Enrichment","description":"Direct mobile numbers, one at a time or in bulk."},{"name":"People Search","description":"Build a target audience by title, seniority, industry, location and company."}]}