> ## 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 > [tab] Pricing > > | 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 | > > > [!TIP] > > > > Raw outreach fields require `include_contact_details: true` and `confirm_credit_charge: true`. Otherwise the API returns masked/locked values and availability flags. > [tab] Rate Limits > > | 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](https://leadmagic.io/docs/v1/reference/company-search.md). | ### 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 **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. > [!NOTE] > > 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 > [card] [Company Search](https://leadmagic.io/docs/v1/reference/company-search.md) > > Build the account set that People Search can target with `company_filters`. > [card] [Company Lookalike](https://leadmagic.io/docs/v1/reference/company-lookalike.md) > > Find similar accounts from a seed company. > [card] [Email Finder](https://leadmagic.io/docs/v1/reference/email-finder.md) > > Find a work email for one known person. > [card] [Mobile Finder](https://leadmagic.io/docs/v1/reference/mobile-finder.md) > > 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). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.