People Search

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

POST /v3/people/search

People Search

cURL

curl --request POST \
  --url https://api.leadmagic.io/v3/people/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "preview": true,
  "company_filters": {
    "company_domains": [
      "leadmagic.io"
    ],
    "crm_tech": [
      "Salesforce"
    ]
  },
  "people_filters": {
    "contact_job_level": [
      "VP",
      "Director"
    ]
  },
  "titles": [
    "VP Sales",
    "Head of Revenue"
  ],
  "required_email": true,
  "limit": 10
}
'

200

{
  "message": "People found",
  "credits_consumed": 0,
  "count": 1,
  "people": [
    {
      "person": {
        "contact_full_name": "Alex Rivera",
        "contact_job_title": "VP Sales",
        "company_domain": "leadmagic.io",
        "contact_email": null,
        "contact_email_masked": "a***@leadmagic.io",
        "has_email": true,
        "has_mobile_phone": true,
        "outreach_locked": true
      },
      "company": {
        "company_domain": "leadmagic.io",
        "company_name": "LeadMagic"
      },
      "unlock": {
        "required": true,
        "email_credits": 1,
        "mobile_credits": 5
      }
    }
  ],
  "metadata": {
    "query_name": "people_search_v3",
    "query_path": "full_search"
  }
}

People Search

POST /v3/people/search is the single V3 people lookup endpoint. It replaces the older V3 people variants such as mixed search, ICP search, employees, by-title, and people lookalike.

Use it when you want to search people from either:

• one company, using company_domain, company_name, or linkedin_url
• a criteria-based account set, using company_filters

You can combine company filters, people filters, title/role/query intent, contactability requirements, preview mode, and optional paid contact-detail unlocks in one request.

Endpoint Details

Pricing

Metric	Value
Base cost	1 credit per returned person
No results	FREE
Preview mode	FREE when preview: true and raw contact details are not requested
Raw email	+ 1 credit per returned email when include_contact_details: true
Raw mobile	+ 5 credits per returned mobile when include_contact_details: true
Authorization	Reserves up to the requested limit and finalizes to returned people plus selected contact details

Raw outreach fields require include_contact_details: true and confirm_credit_charge: true. Otherwise the API returns masked/locked values and availability flags.

Rate Limits

Metric	Value
Requests/Minute	300
Burst Capacity	~5 requests/second

---

Quick Example

cURL

curl -X POST 'https://api.leadmagic.io/v3/people/search' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_domain": "leadmagic.io",
    "titles": ["VP Sales", "Head of Revenue"],
    "required_email": true,
    "limit": 10
  }'

Search Across Company Filters

Use company_filters when you want to find people across an account list instead of one known company.

{
  "preview": true,
  "limit": 10,
  "company_filters": {
    "country_codes": ["US"],
    "employee_ranges": ["51 to 200", "201 to 500"],
    "crm_tech": ["Salesforce"],
    "min_valid_email_count": 10
  },
  "people_filters": {
    "contact_job_level": ["VP", "Director"],
    "contact_job_function": ["Sales"]
  },
  "titles": ["VP Sales", "Head of Revenue"],
  "required_email": true
}

Request Body

At least one company identifier or usable company_filters object is required.

Company Targeting

Field	Type	Description
company_domain	string	Single company domain. Preferred for one-company searches.
company_name	string	Single company name.
linkedin_url	string	B2B company profile URL or slug.
company_filters / companyFilters	object	Criteria-based company set. Supports the same full filter family as Company Search.

People Intent

Field	Type	Description
title / job_title	string	Single title query.
titles	string[]	Up to 12 title terms.
roles	string[]	Role terms combined with title terms.
query	string	Free-text people/title query.

People Filters

Pass these inside people_filters or peopleFilters.

