Skip to main content
POST
/
v3
/
people
/
search
People Search
curl --request POST \
  --url https://api.leadmagic.io/v3/people/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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
}
'
{
  "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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, and optional paid contact-detail unlocks in one request.

​
Endpoint Details

MetricValue
Base cost1 credit per returned person
No resultsFREE
Raw email+ 1 credit per returned email when include_contact_details: true
Raw mobile+ 5 credits per returned mobile when include_contact_details: true
AuthorizationReserves 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.

​
Quick Example

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. 
{
  "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

FieldTypeDescription
company_domainstringSingle company domain. Preferred for one-company searches.
company_namestringSingle company name.
linkedin_urlstringB2B company profile URL or slug.
company_filters / companyFiltersobjectCriteria-based company set. Supports the same full filter family as Company Search.

​
People Intent

FieldTypeDescription
title / job_titlestringSingle title query.
titlesstring[]Up to 12 title terms.
rolesstring[]Role terms combined with title terms.
querystringFree-text people/title query.

​
People Filters

Pass these inside people_filters or peopleFilters.
FieldTypeDescription
contact_full_namestring[]Full-name text filter. Aliases include full_name, name.
contact_first_namestring[]First-name text filter.
contact_last_namestring[]Last-name text filter.
contact_email_domainstring[]Email-domain filter.
contact_linkedin_urlstring[]B2B person profile URL. Aliases include linkedin_url, profile_url.
contact_linkedin_usernamestring[]B2B person profile slug.
contact_job_titlestring[]Fuzzy title text.
contact_job_functionstring[]Normalized function, such as Sales or Engineering.
contact_job_levelstring[]Normalized seniority, such as VP, Director, or C-Team.
contact_country_codestring[]Country code.
contact_countrystring[]Country name text.
contact_regionstring[]Region label.
contact_continentstring[]Continent label.
contact_citystring[]City text.
contact_statestring[]State text.
contact_state_codestring[]State/province code.
contact_linkedin_headlinestring[]Professional headline text.
contact_linkedin_about_mestring[]Professional about/summary text.
contact_linkedin_industrystring[]Industry text.
contact_job_descriptionstring[]Job description text.
contact_languagesstring[]Language text.
min_followersintegerMinimum follower count on the person’s public profile.
max_followersintegerMaximum follower count on the person’s public profile.
min_seniorityintegerMinimum computed seniority score.
has_emailbooleanRequire email availability.
has_mobile_phonebooleanRequire mobile availability.

​
Contactability And Unlocks

FieldTypeDescription
required_email / requiredEmailbooleanOnly return people with email availability.
required_mobile / requiredMobilebooleanOnly 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 / includeContactDetailsbooleanReturn raw paid email/mobile fields. Requires confirm_credit_charge: true.
include_email / includeEmailbooleanWhen unlocking details, include and bill raw email values. Defaults to true.
include_mobile / includeMobilebooleanWhen unlocking details, include and bill raw mobile/direct phone values. Defaults to true.
confirm_credit_charge / confirmCreditChargebooleanRequired for raw contact-detail unlocks.

​
Output Controls

FieldTypeDescription
include_company / includeCompanybooleanInclude company rows for returned people.
include_domain_intel / includeDomainIntelbooleanInclude email/domain intelligence where available.
person_fields"summary" | "full"Requested person detail level.
company_fields"summary" | "full"Requested company detail level.
limitintegerPage size. Maximum is 100. Defaults to 25.
offsetintegerOffset for pagination.

​
Response

​
message
string
Human-readable result summary.
​
credits_consumed
number
Finalized credits charged for this request (base people rows plus any unlocked contact details).
​
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.
Unless you set include_contact_details: true and confirm_credit_charge: true, raw outreach fields stay hidden and the API returns masked values such as contact_email_masked plus an unlock cost summary.

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
​
limit
integer
default:25
Required range: 1 <= x <= 100
​
offset
integer
default:0
Required range: x >= 0

Response

People search results

​
message
string
​
credits_consumed
number
​
people
object[]
​
companies
object[]
​
count
integer
​
returned_count
integer
​
limit_applied
integer
​
offset
integer
​
metadata
object