POST

people

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
}
'

import requests

url = "https://api.leadmagic.io/v3/people/search"

payload = {
    "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
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.leadmagic.io/v3/people/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v3/people/search"

	payload := strings.NewReader("{\n  \"company_filters\": {\n    \"company_domains\": [\n      \"leadmagic.io\"\n    ],\n    \"crm_tech\": [\n      \"Salesforce\"\n    ]\n  },\n  \"people_filters\": {\n    \"contact_job_level\": [\n      \"VP\",\n      \"Director\"\n    ]\n  },\n  \"titles\": [\n    \"VP Sales\",\n    \"Head of Revenue\"\n  ],\n  \"required_email\": true,\n  \"limit\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v3/people/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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

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

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

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

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

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

Pricing
Rate Limits

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

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
  }'

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`);

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.

{
  "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.
`limit`	`integer`	Page size. Maximum is `100`. Defaults to `25`.
`offset`	`integer`	Offset for pagination.

Response

string

Human-readable result summary.

number

Finalized credits charged for this request (base people rows plus any unlocked contact details).

object[]

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

object[]

Company rows matched or hydrated for the search.

integer

Number of returned people.

integer

Applied page size.

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[]

Show child attributes

companies

object[]

count

integer

returned_count

integer

limit_applied

integer

offset

integer

metadata

object

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
}
'

import requests

url = "https://api.leadmagic.io/v3/people/search"

payload = {
    "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
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.leadmagic.io/v3/people/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v3/people/search"

	payload := strings.NewReader("{\n  \"company_filters\": {\n    \"company_domains\": [\n      \"leadmagic.io\"\n    ],\n    \"crm_tech\": [\n      \"Salesforce\"\n    ]\n  },\n  \"people_filters\": {\n    \"contact_job_level\": [\n      \"VP\",\n      \"Director\"\n    ]\n  },\n  \"titles\": [\n    \"VP Sales\",\n    \"Head of Revenue\"\n  ],\n  \"required_email\": true,\n  \"limit\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v3/people/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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

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

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

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

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

Get Started

API Endpoints

MCP Server

CLI

People Search

People Search

Endpoint Details

Quick Example

Search Across Company Filters

Request Body

Company Targeting

People Intent

People Filters

Contactability And Unlocks

Output Controls

Response

Company Search

Company Lookalike

Email Finder

Mobile Finder

Authorizations

Body

Response

​People Search

​Endpoint Details

​Quick Example

​Search Across Company Filters

​Request Body

​Company Targeting

​People Intent

​People Filters

​Contactability And Unlocks

​Output Controls

​Response

​Related endpoints

Company Search

Company Lookalike

Email Finder

Mobile Finder

Authorizations

Body

Response

People Search

Endpoint Details

Quick Example

Search Across Company Filters

Request Body

Company Targeting

People Intent

People Filters

Contactability And Unlocks

Output Controls

Response

Related endpoints