Field	Type	Description
contact_full_name	string[]	Full-name text filter. Aliases include full_name, name.
contact_first_name	string[]	First-name text filter.
contact_last_name	string[]	Last-name text filter.
contact_email_domain	string[]	Email-domain filter.
contact_linkedin_url	string[]	B2B person profile URL. Aliases include linkedin_url, profile_url.
contact_linkedin_username	string[]	B2B person profile slug.
contact_job_title	string[]	Fuzzy title text.
contact_job_function	string[]	Normalized function, such as Sales or Engineering.
contact_job_level	string[]	Normalized seniority, such as VP, Director, or C-Team.
contact_country_code	string[]	Country code.
contact_country	string[]	Country name text.
contact_region	string[]	Region label.
contact_continent	string[]	Continent label.
contact_city	string[]	City text.
contact_state	string[]	State text.
contact_state_code	string[]	State/province code.
contact_linkedin_headline	string[]	Professional headline text.
contact_linkedin_about_me	string[]	Professional about/summary text.
contact_linkedin_industry	string[]	Industry text.
contact_job_description	string[]	Job description text.
contact_languages	string[]	Language text.
min_followers	integer	Minimum follower count on the person’s public profile.
max_followers	integer	Maximum follower count on the person’s public profile.
min_seniority	integer	Minimum computed seniority score.
has_email	boolean	Require email availability.
has_mobile_phone	boolean	Require mobile availability.

Contactability And Unlocks

Field	Type	Description
required_email / requiredEmail	boolean	Only return people with email availability.
required_mobile / requiredMobile	boolean	Only return people with mobile availability.
channels	("email" | "phone")[]	Legacy alias for contactability requirements.
channel_match / channelMatch	"any" | "all"	Whether a person must match any or all requested channels.
include_contact_details / includeContactDetails	boolean	Return raw paid email/mobile fields. Requires confirm_credit_charge: true.
include_email / includeEmail	boolean	When unlocking details, include and bill raw email values. Defaults to true.
include_mobile / includeMobile	boolean	When unlocking details, include and bill raw mobile/direct phone values. Defaults to true.
confirm_credit_charge / confirmCreditCharge	boolean	Required for raw contact-detail unlocks.

Output Controls

Field	Type	Description
include_company / includeCompany	boolean	Include company rows for returned people.
include_domain_intel / includeDomainIntel	boolean	Include email/domain intelligence where available.
person_fields	"summary" | "full"	Requested person detail level.
company_fields	"summary" | "full"	Requested company detail level.
preview	boolean	Return a zero-credit locked preview when raw details are not requested.
limit	integer	Page size. Maximum is 100. Defaults to 25.
offset	integer	Offset for pagination.

Response

message · string

Human-readable result summary.

credits_consumed · number

Finalized credits charged for this request. 0 in free preview mode.

credit_preview · object

Credit breakdown for base people, email unlocks, and mobile unlocks.

people · object[]

Returned people. Each row contains person, optional company, optional domain_intel, and an unlock object when outreach fields are locked.

companies · object[]

Company rows matched or hydrated for the search.

count · integer

Number of returned people.

limit_applied · integer

Applied page size.

offset · integer

Applied offset.

Preview responses keep contact_email, contact_mobile_phone, and contact_direct_phone hidden, while returning masked fields such as contact_email_masked and an unlock cost summary.

Related endpoints

Company Search

Build the account set that People Search can target with company_filters.

Company Lookalike

Find similar accounts from a seed company.

Email Finder

Find a work email for one known person.

Mobile Finder

Find a direct mobile number for one known person.

Authorizations

X-API-Key · string · header · required

Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).

Body

application/json

company_domain · string

Example:

"leadmagic.io"

company_name · string

Example:

"LeadMagic"

linkedin_url · string

B2B company profile URL or slug.

Example:

"https://www.linkedin.com/company/leadmagichq/"

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, seniority, connection count, and channel availability.

title · string

Example:

"VP Sales"

job_title · string

Example:

"Head of Revenue"

titles · string[]

Maximum array length: 12

roles · string[]

Maximum array length: 12

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 · enum<string>[]

Legacy alias for contactability requirements.

Available options: email, phone

channel_match · enum<string> · default: any

Available options: any, all

include_company · boolean · default: true

include_domain_intel · boolean · default: true

include_contact_details · boolean · default: false

Return paid raw email/mobile fields. Requires confirm_credit_charge=true.

include_email · boolean · default: true

include_mobile · boolean · default: true

confirm_credit_charge · boolean · default: false

preview · boolean · default: false

limit · integer · default: 25

Required range: 1 <= x <= 100

offset · integer · default: 0

Required range: x >= 0

Response

200

application/json

People search results

message · string

credits_consumed · number

credit_preview · object

people · object[]

Show child attributes

companies · object[]

count · integer

returned_count · integer

limit_applied · integer

offset · integer

metadata · object