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

# Search Person Prospects

> Search for person prospects using comprehensive account and contact filters, then persist results to the database

Searches for person prospects using data providers with extensive filtering capabilities. Results are automatically mapped to domain objects and persisted to the global database (companies and persons are upserted), returning enriched lead objects with associated company data.

## Authentication

This endpoint requires authentication. The user must be signed in to access prospect search functionality.

<Note>
  This endpoint performs a search against the Lance database of 400+ million
  professional profiles. Results are automatically saved to Lance's database,
  deduplicating and merging with existing records.
</Note>

## Request

The request body allows filtering by both account (company) criteria and contact (person) criteria. All filters are optional and can be combined.

### Pagination

<ParamField body="page" default="0" type="integer">
  Page number for pagination (0-indexed)
</ParamField>

<ParamField body="size" default="10" type="integer">
  Number of results per page. Must be between 0 and 100.
</ParamField>

### Contact Filters

<ParamField body="contact" type="object">
  Filters for the individual/person being searched

  <Expandable title="Contact filter properties">
    <ParamField body="contact.fullName" type="object">
      Filter by person's full name with search modes

      <Expandable title="Filter structure">
        <ParamField body="all" type="object">
          Match all conditions

          <Expandable title="all properties">
            <ParamField body="include" type="object" optional>
              <ParamField body="mode" type="string" optional>
                Search match mode: `SMART`, `WORD`, or `STRICT`
              </ParamField>

              <ParamField body="content" type="string[]" optional>
                Array of names to include
              </ParamField>
            </ParamField>

            <ParamField body="exclude" type="object" optional>
              Same structure as include
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="any" type="object">
          Match any condition (same structure as `all`)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.socialMediaLink" type="object">
      Filter by social media profile URLs (include/exclude arrays)

      <Expandable title="socialMediaLink properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Social media URLs to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Social media URLs to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Social media URLs to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Social media URLs to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.company" type="object">
      Filter by current and/or previous companies

      <Expandable title="Company filter structure">
        <ParamField body="current" type="object" optional>
          Filter by current company names

          <Expandable title="current properties">
            <ParamField body="all" type="object" optional>
              <ParamField body="include" type="string[]" optional>
                Company names to include (all must match)
              </ParamField>

              <ParamField body="exclude" type="string[]" optional>
                Company names to exclude
              </ParamField>
            </ParamField>

            <ParamField body="any" type="object" optional>
              <ParamField body="include" type="string[]" optional>
                Company names to include (any can match)
              </ParamField>

              <ParamField body="exclude" type="string[]" optional>
                Company names to exclude
              </ParamField>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="previous" type="object" optional>
          Filter by previous company names

          <Expandable title="previous properties">
            <ParamField body="all" type="object" optional>
              <ParamField body="include" type="string[]" optional>
                Company names to include (all must match)
              </ParamField>

              <ParamField body="exclude" type="string[]" optional>
                Company names to exclude
              </ParamField>
            </ParamField>

            <ParamField body="any" type="object" optional>
              <ParamField body="include" type="string[]" optional>
                Company names to include (any can match)
              </ParamField>

              <ParamField body="exclude" type="string[]" optional>
                Company names to exclude
              </ParamField>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.seniority" type="object">
      Filter by seniority level. Values: `senior`, `manager`, `entry`, `mid-level`, `director`, `c_suite`, `intern`, `founder`, `owner`, `head`, `vp`, `partner`

      <Expandable title="seniority properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Seniority levels to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Seniority levels to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Seniority levels to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Seniority levels to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.location" type="object">
      Filter by person's location (include/exclude arrays)

      <Expandable title="location properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Locations to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Locations to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Locations to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Locations to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.departmentAndFunction" type="object">
      Filter by department and job function. Extensive list including:

      **Executive**: `c_suite`, `executive`, `founder`

      **Product**: `product_management`, `product_development`, `product_mangement`

      **Engineering**: `master_engineering_technical`, `artificial_intelligence_machine_learning`, `bioengineering`, `biometrics`, `business_intelligence`, `chemical_engineering`, `cloud_mobility`, `data_science`, `devops`, `emerging_technology_innovation`, `engineering_technical`, `industrial_engineering`, `mechanic`, `mobile_development`, `project_management`, `research_development`, `scrum_master_agile_coach`, `software_development`, `support_technical_services`, `technician`, `technology_operations`, `test_quality_assurance`, `ui_ux`, `web_development`

      **Design**: `marketing`, `digital_marketing`, `design`, `all_design`, `product_ui_ux_design`, `graphic_design`

      **Education**: `education`, `teacher`, `principal`, `superintendent`, `professor`

      **Finance**: `master_finance`, `accounting`, `finance`, `financial_planning_analysis`, `financial_reporting`, `financial_strategy`, `financial_systems`, `internal_audit_control`, `investor_relations`, `mergers_acquisitions`, `financial_risk`, `sourcing_procurement`, `tax`, `treasury`

      **HR**: `master_human_resources`, `compensation_benefits`, `culture_diversity_inclusion`, `employee_labor_relations`, `health_safety`, `human_resource_information_system`, `human_resources`, `hr_business_partner`, `learning_development`, `organizational_development`, `recruiting_talent_acquisition`, `talent_management`, `workforce_mangement`

      **IT**: `master_information_technology`, `application_development`, `business_service_management_itsm`, `collaboration_web_app`, `data_center`, `data_warehouse`, `database_administration`, `ecommerce_development`, `enterprise_architecture`, `help_desk_desktop_services`, `hr_financial_erp_systems`, `information_security`, `information_technology`, `infrastructure`, `it_asset_management`, `it_audit_it_compliance`, `it_operations`, `it_procurement`, `it_strategy`, `networking`, `project_program_management`, `quality_assurance`, `retail_store_systems`, `servers`, `storage_disaster_recovery`, `telecommunications`, `virtualization`

      **Legal**: `master_legal`, `compliance`, `contracts`, `ediscovery`, `governmental_affairs_regulatory_law`, `intellectual_property_patent`, `labor_employment`, `lawyer_attorney`, `legal`, `legal_counsel`, `legal_operations`, `litigation`, `privacy`

      **Marketing**: `master_marketing`, `advertising`, `brand_management`, `content_marketing`, `customer_experience`, `customer_marketing`, `demand_generation`, `ecommerce_marketing`, `event_marketing`, `field_marketing`, `lead_generation`, `marketing_analytics_insights`, `marketing_communications`, `product_marketing`, `public_relations`, `search_engine_optimization_pay_per_click`, `social_media_marketing`, `strategic_communications`, `technical_marketing`

      **Sales**: `sales`, `field_outside_sales`, `master_sales`, `account_management`, `business_development`, `channel_sales`, `customer_retention_development`, `inside_sales`, `partnerships`, `sales_enablement`, `sales_engineering`, `sales_operations`, `sales_training`

      **Medical**: `medical_health`, `chiropractics`, `dentistry`, `doctors_physicians`, `first_responder`, `infectious_disease`, `medical_administration`, `medical_education_training`, `medicine`, `neurology`, `nursing`, `nutrition_dietetics`, `oncology`, `pathology`, `pharmacy`, `physical_therapy`, `psychology`, `public_health`, `radiology`, `social_work`

      **Operations**: `master_operations`, `call_center`, `construction`, `corporate_strategy`, `customer_service_support`, `enterprise_resource_planning`, `facilities_management`, `leasing`, `logistics`, `office_operations`, `operations`, `physical_security`, `project_development`, `quality_management`, `real_estate`, `store_operations`, `supply_chain`, `customer_success`

      **Consulting**: `consulting`, `consultant`

      <Expandable title="departmentAndFunction properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Departments/functions to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Departments/functions to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Departments/functions to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Departments/functions to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.skill" type="object">
      Filter by skills with search modes (SMART, WORD, STRICT)

      <Expandable title="skill properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="object" optional>
            <ParamField body="mode" type="string" optional>
              Search match mode: `SMART`, `WORD`, or `STRICT`
            </ParamField>

            <ParamField body="content" type="string[]" optional>
              Array of skills to include
            </ParamField>
          </ParamField>

          <ParamField body="exclude" type="object" optional>
            Same structure as include
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          Same structure as `all`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.certification" type="object">
      Filter by certifications with search modes

      <Expandable title="certification properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="object" optional>
            <ParamField body="mode" type="string" optional>
              Search match mode: `SMART`, `WORD`, or `STRICT`
            </ParamField>

            <ParamField body="content" type="string[]" optional>
              Array of certifications to include
            </ParamField>
          </ParamField>

          <ParamField body="exclude" type="object" optional>
            Same structure as include
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          Same structure as `all`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.keyword" type="object">
      Filter by keywords across multiple profile sources.

      Sources: `ORGANIZATION`, `TEST_SCORE`, `AWARD`, `WORK_HISTORY_DESCRIPTION`, `PUBLICATION`, `SUMMARY`, `PATENT`, `VOLUNTEERING`, `HEADLINE`, `EDUCATION_DESCRIPTION`, `COURSE`, `PROJECTS`, `SKILL`, `LANGUAGE_SKILL`, `CERTIFICATION`

      <Expandable title="keyword properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="object" optional>
            <ParamField body="sources" type="object[]" optional>
              Array of source configurations with:

              * `mode`: `SMART`, `WORD`, or `STRICT`
              * `source`: one of the sources listed above
            </ParamField>

            <ParamField body="content" type="string[]" optional>
              Keywords to search for
            </ParamField>
          </ParamField>

          <ParamField body="exclude" type="object" optional>
            Same structure as include
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          Same structure as `all`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.socialMedia" type="object">
      Filter by social media presence. Values: `FACEBOOK`, `INSTAGRAM`, `TWITTER`, `LINKEDIN`

      <Expandable title="socialMedia properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Social media platforms to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Social media platforms to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Social media platforms to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Social media platforms to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.language" type="object">
      Filter by language skills with proficiency range. Supports 49 languages: `english`, `spanish`, `french`, `portuguese`, `german`, `dutch`, `italian`, `chinese`, `turkish`, `polish`, `russian`, `swedish`, `arabic`, `indonesian`, `danish`, `czech`, `norwegian`, `japanese`, `korean`, `romanian`, `ukrainian`, `thai`, `hindi`, `malay`, `tagalog`, `vietnamese`, `finnish`, `persian`, `greek`, `hungarian`, `bengali`, `marathi`, `telugu`, `panjabi`, `serbian`, `slovak`, `croatian`, `lithuanian`, `latvian`, `albanian`, `icelandic`, `armenian`, `bosnian`, `tamil`, `javanese`, `malayalam`, `kannada`, `burmese`

      <Expandable title="language properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="object" optional>
            <ParamField body="mode" type="string" optional>
              Search match mode: `SMART`, `WORD`, or `STRICT`
            </ParamField>

            <ParamField body="content" type="string[]" optional>
              Array of language enum values to include (e.g., `["english", "german"]`)
            </ParamField>
          </ParamField>

          <ParamField body="exclude" type="object" optional>
            Same structure as include
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          Same structure as `all`
        </ParamField>

        <ParamField body="range" type="object" optional>
          Range filter for number of languages
          <ParamField body="start" type="number" optional>Minimum count</ParamField>
          <ParamField body="end" type="number" optional>Maximum count</ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.education" type="object">
      Filter by education background

      <Expandable title="Education filter structure">
        <ParamField body="school" type="object">
          <ParamField body="all" type="object" optional>
            <ParamField body="include" type="string[]" optional>School names to include</ParamField>
            <ParamField body="exclude" type="string[]" optional>School names to exclude</ParamField>
          </ParamField>

          <ParamField body="any" type="object" optional>
            Same structure as `all`
          </ParamField>
        </ParamField>

        <ParamField body="degree" type="object">
          Filter by degree types with search mode (`SMART`, `WORD`, `STRICT`)
        </ParamField>

        <ParamField body="fieldOfStudy" type="object">
          Filter by fields of study with search mode
        </ParamField>

        <ParamField body="date" type="object">
          Education date range filter
          <ParamField body="start" type="number" optional>Start year</ParamField>
          <ParamField body="end" type="number" optional>End year</ParamField>
          <ParamField body="present" type="boolean" optional>Currently enrolled</ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.profileBadge" type="object">
      Filter by LinkedIn profile badges. Values: `PREMIUM`, `OPEN_TO_WORK`, `INFLUENCER`

      <Expandable title="profileBadge properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Profile badges to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Profile badges to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Profile badges to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Profile badges to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact.experience" type="object">
      Filter by work experience

      <Expandable title="Experience filter structure">
        <ParamField body="current" type="object">
          Current role filters

          <Expandable title="current properties">
            <ParamField body="title" type="object" optional>
              Filter by current job title with search modes (`SMART`, `WORD`, `STRICT`)

              <ParamField body="all" type="object" optional>
                <ParamField body="include" type="object" optional>
                  <ParamField body="mode" type="string" optional>Search match mode</ParamField>
                  <ParamField body="content" type="string[]" optional>Job titles to include</ParamField>
                </ParamField>

                <ParamField body="exclude" type="object" optional>Same structure as include</ParamField>
              </ParamField>

              <ParamField body="any" type="object" optional>Same structure as `all`</ParamField>
            </ParamField>

            <ParamField body="duration" type="object" optional>
              Duration filters for current position

              <ParamField body="currentCompany" type="object" optional>
                Time at current company

                <ParamField body="min" type="object" optional>
                  <ParamField body="year" type="number" optional>Minimum years</ParamField>
                  <ParamField body="month" type="number" optional>Minimum months</ParamField>
                </ParamField>

                <ParamField body="max" type="object" optional>
                  <ParamField body="year" type="number" optional>Maximum years</ParamField>
                  <ParamField body="month" type="number" optional>Maximum months</ParamField>
                </ParamField>
              </ParamField>

              <ParamField body="currentJob" type="object" optional>
                Time in current role (same structure as currentCompany)
              </ParamField>

              <ParamField body="total" type="object" optional>
                Total work experience (same structure as currentCompany)
              </ParamField>
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="previous" type="object">
          Previous role filters

          <Expandable title="previous properties">
            <ParamField body="title" type="object" optional>
              Filter by previous job titles with search modes
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Account Filters

