--- title: "Search Companies" method: POST path: "/v2/companies/search" tags: ["Companies"] --- # Search Companies `POST /v2/companies/search` ## Request - Base URL: `https://api.village.ai` - URL: `https://api.village.ai/v2/companies/search` - Auth: HTTP bearer Search for companies using natural language queries. Pass your search text in the "prompt" field (not "query"). Use this to find companies matching specific criteria like industry, location, funding stage, or technology. Examples: "AI startups in San Francisco", "Series B fintech companies", "healthcare companies using Python". By default this searches only companies connected to the caller’s own network; pass scope: "global" to search everyone. Returns matching companies with relevance scores and connection strength. 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. ## Request body - CompaniesSearchRequest: Request body for searching companies with a natural-language prompt or structured filters. Send one form; prompt and filters cannot be combined. - `prompt` string: Natural language search query - `filters` CompanyFilterJson: Structured company filters, compiled deterministically. Send filters without a prompt. - `name` union: Company name (partial match). - string - string[] - `domain` union: Company domain (exact match). - string - string[] - `linkedinUrl` union: Company LinkedIn URL. - string - string[] - `linkedinId` union: Company LinkedIn identifier. - string - string[] - `industry` union: Industry classification, matched exactly against canonical LinkedIn industry names. Values must be canonical — 487 are allowed, and anything else is rejected. - string - string[] - `industryNot` union: Excludes matches on: Industry classification, matched exactly against canonical LinkedIn industry names. Values must be canonical — 487 are allowed, and anything else is rejected. - string - string[] - `companySize` union: Employee count range (e.g., "50-200", "500+"). - string - string[] - `companySizeNot` union: Excludes matches on: Employee count range (e.g., "50-200", "500+"). - string - string[] - `includeEstimatedHeadcount` true: Optional employee-size modifier: allow a fully contained estimated interval only when the reported employee count is unknown; requires companySize or companySizeNot. - `companyType` union: Company type (e.g., "Public Company", "Privately Held"). Canonical values: Privately Held, Self-Owned, Self-Employed, Partnership, Public Company, Nonprofit, Educational, Government Agency. - string - string[] - `companyTypeNot` union: Excludes matches on: Company type (e.g., "Public Company", "Privately Held"). Canonical values: Privately Held, Self-Owned, Self-Employed, Partnership, Public Company, Nonprofit, Educational, Government Agency. - string - string[] - `investorType` union: Canonical investor organization type. Canonical values: Accelerator, Angel Group, Corporate Venture Capital, Co-Working Space, Entrepreneurship Program, Family Investment Office, Fund of Funds, Government Office, Hedge Fund, Incubator, Investment Bank, Micro-VC, Pension Fund, Private Equity Firm, Secondary Purchaser, Startup Competition, Syndicate, University Program, Venture Capital, Venture Debt. - string - string[] - `investorTypeNot` union: Excludes matches on: Canonical investor organization type. Canonical values: Accelerator, Angel Group, Corporate Venture Capital, Co-Working Space, Entrepreneurship Program, Family Investment Office, Fund of Funds, Government Office, Hedge Fund, Incubator, Investment Bank, Micro-VC, Pension Fund, Private Equity Firm, Secondary Purchaser, Startup Competition, Syndicate, University Program, Venture Capital, Venture Debt. - string - string[] - `fundingStage` union: Most-recent funding round stage (e.g., "Series B"). Matches the latest round only — a company whose newest round is "Debt financing" will not match "Series B". Canonical values: Seed, Pre seed, Angel, Series A, Series B, Series C, Series D, Series E, Series F, Series G, Series H, Series I, Series J, Series unknown, Private equity, Post IPO equity, Post IPO debt, Post IPO secondary, Debt financing, Convertible note, Corporate round, Grant, Non equity assistance, Equity crowdfunding, Product crowdfunding, Initial coin offering, Secondary market, Undisclosed. - string - string[] - `fundingStageNot` union: Excludes matches on: Most-recent funding round stage (e.g., "Series B"). Matches the latest round only — a company whose newest round is "Debt financing" will not match "Series B". Canonical values: Seed, Pre seed, Angel, Series A, Series B, Series C, Series D, Series E, Series F, Series G, Series H, Series I, Series J, Series unknown, Private equity, Post IPO equity, Post IPO debt, Post IPO secondary, Debt financing, Convertible note, Corporate round, Grant, Non equity assistance, Equity crowdfunding, Product crowdfunding, Initial coin offering, Secondary market, Undisclosed. - string - string[] - `locations` string: Structured headquarters locations, as a JSON string: { "locations": [{ "id", "type": "city" | "region" | "country", "name" }], "radius"?: { "value", "unit": "kilometers" } }, 1-60 selections. The ids come from the location picker, so callers without them should use country or city instead. - `locationsNot` string: Excludes matches on: Structured headquarters locations, as a JSON string: { "locations": [{ "id", "type": "city" | "region" | "country", "name" }], "radius"?: { "value", "unit": "kilometers" } }, 1-60 selections. The ids come from the location picker, so callers without them should use country or city instead. - `country` union: Headquarters country filter (exact ISO country match). - string - string[] - `countryNot` union: Excludes matches on: Headquarters country filter (exact ISO country match). - string - string[] - `city` union: City/region filter resolved through standardized headquarters. - string - string[] - `cityNot` union: Excludes matches on: City/region filter resolved through standardized headquarters. - string - string[] - `foundedAfter` integer: Minimum founding year. - `foundedBefore` integer: Maximum founding year. - `companyKeywords` union: Company profile keywords (full-text over name, about, specialties, categories, slogan); comma-separated phrases are ORed. - string - string[] - `hiring` union: Open job title(s) the company is hiring for. - string - string[] - `hiringMinOpenings` integer: Minimum number of qualifying open jobs at the company (with hiring: openings matching those titles). - `totalFundingMinUsd` integer: Minimum historical recorded total funding in whole USD (inclusive). - `totalFundingMaxUsd` integer: Maximum historical recorded total funding in whole USD (inclusive). - `lastRoundMinUsd` integer: Minimum last recorded funding round amount in whole USD (inclusive). - `lastRoundMaxUsd` integer: Maximum last recorded funding round amount in whole USD (inclusive). - `lastFundingDateAfter` string: Earliest last recorded funding date, inclusive, as a real YYYY-MM-DD date. - `lastFundingDateBefore` string: Latest last recorded funding date, inclusive, as a real YYYY-MM-DD date. - `backedBy` union: Company backed by a recorded investor LinkedIn company identifier or URL. - string - string[] - `backedByNot` union: Excludes matches on: Company backed by a recorded investor LinkedIn company identifier or URL. - string - string[] - `portfolio` union: Investor whose recorded portfolio includes the given LinkedIn company identifier or URL. - string - string[] - `portfolioNot` union: Excludes matches on: Investor whose recorded portfolio includes the given LinkedIn company identifier or URL. - string - string[] - `investorStages` union: Investor stages observed in historical recorded portfolio rounds. Canonical values: Seed, Early Stage Venture, Late Stage Venture, Private Equity. - string - string[] - `investorStagesNot` union: Excludes matches on: Investor stages observed in historical recorded portfolio rounds. Canonical values: Seed, Early Stage Venture, Late Stage Venture, Private Equity. - string - string[] - `investorCategories` union: Exact category tags in the historical investor portfolio (case-insensitive). - string - string[] - `investorCategoriesNot` union: Excludes matches on: Exact category tags in the historical investor portfolio (case-insensitive). - string - string[] - `investorRoundSizeMinUsd` integer: Minimum historical median portfolio round amount in whole USD (inclusive), not check size. - `investorRoundSizeMaxUsd` integer: Maximum historical median portfolio round amount in whole USD (inclusive), not check size. - `hiringWorkplace` union: Reported Remote, Hybrid or On-site workplace of the same qualifying open jobs. Canonical values: Remote, Hybrid, On-site. - string - string[] - `hiringCountry` union: Reported country of qualifying open jobs, as known country names or ISO codes. - string - string[] - `hiringEmploymentType` union: Reported employment type group of qualifying open jobs. Canonical values: Full-time, Part-time, Contract/Temporary, Internship, Permanent. - string - string[] - `hiringDepartment` union: Exact reported job department labels (case-insensitive), not inferred from titles. - string - string[] - `hiringPostedWithinDays` integer: Qualifying jobs posted within this many days (integer 1–180). - `limit` integer: Maximum number of results per page - `mode` 'auto' | 'lookup' | 'simple' | 'complex': Search mode for prompt-only searches: auto (let system decide), lookup (direct match), simple (LLM-powered), or complex (thinking + high-reasoning SQL generation). Structured filters always compile deterministically. - `scope` 'network' | 'global': Search scope: network (connections first) or global (all companies) - `stream` boolean: Enable SSE streaming for progressive results - `cursor` union: Pagination cursor (encoded string or cursor object) - string - CompanySearchCursor: Cursor for paginated company search results - `source` 'network' | 'global' - `chunk_skip` integer - `results_skip` integer - `cumulative_results` integer - `network_filters` object: Network path and relationship filters - `connection_degrees` integer[] - `introducer_linkedin_ids` string[] - `user_to_introducer_types` string[] - `user_to_introducer_min_score` 'excellent' | 'very_good' | 'good' | 'okay' | 'maybe' | 'no_path' - `introducer_to_target_types` string[] - `introducer_to_target_min_score` 'excellent' | 'very_good' | 'good' | 'okay' | 'maybe' | 'no_path' - `exclude_teams` boolean - `exclude_community` boolean - `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. - `list_filter` object: Search within your saved lists. company_list_id restricts results to the members of that company list; people_list_id restricts results to the current employers of the people in that people list. Both may be combined (AND) and with any prompt or filter. A list alone is a valid search. Lists must belong to your active workspace. - `people_list_id` integer - `company_list_id` integer - `screening_handoff` boolean: Complex searches keep only objective constraints in SQL and return the subjective ones as metadata.screening_criteria for a downstream screening step. ## Response `200` Search completed successfully - object - `data` SearchResultCompany[], required: Array of companies matching the search query - `id` string, required - `name` string, required - `domain` string, nullable - `linkedin_url` string, nullable - `website` string, nullable - `employee_count` number, nullable - `industry` string, nullable - `description` string, nullable - `location` string, nullable - `warmth_score` number, nullable - `warmth_label` string, nullable - `metadata` object, required - `request_id` string, required - `mode` 'lookup' | 'simple' | 'complex' - `source` 'network' | 'global' - `network_stage_complete` boolean - `generated_sql` string - `search_engine` string - `counts_token` string - `search_execution_token` string - `counts` object - `global` object - `value` number, nullable, required - `is_capped` boolean, required - `cap` number, required - `network` object - `value` number, nullable, required - `is_estimated` boolean, required - `cache_hit` boolean - `plan_disclosure` object: Present only when the prompt-to-filters engine served the search: the filters it ran on, in words, and every approximation it made. - `sentence` string, required - `approximations` string[], required - `pagination` PaginationInfo, required: Cursor-based pagination metadata - `cursor` string, nullable, required: Opaque cursor for fetching the next page (null if no more results) - `has_next_page` boolean, required: Whether more results are available - `count` integer, required: Total number of results or count of items in current page ## Other responses - `400`: Bad request - invalid parameters - `401`: Unauthorized - missing or invalid authentication - `422`: Validation error - invalid request format --- [API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)