> ## Documentation Index
> Fetch the complete documentation index at: https://developer.salesforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search people

> Synchronous. Each calendar month (UTC) your account gets a free allowance of search requests, cursor pages included; after that each successful request costs credits. Returns up to limit people (required, 1-2000) matching the filters, plus a cursor while more pages may exist; fetch the next page by sending the cursor as the cursor query parameter (the body is then ignored). Finding contact details is charged separately, when you pass the person IDs to the /enrichment endpoints. In each lead, location and company can be null, and so can a company's location and revenueRange.

A cursor stays valid for 20 minutes after each page. Once a search has returned 1000 people, the next page answers 410; refine your filters to reach the people you need. Stop paging on 410 or when a page has no cursor. With maxContactsPerCompany a page can be shorter than limit, or empty, and still carry a cursor.

Accepts the full person filter set. Use companyDomains.include to target specific companies (e.g. domains returned by /lookalikes/search). Example: {"limit": 100, "leadJobTitles": {"include": ["Head of Sales"]}, "companyLocations": {"include": ["Germany"]}, "companyEmployeeNumberRange": {"min": 11, "max": 200}, "maxContactsPerCompany": 3}.

Free-text fields (leadJobTitles, leadLocations, companyLocations, companyTechnologies, companyKeywords, companyNames) accept any value, so there is no value list to fetch. Two-letter location values are read as ISO country codes (CA = Canada, not California), so spell out states. Controlled fields (companyIndustries, leadSeniorities, leadDepartments, companyTypes, companyFundingRounds, companyRevenueRanges) must use values from their discovery endpoints under /search/filters. An unknown leadSeniorities, leadDepartments or companyRevenueRanges value is rejected with 400; an unknown companyIndustries or companyTypes value matches nothing. companyFundingRounds takes ids such as SERIES_A, not display names such as "Series A"; an unknown id is rejected with 400. An empty string in an include or exclude list is rejected with 400. warnings lists leadLocations and companyLocations include values that match nothing, in normalised form, on the first page only; when they cannot be worked out, the search still answers, without warnings.

Field notes: leadJobTitles include values match titles containing those words in that order, by whole word and stem, synonyms included (CTO ~ Chief Technology Officer); wrap a value in double quotes to turn synonyms off, or set exactMatch to match the whole title. leadTenure is the time in the current position in months; companyYearsInBusinessRange is the company age in years; companyFoundedYearRange takes calendar years, e.g. {"min": 2015, "max": 2020}. leadIDs and companyIDs take leads[].id and leads[].company.id from earlier results. companyDomains takes bare domains, e.g. salesforge.ai, without scheme, www. or path. companyNiches takes exact, case-sensitive values (e.g. "SaaS") and companyBusinessModels exact values.



## OpenAPI

````yaml https://api.leadsforge.ai/public/swagger/doc.json post /search
openapi: 3.1.0
info:
  description: >-
    Search B2B leads, find their work emails, phone numbers and LinkedIn
    profiles, and discover lookalike companies, company page followers and local
    businesses.


    Authenticate every request with your API key in the `Authorization` header:
    the raw key, no `Bearer` prefix. Create the key in the Leadsforge app under
    Settings -> API & MCP.


    Paid operations consume credits from your account balance, and each
    operation says whether it is paid. Long-running operations are asynchronous:
    they return a job that you poll (or receive by webhook) and then page
    through its results.


    Errors return a JSON body with a human-readable `message` and, except for an
    unknown path (404), a stable `code`. Program against `code`. A JSON body
    with a field the operation does not accept is rejected with 400 bad_request,
    listing the unknown fields in data.validations. A request still running when
    the server timeout is reached is cut off with 503 and an empty body.
  license:
    name: Proprietary
    url: https://www.leadsforge.ai/terms
  termsOfService: https://www.leadsforge.ai/terms
  title: Leadsforge API
  version: '1.0'
servers:
  - url: https://api.leadsforge.ai/public/v1
security: []
tags:
  - description: Your account's credit balance.
    name: Balance
  - description: >-
      Find people by role, seniority, company, location and other filters.
      Searches and counts are free up to a monthly allowance, then each one
      costs credits; finding contact details is charged separately.
    name: Search
  - description: >-
      Accepted values for the controlled filters of POST /search and POST
      /search/count, and a resolver for location strings. All free.
    name: Search filters
  - description: >-
      Find work emails, phone numbers and LinkedIn profiles. Asynchronous jobs
      take up to 500 people; synchronous calls take one person and answer in the
      same response.
    name: Enrichment
  - description: >-
      Find companies similar to the domains you give. Previews are free up to a
      monthly allowance, then each one costs credits; the search consumes
      credits per company returned.
    name: Lookalikes
  - description: >-
      Find the people who follow a LinkedIn company page. Asynchronous jobs that
      consume credits per follower collected.
    name: Company followers
  - description: >-
      Find local businesses in an area you choose, then find their owners'
      emails and phone numbers. Both steps are asynchronous jobs that consume
      credits.
    name: Maps discovery
  - description: Scrape LinkedIn Sales Navigator searches.
    name: salesnav