<ParamField body="account" type="object">
  Filters for the company/account associated with the person

  <Expandable title="Account filter properties">
    <ParamField body="account.nameOrDomain" type="object">
      Filter by company name or domain with search modes (`SMART`, `WORD`, `STRICT`)
    </ParamField>

    <ParamField body="account.domain" type="object">
      Filter by company domain (include/exclude arrays)
    </ParamField>

    <ParamField body="account.socialMediaLink" type="object">
      Filter by company social media profile URLs (include/exclude arrays)
    </ParamField>

    <ParamField body="account.phoneNumber" type="object">
      Filter by company phone numbers (include/exclude arrays)
    </ParamField>

    <ParamField body="account.industry" type="object">
      Filter by industry. Supports 900+ industries including: `software development`, `it services and it consulting`, `financial services`, `hospitals and health care`, `manufacturing`, `retail`, `construction`, `real estate`, `education`, `marketing`, `biotechnology`, `telecommunications`, `saas`, `fintech`, `artificial intelligence (ai)`, `generative ai`, and many more.

      <Expandable title="industry properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Industries to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Industries to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Industries to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Industries to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.location" type="object">
      Filter by company location (include/exclude arrays)
    </ParamField>

    <ParamField body="account.productAndServices" type="object">
      Filter by company products and services with search modes (`SMART`, `WORD`, `STRICT`)
    </ParamField>

    <ParamField body="account.socialMedia" type="object">
      Filter by company social media presence. Values: `FACEBOOK`, `INSTAGRAM`, `TWITTER`, `LINKEDIN`

      <Expandable title="socialMedia properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Social media platforms to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Social media platforms to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Social media platforms to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Social media platforms to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.type" type="object">
      Filter by company type. Values: `PRIVATELY_HELD`, `PUBLIC_COMPANY`, `GOVERNMENT_AGENCY`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `NON_PROFIT`, `EDUCATIONAL`, `SELF_OWNED`, `SELF_EMPLOYED`

      <Expandable title="type properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Company types to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Company types to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Company types to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Company types to exclude
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.foundedYear" type="object">
      Filter by company founded year range `{start, end}`
    </ParamField>

    <ParamField body="account.employeeSize" type="object">
      Filter by employee count range

      <Expandable title="Range structure">
        <ParamField body="type" type="string">
          Must be `RANGE`
        </ParamField>

        <ParamField body="range" type="array">
          Array of `{start, end}` objects
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.revenue" type="object">
      Filter by company revenue range (same structure as employeeSize)
    </ParamField>

    <ParamField body="account.language" type="object">
      Filter by company operating language. Supports 49 languages: `english`, `spanish`, `french`, `portuguese`, `german`, `dutch`, `italian`, `chinese`, `turkish`, `polish`, `russian`, `swedish`, `arabic`, `indonesian`, `danish`, `czech`, `norwegian`, `japanese`, `korean`, `romanian`, `ukrainian`, `thai`, `hindi`, `malay`, `tagalog`, `vietnamese`, `finnish`, `persian`, `greek`, `hungarian`, `bengali`, `marathi`, `telugu`, `panjabi`, `serbian`, `slovak`, `croatian`, `lithuanian`, `latvian`, `albanian`, `icelandic`, `armenian`, `bosnian`, `tamil`, `javanese`, `malayalam`, `kannada`, `burmese`.

      <Expandable title="language properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Language enum values to include (all must match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Language enum values to exclude
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          <ParamField body="include" type="string[]" optional>
            Language enum values to include (any can match)
          </ParamField>

          <ParamField body="exclude" type="string[]" optional>
            Language enum values to exclude
          </ParamField>
        </ParamField>

        <ParamField body="range" type="object" optional>
          Range filter for number of languages
          <ParamField body="start" type="number" optional>Minimum count</ParamField>
          <ParamField body="end" type="number" optional>Maximum count</ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.geoLocation" type="object">
      Filter by geographic location

      <Expandable title="GeoLocation structure">
        <ParamField body="position" type="object">
          `{lat, lng}` coordinates
        </ParamField>

        <ParamField body="radius" type="number">
          Search radius
        </ParamField>

        <ParamField body="unit" type="string">
          `km` or `mi`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.keyword" type="object">
      Search by keywords across company data sources.

      <Expandable title="keyword properties">
        <ParamField body="all" type="object" optional>
          <ParamField body="include" type="object" optional>
            <ParamField body="sources" type="object[]" optional>
              Array of source configurations with `mode` (`SMART`, `WORD`, `STRICT`) and `source`. Sources: `NAME`, `KEYWORD`, `SEO`, `DESCRIPTION`, `INDUSTRY`
            </ParamField>

            <ParamField body="content" type="string[]" optional>
              Keywords to search for
            </ParamField>
          </ParamField>

          <ParamField body="exclude" type="object" optional>
            Same structure as include
          </ParamField>
        </ParamField>

        <ParamField body="any" type="object" optional>
          Same structure as `all`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.funding" type="object">
      Filter by funding details

      <Expandable title="Funding filter structure">
        <ParamField body="type" type="array">
          Funding types: `PRE_SEED`, `SEED`, `SERIES_A` through `SERIES_J`, `VENTURE_ROUND`, `ANGEL`, `PRIVATE_EQUITY`, `DEBT_FINANCING`, `CONVERTIBLE_NOTE`, `GRANT`, `CORPORATE_ROUND`, `EQUITY_CROWDFUNDING`, `PRODUCT_CROWDFUNDING`, `SECONDARY_MARKET`, `POST_IPO_EQUITY`, `POST_IPO_DEBT`, `POST_IPO_SECONDARY`, `NON_EQUITY_ASSISTANCE`, `INITIAL_COIN_OFFERING`, `UNDISCLOSED`, `SERIES_UNKNOWN`, `FUNDING_ROUND`
        </ParamField>

        <ParamField body="totalAmount" type="object">
          Total funding amount range `{start, end}`
        </ParamField>

        <ParamField body="lastAmount" type="object">
          Last funding round amount range `{start, end}`
        </ParamField>

        <ParamField body="duration" type="object">
          Funding date range `{start, end}` as ISO timestamps
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="account.metric" type="object">
      Filter by company metrics

      <Expandable title="Metrics filter structure">
        <ParamField body="employee" type="object[]" optional>
          Array of employee count filters by department. Each object has:

          * `function`: array of department enums (`program_and_project_management`, `education`, `purchasing`, `accounting`, `sales`, `research`, `operations`, `customer_success_and_support`, `legal`, `product_management`, `media_and_communication`, `real_estate`, `quality_assurance`, `consulting`, `arts_and_design`, `healthcare_services`, `entrepreneurship`, `engineering`, `community_and_social_services`, `marketing`, `information_technology`, `business_development`, `administrative`, `military_and_protective_services`, `finance`, `human_resources`, `support`)
          * `start`: minimum employee count
          * `end`: maximum employee count
        </ParamField>

        <ParamField body="growth" type="object[]" optional>
          Array of headcount growth filters by department. Each object has:

          * `function`: array of department enums (same as employee, also accepts custom strings)
          * `start`: minimum growth percentage
          * `end`: maximum growth percentage
          * `timeFrame`: `ONE`, `THREE`, `SIX`, `TWELVE`, or `TWENTY_FOUR` (months)
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns a paginated response containing leads (persons with associated company data).

