People

Search People

Search for people using natural language queries. Pass your search text in the "prompt" field (not "query"). Use this to find professionals matching specific criteria like job titles, companies, industries, or skills. Examples: "engineers at Google", "investors in fintech", "product managers in San Francisco". By default this searches only the caller’s own network; pass scope: "global" to search everyone. Returns matching profiles with relevance scores. Supports cursor-based pagination for large result sets. Expect this to be slow: complex searches usually take 20-60 seconds. Wait for it to finish rather than retrying or assuming it failed.

post/v2/people/search

Request

  • Base URL: https://api.village.ai
  • URL: https://api.village.ai/v2/people/search
  • Auth: HTTP bearer

Request body

promptstring

Natural language search query

limitinteger

Maximum number of results per page

mode'auto' | 'lookup' | 'simple' | 'complex'

Search execution mode. "auto" classifies the query into lookup/simple/complex. Use "lookup" for direct matches, "simple" for firmographic queries, and "complex" for multi-step or subjective queries.

streamboolean

Enable Server-Sent Events (SSE) streaming for real-time results

scope'network' | 'global' | 'specific_list'

Override default scope. Defaults: lookup=global, simple=network, complex=network. "network" searches your connections first, "global" searches everyone.

include_counts'global' | 'network' | 'all'

Inline count scopes to compute on the first page only. Use "global", "network", or "all". Ignored when cursor is provided and adds latency.

screening_handoffboolean

Complex searches keep only objective constraints in SQL and return the subjective ones as metadata.screening_criteria for a downstream screening step.

Example request

{
  "prompt": "Find CTOs at SaaS companies in San Francisco",
  "filters": {
    "dropout": true,
    "lastJobChangeMonths": 6,
    "yearsOfExperienceMin": 5,
    "yearsOfExperienceMax": 15,
    "averageTenureMonthsMin": 12,
    "averageTenureMonthsMax": 60,
    "roleDurationMonthsMin": 12,
    "roleDurationMonthsMax": 60,
    "pastRoleDurationMonthsMin": 12,
    "pastRoleDurationMonthsMax": 60,
    "currentRoleTenureMonthsMin": 12,
    "currentRoleTenureMonthsMax": 60
  },
  "limit": 25,
  "list_filter": {
    "people_list_id": 123
  }
}

Response

Search completed successfully

Example response

{
  "data": [
    {
      "id": 11111,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "headline": "CEO at Acme Corporation",
      "work_relevant": {
        "title": "Chief Executive Officer",
        "company": {
          "id": 11111,
          "name": "Acme Corporation",
          "linkedin_url": "https://linkedin.com/company/acme",
          "domain": "acme.com",
          "website": "https://acme.com",
          "industry": "Technology",
          "employee_count": 5000,
          "image_url": "https://logo.clearbit.com/acme.com",
          "headquarters": "San Francisco, California, United States",
          "type": "Public",
          "founded_year": 2015
        },
        "start_date": "2020-01-15"
      },
      "image_url": "https://media.licdn.com/dms/image/..."
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMzQ1In0",
    "has_next_page": true,
    "count": 20
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.