externalDocs:
  description: Leadsforge API guides
  url: >-
    https://developer.salesforge.ai/leadsforge-api/concepts/search-and-enrichment
paths:
  /search:
    post:
      tags:
        - Search
      summary: Search people
      description: >-
        Synchronous. Each calendar month (UTC) your account gets a free
        allowance of search requests, cursor pages included; after that each
        successful request costs credits. Returns up to limit people (required,
        1-2000) matching the filters, plus a cursor while more pages may exist;
        fetch the next page by sending the cursor as the cursor query parameter
        (the body is then ignored). Finding contact details is charged
        separately, when you pass the person IDs to the /enrichment endpoints.
        In each lead, location and company can be null, and so can a company's
        location and revenueRange.


        A cursor stays valid for 20 minutes after each page. Once a search has
        returned 1000 people, the next page answers 410; refine your filters to
        reach the people you need. Stop paging on 410 or when a page has no
        cursor. With maxContactsPerCompany a page can be shorter than limit, or
        empty, and still carry a cursor.


        Accepts the full person filter set. Use companyDomains.include to target
        specific companies (e.g. domains returned by /lookalikes/search).
        Example: {"limit": 100, "leadJobTitles": {"include": ["Head of Sales"]},
        "companyLocations": {"include": ["Germany"]},
        "companyEmployeeNumberRange": {"min": 11, "max": 200},
        "maxContactsPerCompany": 3}.


        Free-text fields (leadJobTitles, leadLocations, companyLocations,
        companyTechnologies, companyKeywords, companyNames) accept any value, so
        there is no value list to fetch. Two-letter location values are read as
        ISO country codes (CA = Canada, not California), so spell out states.
        Controlled fields (companyIndustries, leadSeniorities, leadDepartments,
        companyTypes, companyFundingRounds, companyRevenueRanges) must use
        values from their discovery endpoints under /search/filters. An unknown
        leadSeniorities, leadDepartments or companyRevenueRanges value is
        rejected with 400; an unknown companyIndustries or companyTypes value
        matches nothing. companyFundingRounds takes ids such as SERIES_A, not
        display names such as "Series A"; an unknown id is rejected with 400. An
        empty string in an include or exclude list is rejected with 400.
        warnings lists leadLocations and companyLocations include values that
        match nothing, in normalised form, on the first page only; when they
        cannot be worked out, the search still answers, without warnings.


        Field notes: leadJobTitles include values match titles containing those
        words in that order, by whole word and stem, synonyms included (CTO ~
        Chief Technology Officer); wrap a value in double quotes to turn
        synonyms off, or set exactMatch to match the whole title. leadTenure is
        the time in the current position in months; companyYearsInBusinessRange
        is the company age in years; companyFoundedYearRange takes calendar
        years, e.g. {"min": 2015, "max": 2020}. leadIDs and companyIDs take
        leads[].id and leads[].company.id from earlier results. companyDomains
        takes bare domains, e.g. salesforge.ai, without scheme, www. or path.
        companyNiches takes exact, case-sensitive values (e.g. "SaaS") and
        companyBusinessModels exact values.
      operationId: searchPeople
      parameters:
        - description: Cursor from the previous page
          in: query
          name: cursor
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPeopleRequest'
              description: Search request
              summary: search
        description: Search request
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchPeopleResponse'
          description: Search response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'bad_request: the body or a parameter is invalid'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            missing_api_key, invalid_api_key, or unauthorized when your account
            is blocked
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            insufficient_credits: the free searches of this month are used up
            and your balance does not cover the next one
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            account_frozen: the free searches of this month are used up and
            credit spending is paused for your account
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            gone: the cursor expired or is invalid, or the search has returned
            the maximum number of results; start a new search with narrower
            filters
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            rate_limited: too many requests, retry later; Retry-After is set
            when known
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'internal: unexpected server error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SearchPeopleRequest:
      properties:
        companyBusinessModels:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyDomains:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyEmployeeNumberRange:
          $ref: '#/components/schemas/MinMaxFilter'
        companyFoundedYearRange:
          $ref: '#/components/schemas/MinMaxFilter'
        companyFundingRounds:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyIDs:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyIndustries:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyKeywords:
          $ref: '#/components/schemas/IncludeExcludeAllFilter'
        companyLocations:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyNames:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyNiches:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyRequired:
          description: CompanyRequired true returns only people with a known company.
          type: boolean
        companyRevenueRanges:
          items:
            $ref: '#/components/schemas/RevenueCategory'
          type: array
          uniqueItems: false
        companyTechnologies:
          $ref: '#/components/schemas/AnyAllFilter'
        companyTypes:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        companyYearsInBusinessRange:
          $ref: '#/components/schemas/MinMaxFilter'
        leadDepartments:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        leadIDs:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        leadJobTitles:
          $ref: '#/components/schemas/JobTitleFilter'
        leadLanguages:
          $ref: '#/components/schemas/LanguageFilter'
        leadLocations:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        leadSeniorities:
          $ref: '#/components/schemas/IncludeExcludeFilter'
        leadTenure:
          $ref: '#/components/schemas/MinMaxFilter'
        limit:
          maximum: 2000
          minimum: 1
          type: integer
        maxContactsPerCompany:
          description: >-
            MaxContactsPerCompany caps the people returned per company, up to
            100; 0 or absent means no cap.
          maximum: 100
          minimum: 0
          type: integer
      required:
        - limit
      type: object
    SearchPeopleResponse:
      properties:
        cursor:
          type: string
        leads:
          items:
            $ref: '#/components/schemas/SearchLead'
          type: array
          uniqueItems: false
        warnings:
          items:
            $ref: '#/components/schemas/SearchFilterWarning'
          type: array
          uniqueItems: false
      type: object
    ApiError:
      properties:
        code:
          description: >-
            Code is the stable, machine-readable error code; each endpoint lists
            the codes it returns.
          type: string
        data:
          description: >-
            Data carries details for some errors; on validation errors it is
            {"validations": ["..."]}, one message per

            invalid field.
        message:
          type: string
      type: object
    IncludeExcludeFilter:
      properties:
        exclude:
          items:
            type: string
          type: array
          uniqueItems: false
        include:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    MinMaxFilter:
      properties:
        max:
          type: integer
        min:
          type: integer
      type: object
    IncludeExcludeAllFilter:
      properties:
        exclude:
          items:
            type: string
          type: array
          uniqueItems: false
        include:
          items:
            type: string
          type: array
          uniqueItems: false
        matchAll:
          description: >-
            MatchAll true requires every include value to match; false (default)
            matches any of them.
          type: boolean
      type: object
    RevenueCategory:
      enum:
        - very_small
        - small_lower
        - small_upper
        - lower_mid_sized
        - mid_sized_lower
        - mid_sized_upper
        - large_lower
        - large_upper
        - enterprise_lower
        - enterprise_upper
        - global_giants_lower
        - global_giants_upper
        - super_enterprises
      type: string
      x-enum-varnames:
        - RevenueVerySmall
        - RevenueSmallLower
        - RevenueSmallUpper
        - RevenueLowerMidSized
        - RevenueMidSizedLower
        - RevenueMidSizedUpper
        - RevenueLargeLower
        - RevenueLargeUpper
        - RevenueEnterpriseLower
        - RevenueEnterpriseUpper
        - RevenueGlobalGiantsLower
        - RevenueGlobalGiantsUpper
        - RevenueSuperEnterprises
    AnyAllFilter:
      properties:
        all:
          description: All matches only when every value matches.
          items:
            type: string
          type: array
          uniqueItems: false
        any:
          description: Any matches when at least one of the values matches.
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    JobTitleFilter:
      properties:
        exactMatch:
          description: ExactMatch true matches the whole title instead (case-insensitive).
          type: boolean
        exclude:
          items:
            type: string
          type: array
          uniqueItems: false
        include:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    LanguageFilter:
      properties:
        exclude:
          items:
            type: string
          type: array
          uniqueItems: false
        include:
          description: >-
            Include takes language names as on the profile, e.g. "English"
            (case-sensitive).
          items:
            type: string
          type: array
          uniqueItems: false
        primaryOnly:
          description: PrimaryOnly true keeps only native or bilingual speakers.
          type: boolean
      type: object
    SearchLead:
      properties:
        company:
          $ref: '#/components/schemas/LeadCompany'
        firstName:
          type: string
        id:
          type: string
        jobTitle:
          description: JobTitle may be null.
          type: string
        lastName:
          type: string
        location:
          $ref: '#/components/schemas/LeadLocation'
      type: object
    SearchFilterWarning:
      properties:
        filter:
          type: string
        value:
          type: string
      type: object
    LeadCompany:
      properties:
        domain:
          type: string
        employeeCount:
          type: integer
        id:
          type: string
        industry:
          description: Industry may be null.
          type: string
        keywords:
          description: Keywords may be null.
          items:
            type: string
          type: array
          uniqueItems: false
        location:
          $ref: '#/components/schemas/LeadLocation'
        revenueRange:
          $ref: '#/components/schemas/LeadRevenueRange'
        website:
          description: Website may be null.
          type: string
        yearsInBusiness:
          description: YearsInBusiness may be null.
          type: integer
      type: object
    LeadLocation:
      properties:
        city:
          description: City may be null.
          type: string
        country:
          description: Country may be null.
          type: string
        state:
          description: State may be null.
          type: string
      type: object
    LeadRevenueRange:
      properties:
        end:
          type: integer
        start:
          type: integer
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: >-
        Your API key, sent as is (no `Bearer` prefix). Create it in the
        Leadsforge app under Settings -> API & MCP.
      in: header
      name: Authorization
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.