<ResponseField name="content" type="Lead[]">
  Array of lead objects matching the search criteria

  <Expandable title="Lead object properties">
    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for the person
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the person was created. Can be null.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the person was last updated. Can be null.
    </ResponseField>

    <ResponseField name="firstName" type="string" required>
      Person's first name
    </ResponseField>

    <ResponseField name="lastName" type="string" required>
      Person's last name
    </ResponseField>

    <ResponseField name="jobTitle" type="string">
      Person's current job title. Can be null.
    </ResponseField>

    <ResponseField name="city" type="string">
      Person's city. Can be null.
    </ResponseField>

    <ResponseField name="postalCode" type="string">
      Person's postal/zip code. Can be null.
    </ResponseField>

    <ResponseField name="country" type="string">
      Person's country. Can be null.
    </ResponseField>

    <ResponseField name="linkedinUrl" type="string">
      Person's LinkedIn profile URL. Can be null.
    </ResponseField>

    <ResponseField name="phones" type="string[]">
      Array of phone numbers. Defaults to empty array.
    </ResponseField>

    <ResponseField name="emails" type="string[]">
      Array of email addresses (lowercased). Defaults to empty array.
    </ResponseField>

    <ResponseField name="companyId" type="string">
      UUID of the associated company. Can be null.
    </ResponseField>

    <ResponseField name="seniority" type="string">
      Person's seniority level. Can be null.
    </ResponseField>

    <ResponseField name="industry" type="string">
      Person's industry. Can be null.
    </ResponseField>

    <ResponseField name="departments" type="string[]">
      Array of department names. Defaults to empty array.
    </ResponseField>

    <ResponseField name="subDepartments" type="string[]">
      Array of sub-department names. Defaults to empty array.
    </ResponseField>

    <ResponseField name="functions" type="string[]">
      Array of job functions. Defaults to empty array.
    </ResponseField>

    <ResponseField name="skills" type="string[]">
      Array of skills. Defaults to empty array.
    </ResponseField>

    <ResponseField name="languages" type="Language[]">
      Array of language proficiencies with `language` and `level` fields.
    </ResponseField>

    <ResponseField name="educations" type="Education[]">
      Array of educational background with institution, degree, field of study, and dates.
    </ResponseField>

    <ResponseField name="workExperiences" type="WorkExperience[]">
      Array of work history with company details and profile positions.
    </ResponseField>

    <ResponseField name="certificates" type="Certificate[]">
      Array of certifications with name, authority, and dates.
    </ResponseField>

    <ResponseField name="linkedinProfile" type="object">
      LinkedIn profile data with headline, summary, and pictureUrl.
    </ResponseField>

    <ResponseField name="baseProviderId" type="string">
      Internal data provider identifier. Can be null.
    </ResponseField>

    <ResponseField name="crmId" type="string">
      Generic CRM identifier. Can be null.
    </ResponseField>

    <ResponseField name="leadOwnerId" type="string">
      ID of the user who owns this lead. Can be null.
    </ResponseField>

    <ResponseField name="company" type="Company">
      Associated company data. Can be null.

      <Expandable title="Company object properties">
        <ResponseField name="id" type="string" required>
          Unique identifier (UUID)
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          ISO 8601 timestamp when the company was created. Can be null.
        </ResponseField>

        <ResponseField name="updatedAt" type="string">
          ISO 8601 timestamp when the company was last updated. Can be null.
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Company name
        </ResponseField>

        <ResponseField name="description" type="string">
          Company description. Can be null.
        </ResponseField>

        <ResponseField name="summary" type="string">
          Brief company summary. Can be null.
        </ResponseField>

        <ResponseField name="headcount" type="string">
          Employee count range. Can be null.
        </ResponseField>

        <ResponseField name="industry" type="string">
          Industry classification. Can be null.
        </ResponseField>

        <ResponseField name="phones" type="string[]">
          Company phone numbers.
        </ResponseField>

        <ResponseField name="linkedinUrl" type="string">
          Company LinkedIn URL. Can be null.
        </ResponseField>

        <ResponseField name="websiteUrl" type="string">
          Company website URL. Can be null.
        </ResponseField>

        <ResponseField name="domain" type="string">
          Company domain. Can be null.
        </ResponseField>

        <ResponseField name="city" type="string">
          Headquarters city. Can be null.
        </ResponseField>

        <ResponseField name="postalCode" type="string">
          Headquarters postal code. Can be null.
        </ResponseField>

        <ResponseField name="country" type="string">
          Headquarters country. Can be null.
        </ResponseField>

        <ResponseField name="logoUrl" type="string">
          Company logo URL. Can be null.
        </ResponseField>

        <ResponseField name="legalName" type="string">
          Legal/registered company name. Can be null.
        </ResponseField>

        <ResponseField name="foundedYear" type="number">
          Year founded. Can be null.
        </ResponseField>

        <ResponseField name="revenue" type="string">
          Revenue range. Can be null.
        </ResponseField>

        <ResponseField name="location" type="object">
          Detailed location information. Can be null.
        </ResponseField>

        <ResponseField name="baseProviderId" type="string">
          Lance internal provider ID. Can be null.
        </ResponseField>

        <ResponseField name="crmId" type="string">
          Generic CRM identifier. Can be null.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalElements" type="integer">
  Total number of matching results across all pages. Can be null.
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of pages available. Can be null.
</ResponseField>

