> ## 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
> Canonical V3 people lookup with all company, title, role, people, channel, and contact-detail filters.
# 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
| Metric | Value |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| **Base cost** | **1 credit** per returned person |
| **No results** | **FREE** |
| **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.
| Metric | Value |
| ------------------- | ------------------- |
| **Requests/Minute** | 300 |
| **Burst Capacity** | \~5 requests/second |
***
## Quick Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
}'
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v3/people/search', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
company_domain: 'leadmagic.io',
titles: ['VP Sales', 'Head of Revenue'],
required_email: true,
limit: 10
})
});
const data = await response.json();
console.log(`${data.count} people found`);
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
response = requests.post(
'https://api.leadmagic.io/v3/people/search',
headers={'X-API-Key': 'YOUR_API_KEY'},
json={
'company_domain': 'leadmagic.io',
'titles': ['VP Sales', 'Head of Revenue'],
'required_email': True,
'limit': 10
}
)
data = response.json()
print(f"{data['count']} people found")
```
## Search Across Company Filters
Use `company_filters` when you want to find people across an account list instead of one known company.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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](/docs/v1/reference/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. |
| `limit` | `integer` | Page size. Maximum is `100`. Defaults to `25`. |
| `offset` | `integer` | Offset for pagination. |
## Response
Human-readable result summary.
Finalized credits charged for this request (base people rows plus any unlocked contact details).
Returned people. Each row contains `person`, optional `company`, optional `domain_intel`, and an `unlock` object when outreach fields are locked.
Company rows matched or hydrated for the search.
Number of returned people.
Applied page size.
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.
## Related endpoints
Build the account set that People Search can target with `company_filters`.
Find similar accounts from a seed company.
Find a work email for one known person.
Find a direct mobile number for one known person.
## OpenAPI
````yaml post /v3/people/search
openapi: 3.1.0
info:
title: LeadMagic API
version: 1.4.34
description: >
# LeadMagic API Documentation
The LeadMagic API provides comprehensive B2B data enrichment services
including email validation, email finding, profile search, company
intelligence, and more.
## Quick Start
1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)
2. Add the `X-API-Key` header to all requests
3. Start enriching your data!
## Base URL
All API requests should be made to: `https://api.leadmagic.io`
## Rate Limits
Each endpoint has specific rate limits (requests per minute). Exceeding
limits returns a `429 Too Many Requests` response.
## Credits
API calls consume credits based on the endpoint used. Check your balance
with the `/v1/credits` endpoint.
## Support
Contact us at support@leadmagic.io for assistance.
contact:
name: LeadMagic Support
email: support@leadmagic.io
url: https://leadmagic.io
termsOfService: https://leadmagic.io/legal/terms
servers:
- url: https://api.leadmagic.io
description: Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Credits
description: Manage and check your credit balance
- name: Analytics
description: >-
Monitor your API usage with comprehensive analytics endpoints (FREE - no
credits consumed)
- name: People Enrichment
description: Find and validate contact information for individuals
- name: Company Data
description: Discover company information and intelligence
- name: Jobs Data
description: Search job listings and detect career changes
- name: Ads Data
description: Search advertising data across platforms
paths:
/v3/people/search:
post:
tags:
- People Enrichment
summary: People Search
description: >-
Canonical V3 people lookup with all company, title, role, people,
channel, and contact-detail filters.
operationId: people-search
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
company_domain:
type: string
example: leadmagic.io
company_name:
type: string
example: LeadMagic
linkedin_url:
type: string
description: B2B company profile URL or slug.
example: https://www.linkedin.com/company/leadmagichq/
company_filters:
type: object
additionalProperties: true
description: >-
Criteria-based company set. Supports the full Company Search
filter family.
people_filters:
type: object
additionalProperties: true
description: >-
People-level filters for names, title/function/level,
geography, profile URLs, seniority, connection count, and
channel availability.
title:
type: string
example: VP Sales
job_title:
type: string
example: Head of Revenue
titles:
type: array
items:
type: string
maxItems: 12
roles:
type: array
items:
type: string
maxItems: 12
query:
type: string
description: Free-text people/title query.
required_email:
type: boolean
description: Only return people with email availability.
required_mobile:
type: boolean
description: Only return people with mobile availability.
channels:
type: array
items:
type: string
enum:
- email
- phone
description: Legacy alias for contactability requirements.
channel_match:
type: string
enum:
- any
- all
default: any
include_company:
type: boolean
default: true
include_domain_intel:
type: boolean
default: true
include_contact_details:
type: boolean
default: false
description: >-
Return paid raw email/mobile fields. Requires
confirm_credit_charge=true.
include_email:
type: boolean
default: true
include_mobile:
type: boolean
default: true
confirm_credit_charge:
type: boolean
default: false
limit:
type: integer
default: 25
minimum: 1
maximum: 100
offset:
type: integer
default: 0
minimum: 0
example:
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
responses:
'200':
description: People search results
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
message:
type: string
credits_consumed:
type: number
people:
type: array
items:
type: object
additionalProperties: true
properties:
person:
type: object
additionalProperties: true
company:
type: object
nullable: true
additionalProperties: true
domain_intel:
type: object
nullable: true
additionalProperties: true
unlock:
type: object
additionalProperties: true
companies:
type: array
items:
type: object
additionalProperties: true
count:
type: integer
returned_count:
type: integer
limit_applied:
type: integer
offset:
type: integer
metadata:
type: object
additionalProperties: true
example:
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
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
responses:
BadRequest:
description: |
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
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
Unauthorized:
description: |
Unauthorized - Authentication failed.
**Common causes:**
- Missing X-API-Key header
- Invalid or expired API key
- Malformed API key
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/MissingAuthenticationError'
- $ref: '#/components/schemas/InvalidApiKeyError'
PaymentRequired:
description: >
Payment Required - Insufficient credits for this request.
**Action required:** Add credits to your account at
https://app.leadmagic.io/billing
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InsufficientCreditsError'
RateLimitExceeded:
description: |
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
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
RateLimit-Limit:
schema:
type: integer
description: Maximum requests per minute
RateLimit-Remaining:
schema:
type: integer
description: Remaining requests this minute
RateLimit-Reset:
schema:
type: integer
description: Seconds until limit resets
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitExceededError'
schemas:
ValidationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/validation_error
title: Request validation failed. Check your input parameters.
status: 400
code: validation_error
param:
- email
detail: 'Email format is invalid. Expected format: user@domain.com'
action: Provide a valid email address in the 'email' field.
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
MissingAuthenticationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/missing_authentication
title: >-
Authentication required. Provide a valid API key in the X-API-Key
header (case-insensitive).
status: 401
code: missing_authentication
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InvalidApiKeyError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/invalid_api_key
title: Invalid API key. The key does not exist or is incorrect.
status: 401
code: invalid_api_key
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InsufficientCreditsError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/insufficient_credits
title: 'Insufficient credits: need 5, have 2.50. Add credits to continue.'
status: 402
code: insufficient_credits
detail: >-
This request requires 5 credit(s) but your account only has 2.50
credits remaining.
action: >-
Add credits to your account at https://app.leadmagic.io/billing or
contact support@leadmagic.io for enterprise plans.
docs: https://leadmagic.io/docs/api-reference/credits
context:
credits_required: 5
credits_available: 2.5
credits_needed: 2.5
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
RateLimitExceededError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/rate_limit_exceeded
title: >-
Rate limit exceeded: 300 requests per 1 minute. Wait and try
again.
status: 429
code: rate_limit_exceeded
detail: >-
You have exceeded the maximum allowed request rate. Please wait
before making additional requests.
action: >-
Wait 42 seconds before retrying. Consider implementing exponential
backoff.
docs: https://leadmagic.io/docs/api-reference/rate-limits
context:
limit: 300
window: 1 minute
remaining: 0
reset_at: 1706745642
retry_after_seconds: 42
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
ErrorResponse:
type: object
description: RFC 9457 Problem Details error response
required:
- success
- errors
properties:
success:
type: boolean
example: false
description: Always false for error responses
errors:
type: array
description: Array of error details (typically one, but can be multiple)
items:
$ref: '#/components/schemas/ErrorDetail'
meta:
$ref: '#/components/schemas/ResponseMeta'
ErrorDetail:
type: object
description: RFC 9457 compliant error detail
required:
- type
- title
- status
properties:
type:
type: string
format: uri
description: RFC 9457 - URI reference identifying the error type
example: https://api.leadmagic.io/errors/validation_error
title:
type: string
description: RFC 9457 - Short human-readable summary
example: Request validation failed. Check your input parameters.
status:
type: integer
description: RFC 9457 - HTTP status code
example: 400
detail:
type: string
description: RFC 9457 - Human-readable explanation specific to this occurrence
example: The email field is required but was not provided.
instance:
type: string
format: uri
description: RFC 9457 - URI reference for this specific occurrence
example: /v1/people/email-validation#req_abc123
code:
type: string
description: Machine-readable error code for programmatic handling
example: validation_error
param:
type: array
description: Parameters that caused the error
items:
type: string
example:
- email
action:
type: string
description: Suggested action to resolve the error
example: Provide a valid email address in the 'email' field.
docs:
type: string
format: uri
description: Link to relevant documentation
example: https://leadmagic.io/docs/api-reference/errors
context:
type: object
description: Additional context specific to this error type
additionalProperties: true
ResponseMeta:
type: object
description: Metadata included in all responses
properties:
request_id:
type: string
format: uuid
description: Unique identifier for this request (use for debugging/support)
example: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp when the response was generated
example: '2024-02-01T12:00:00.000Z'
environment:
type: string
description: API environment (production, staging)
example: production
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
X-API-KEY, x-api-key all work).
````