---
title: "People Search"
method: POST
path: "/v3/people/search"
tags: ["People Enrichment"]
---

# People Search

`POST /v3/people/search`

Canonical V3 people lookup with all company, title, role, people, channel, and contact-detail filters.

## Request body

- object
  - `company_domain` string
  - `company_name` string
  - `linkedin_url` string — B2B company profile URL or slug.
  - `company_filters` object — Criteria-based company set. Supports the full Company Search filter family.
  - `people_filters` object — People-level filters for names, title/function/level, geography, profile URLs, headline/about-me/industry, languages, seniority, connection count, and channel availability. Canonical keys use the contact_* prefix (e.g. contact_linkedin_about_me); bare aliases such as about_me, headline, industry, job_function, and city are accepted. contact_job_function accepts short chips (Sales, Marketing, Finance, …) or full standard labels (Sales & Business Development, …); matching is exact after chip→label expansion and response rows always return the standard label. Multiple values in one array are OR'd; different people_filters keys in one request are AND'd. Keys the search cannot honor are echoed in interpreted_search.ignored_people_filters rather than silently dropped.
  - `title` string
  - `job_title` string
  - `titles` string[]
  - `roles` string[]
  - `query` string — Free-text people/title query.
  - `required_email` boolean — Only return people with email availability.
  - `required_mobile` boolean — Only return people with mobile availability.
  - `channels` string[] — Legacy alias for contactability requirements.
  - `channel_match` 'any' | 'all'
  - `include_company` boolean
  - `include_domain_intel` boolean
  - `include_contact_details` boolean — Opt in to paid raw email/mobile fields (alias — full_search). Bills 1 extra credit per returned email and 5 per returned mobile; base results are 1 credit per returned person. Search RPS / unmetered people-search plans cannot unlock email or mobile (403); unlocks require a credit-metered plan.
  - `include_email` boolean — When contact details are on, return and bill raw emails (+1 credit each). If neither include_email nor include_mobile is set, both default to true. If either flag is set, the omitted flag defaults to false (include_email=true alone is email-only).
  - `include_mobile` boolean — When contact details are on, return and bill raw mobiles (+5 credits each). Same default rules as include_email.
  - `confirm_credit_charge` boolean — Accepted for backwards compatibility; does not bypass RPS/unmetered unlock restrictions.
  - `limit` integer — Offset requests allow up to 10000 rows; cursor-based pages are capped at 50.
  - `cursor` string — Opaque signed next_cursor from the previous page. Send unchanged with the same filters, a limit no greater than 50, and offset 0.
  - `offset` integer

## Response `200`

People search results

- object
  - `message` string
  - `credits_consumed` number
  - `credit_preview` object
  - `people` object[]
    - `contact_linkedin_url` string, nullable
    - `contact_linkedin_username` string, nullable
    - `contact_first_name` string, nullable
    - `contact_last_name` string, nullable
    - `contact_full_name` string, nullable
    - `contact_email` string, nullable
    - `contact_email_domain` string, nullable
    - `contact_mobile_phone` string, nullable
    - `contact_direct_phone` string, nullable
    - `contact_linkedin_headline` string, nullable
    - `contact_linkedin_industry` string, nullable
    - `contact_linkedin_about_me` string, nullable
    - `contact_city` string, nullable
    - `contact_state` string, nullable
    - `contact_state_code` string, nullable
    - `contact_country` string, nullable
    - `contact_country_code` string, nullable
    - `contact_region` string, nullable
    - `contact_continent` string, nullable
    - `contact_job_title` string, nullable
    - `contact_job_function` string, nullable — Standard department label for the person's current role (e.g. Sales & Business Development). Filter requests may use short chips such as Sales; responses always return this standard label.
    - `contact_job_level` string, nullable
    - `contact_job_description` string, nullable
    - `contact_job_start_date` string, nullable
    - `contact_job_count` integer, nullable
    - `contact_persona` string, nullable
    - `contact_job_city` string, nullable
    - `contact_job_country` string, nullable
    - `contact_job_country_code` string, nullable
    - `contact_job_region` string, nullable
    - `contact_job_continent` string, nullable
    - `contact_job_state` string, nullable
    - `contact_job_state_code` string, nullable
    - `contact_company_name` string, nullable
    - `company_domain` string, nullable
    - `contact_education` string, nullable
    - `contact_skills` string, nullable
    - `contact_certifications` string, nullable
    - `contact_languages` string, nullable
    - `contact_websites` string, nullable
    - `seniority_score` integer, nullable
    - `has_email` boolean
    - `has_mobile_phone` boolean
    - `has_phone` boolean
    - `is_cio` boolean, nullable
    - `is_it_leader` boolean, nullable
    - `is_security` boolean, nullable
    - `is_revops` boolean, nullable
    - `is_recruiting` boolean, nullable
    - `is_engineering` boolean, nullable
    - `is_sales` boolean, nullable
    - `is_marketing` boolean, nullable
    - `is_operations` boolean, nullable
    - `contactability_score` integer, nullable
    - `profile_completeness_score` integer, nullable
    - `job_observation_count` integer, nullable
    - `distinct_company_count` integer, nullable
    - `followers` integer, nullable
    - `company` object, nullable
    - `domain_intel` object, nullable
    - `unlock` object, nullable
  - `companies` object[]
  - `count` integer
  - `returned_count` integer
  - `limit_applied` integer
  - `offset` integer
  - `has_more` boolean
  - `next_cursor` string, nullable
  - `metadata` object

## Other responses

- `400` — Bad Request - The request was malformed or contains invalid parameters. **Common causes:** - Missing required fields - Invalid field format (e.g., malformed email) - Invalid JSON syntax - Invalid parameter values
- `401` — Unauthorized - Authentication failed. **Common causes:** - Missing X-API-Key header - Invalid or expired API key - Malformed API key
- `402` — Payment Required - Insufficient credits for this request. **Action required:** Add credits to your account at https://app.leadmagic.io/settings/billing
- `429` — Too Many Requests - Rate limit exceeded. **Action required:** Check the `Retry-After` header for when to retry. **Headers returned:** - `Retry-After`: Seconds until you can retry - `RateLimit-Limit`: Your limit per minute - `RateLimit-Remaining`: Remaining requests this minute - `RateLimit-Reset`: Seconds until limit resets

---

[API](https://skmtc.net/leadmagic/apis/leadmagic-api.md) · [All operations](https://skmtc.net/leadmagic/apis/leadmagic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadmagic/leadmagic-api/revisions/aa19cf9bc46a/schema)