<ResponseField name="number" type="integer">
  Current page number (0-indexed). Can be null.
</ResponseField>

<ResponseField name="size" type="integer">
  Number of results per page. Can be null.
</ResponseField>

<ResponseField name="first" type="boolean">
  Whether this is the first page. Can be null.
</ResponseField>

<ResponseField name="last" type="boolean">
  Whether this is the last page. Can be null.
</ResponseField>

<ResponseField name="numberOfElements" type="integer">
  Number of elements on the current page. Can be null.
</ResponseField>

<ResponseField name="empty" type="boolean">
  Whether the result set is empty. Can be null.
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "totalElements": 1250,
    "totalPages": 125,
    "number": 0,
    "size": 10,
    "first": true,
    "last": false,
    "numberOfElements": 10,
    "empty": false,
    "content": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "firstName": "Sarah",
        "lastName": "Johnson",
        "jobTitle": "Chief Technology Officer",
        "city": "Austin",
        "postalCode": null,
        "country": "United States",
        "linkedinUrl": "https://www.linkedin.com/in/sarahjohnson",
        "phones": [],
        "emails": [],
        "companyId": "660e8400-e29b-41d4-a716-446655440001",
        "seniority": "c_suite",
        "industry": "Software",
        "departments": ["Engineering", "Technology"],
        "subDepartments": [],
        "functions": ["technology_operations", "engineering_technical"],
        "skills": ["Cloud Architecture", "Team Leadership", "Python", "AWS"],
        "languages": [{ "language": "English", "level": "Native" }],
        "educations": [
          {
            "institution": {
              "id": null,
              "name": "MIT",
              "logoUrl": null,
              "linkedinUrl": "https://www.linkedin.com/school/mit"
            },
            "degreeName": "MS",
            "fieldOfStudy": "Computer Science",
            "grade": null,
            "dates": { "start": "2008", "end": "2010" }
          }
        ],
        "workExperiences": [
          {
            "company": {
              "id": null,
              "name": "TechStartup Inc",
              "logoUrl": "https://logo.example.com/techstartup.png",
              "linkedinUrl": "https://www.linkedin.com/company/techstartup",
              "employees": { "start": "100", "end": "250" }
            },
            "dates": { "start": "2021-03", "end": null },
            "profilePositions": [
              {
                "company": "TechStartup Inc",
                "description": "Leading technology strategy and engineering teams",
                "title": "Chief Technology Officer",
                "employmentType": "Full-time",
                "location": "Austin, TX",
                "dates": { "start": "2021-03", "end": null }
              }
            ]
          }
        ],
        "certificates": [],
        "linkedinProfile": {
          "headline": "CTO at TechStartup Inc | Building Scalable Solutions",
          "summary": "Technology leader with 15+ years of experience...",
          "pictureUrl": "https://media.licdn.com/dms/image/..."
        },
        "baseProviderId": "baseProvider_person_abc123",
        "bullhornId": null,
        "crmId": null,
        "leadOwnerId": null,
        "consentStatus": "UNKNOWN",
        "consentSource": null,
        "consentUpdatedAt": null,
        "deletedAt": null,
        "birthDate": null,
        "company": {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "updatedAt": "2024-01-15T10:30:00.000Z",
          "name": "TechStartup Inc",
          "description": "Innovative software company focused on enterprise solutions",
          "summary": "Enterprise SaaS provider",
          "headcount": "100-250",
          "industry": "Software",
          "phones": [],
          "linkedinUrl": "https://www.linkedin.com/company/techstartup",
          "websiteUrl": "https://www.techstartup.com",
          "domain": "techstartup.com",
          "city": "Austin",
          "postalCode": "78701",
          "country": "United States",
          "logoUrl": "https://logo.example.com/techstartup.png",
          "legalName": "TechStartup Inc.",
          "foundedYear": 2018,
          "revenue": "$10M-$50M",
          "baseProviderId": "baseProvider_company_xyz789",
          "bullhornId": null,
          "crmId": null,
          "location": null
        }
      }
    ]
  }
  ```

  ```json 200 - Empty Results theme={null}
  {
    "totalElements": 0,
    "totalPages": 0,
    "number": 0,
    "size": 10,
    "first": true,
    "last": true,
    "numberOfElements": 0,
    "empty": true,
    "content": []
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request body",
      "details": [
        {
          "path": ["size"],
          "message": "Number must be less than or equal to 100"
        }
      ]
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Unauthorized"
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

## Request Examples

### Basic Search - CTOs in Software Industry

```json theme={null}
{
  "contact": {
    "seniority": {
      "any": {
        "include": ["c_suite"]
      }
    },
    "experience": {
      "current": {
        "title": {
          "any": {
            "include": {
              "mode": "SMART",
              "content": ["CTO", "Chief Technology Officer"]
            }
          }
        }
      }
    }
  },
  "account": {
    "industry": {
      "any": {
        "include": ["software development", "software"]
      }
    }
  },
  "page": 0,
  "size": 25
}
```

### Search by Company Size and Location

```json theme={null}
{
  "contact": {
    "departmentAndFunction": {
      "any": {
        "include": ["sales", "business_development"]
      }
    },
    "location": {
      "any": {
        "include": ["San Francisco", "New York", "Boston"]
      }
    }
  },
  "account": {
    "employeeSize": {
      "type": "RANGE",
      "range": [{ "start": 50, "end": 500 }]
    }
  },
  "page": 0,
  "size": 50
}
```

### Search by Skills and Funding Stage

```json theme={null}
{
  "contact": {
    "skill": {
      "any": {
        "include": {
          "mode": "SMART",
          "content": ["Machine Learning", "AI", "Python"]
        }
      }
    }
  },
  "account": {
    "funding": {
      "type": ["SERIES_A", "SERIES_B", "SERIES_C"]
    }
  },
  "page": 0,
  "size": 20
}
```

### Search by Keywords Across Profile Sources

```json theme={null}
{
  "contact": {
    "keyword": {
      "any": {
        "include": {
          "sources": [
            { "mode": "SMART", "source": "HEADLINE" },
            { "mode": "SMART", "source": "SUMMARY" },
            { "mode": "SMART", "source": "SKILL" }
          ],
          "content": ["data engineering", "ETL", "data pipeline"]
        }
      }
    }
  },
  "page": 0,
  "size": 25
}
```

### Search by Experience Duration

```json theme={null}
{
  "contact": {
    "seniority": {
      "any": {
        "include": ["manager", "director"]
      }
    },
    "experience": {
      "current": {
        "duration": {
          "currentCompany": {
            "min": { "year": 2, "month": 0 },
            "max": { "year": 5, "month": 0 }
          },
          "total": {
            "min": { "year": 8, "month": 0 }
          }
        }
      }
    }
  },
  "page": 0,
  "size": 20
}
```

### Search People Open to Work

```json theme={null}
{
  "contact": {
    "profileBadge": {
      "any": {
        "include": ["OPEN_TO_WORK"]
      }
    },
    "departmentAndFunction": {
      "any": {
        "include": ["software_development", "data_science"]
      }
    }
  },
  "page": 0,
  "size": 25
}
```

## How It Works

1. **Authentication**: The endpoint authenticates the user via Clerk
2. **Validation**: Request body is validated against the `PeopleSearch_Body` schema
3. **Search**: Queries the Lance database with the provided filters
4. **Mapping**: Maps external provider response data to Lance domain objects (Person and Company)
5. **Persistence**: Companies and persons are upserted to the global database using merge logic to preserve existing data
6. **Response**: Returns the enriched leads with associated company data

<Info>
  Results are automatically deduplicated during the upsert process. If a person
  or company already exists in the database (matched by external IDs or other
  identifiers), the records are merged rather than duplicated.
</Info>

## Notes

* Search results are persisted to the database, making subsequent searches faster for the same prospects
* The external provider integration uses rate limiting (5 requests per second) to avoid overwhelming the external service
* Company data is extracted from the person's current position or position groups if available
* The `companyId` field in the response links each person to their saved company record
* External provider IDs (`baseProviderId`) are preserved to enable future enrichment and deduplication