--- title: "Search companies by filters" method: POST path: "/v1/search/companies" tags: ["enrichment"] --- # Search companies by filters `POST /v1/search/companies` ## Request - Base URL: `https://developer.saleshandy.com` (the document declares no server; this is the origin it was published from) - URL: `https://developer.saleshandy.com/v1/search/companies` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Request body - SearchCompaniesOpenAPIDto - `signalIds` number[] - `newsIds` number[] - `company_name` CompanyNameFilterDto - `includes` string[] - `excludes` string[] - `exactMatch` 0 | 1 - `company_hq_location` CompanyIncludesExcludesFilterDto - `includes` string[] - `excludes` string[] - `exactMatch` 0 | 1 - `company_founded_year` CompanyRangeFilterDto - `min` string - `max` string - `company_industry` CompanyIndustryIncludesExcludesDto - `includes` string[] - `excludes` string[] - `company_domain` CompanyIncludesExcludesSimpleFilterDto - `includes` string[] - `excludes` string[] - `type` 'Privately Held' | 'Public Company' | 'Self-Owned' | 'Self-Employed' | 'Partnership' | 'Nonprofit' | 'Educational' | 'Government Agency' - `sic_codes` CompanyIncludesFilterDto - `includes` string[] - `naics_codes` CompanyIncludesFilterDto - `includes` string[] - `product_reviews_score_change` ProductReviewScoreChangeFilter - `duration` 'current' | 'monthly' | 'quarterly' | 'yearly' - `direction` 'up' | 'down' | 'any' - `points_range` CompanyRangeFilterDto - `min` string - `max` string - `is_b2b` boolean - `technologies_used` CompanyIncludesFilterDto - `includes` string[] - `last_funding_round_name` LastFundingRoundNameIncludesDto - `includes` string[] - `last_funding_round_amount_raised` CompanyRangeFilterDto - `min` string - `max` string - `last_funding_round_announced_date` CompanyRangeFilterDto - `min` string - `max` string - `funding_rounds_name` FundingRoundsNameIncludesDto - `includes` string[] - `company_funding_amount` CompanyRangeFilterDto - `min` string - `max` string - `company_funding_date` CompanyRangeFilterDto - `min` string - `max` string - `company_annual_revenue` CompanyRangeFilterDto - `min` string - `max` string - `company_size` CompanyRangeFilterDto - `min` string - `max` string - `employee_count_seniority` SeniorityCountFilterDto[] - `group` 'owner' | 'founder' | 'clevel' | 'partner' | 'vp' | 'head' | 'director' | 'manager' | 'senior' | 'mid' | 'junior' | 'intern' | 'specialist' | 'other_management' - `count` CompanyRangeFilterDto - `min` string - `max` string - `employee_count_department` DepartmentCountFilterDto[] - `group` 'medical' | 'sales' | 'hr' | 'legal' | 'marketing' | 'finance' | 'technical' | 'consulting' | 'operations' | 'product' | 'general_management' | 'administrative' | 'customer_service' | 'project_management' | 'design' | 'research' | 'trades' | 'real_estate' | 'education' | 'other_department' - `count` CompanyRangeFilterDto - `min` string - `max` string - `base_salary` BaseSalaryFilterDto[] - `title` CompanyIncludesExcludesFilterDto - `includes` string[] - `excludes` string[] - `exactMatch` 0 | 1 - `range` CompanyRangeFilterDto - `min` string - `max` string - `ownership_status` 'Private' | 'Public' | 'Other' - `website` CompanyIncludesFilterDto - `includes` string[] - `look_alike_company_name` LookAlikeFilterDto[] - `value` string - `company_id` number - `_company_name` string - `_industry` string - `_categories_and_keywords` string[] - `_technologies_used` string[] - `_competitors` string[] - `_annual_revenue` number - `_followers_count_linkedin` number - `_total_website_visits_monthly` number - `_ownership_status` string - `linkedin_url` CompanyIncludesExcludesFilterDto - `includes` string[] - `excludes` string[] - `exactMatch` 0 | 1 - `followers_count_linkedin` CompanyRangeFilterDto - `min` string - `max` string - `active_job_postings_title` CompanyIncludesFilterDto - `includes` string[] - `active_job_postings_count` CompanyRangeFilterDto - `min` string - `max` string - `total_website_visits_monthly` CompanyRangeFilterDto - `min` string - `max` string - `rank_global` CompanyRangeFilterDto - `min` string - `max` string - `visits_breakdown_by_country` VisitsBreakdownByCountryFilterDto[] - `country` string - `percentage` CompanyRangeFilterDto - `min` string - `max` string - `visits_breakdown_by_gender` VisitsBreakdownByGenderFilterDto[] - `gender` 'male' | 'female' - `percentage` CompanyRangeFilterDto - `min` string - `max` string - `product_reviews_aggregate_score` CompanyRangeFilterDto - `min` string - `max` string - `product_reviews_count` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_total_count` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_aggregate_score` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_business_outlook` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_ceo_approval` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_career_opportunities` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_recommend` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_work_life_balance` CompanyRangeFilterDto - `min` string - `max` string - `employee_reviews_culture_values` CompanyRangeFilterDto - `min` string - `max` string - `keywords` CompanyIncludesFilterDto - `includes` string[] - `social_urls` CompanyIncludesFilterDto - `includes` string[] - `page` number - `tab` 'total' | 'netNew': Which results to search. `netNew` returns only leads/companies not yet revealed by your account; `total` returns all matches, including ones you have already revealed. ## Response `201` Companies searched successfully - union - object - `message` string - `payload` object - `status` string: Search status string, e.g. "success". - `display_limit` number: Maximum number of results the account is allowed to retrieve for this search. - `total_results` number: Total number of matching results across all pages. - `page` number: Current page number, matching the request's `page` parameter. - `per_page` number: Number of results returned on this page. - `total_pages` number: Total number of pages available. - `has_next_page` boolean: Whether a page after the current one exists. - `has_previous_page` boolean: Whether a page before the current one exists. - `company` object[]: The matching companies for this page. Named `company` (singular), not `companies`. When there are zero matching results, `payload` itself becomes the literal empty array `[]` instead of an object containing this field. Client code reading `payload.company` should confirm `payload` is not itself an array first (e.g. `Array.isArray(payload)`). - `id` number: Numeric identifier for this company. - `name` string: Company name. - `linkedin_url` string: LinkedIn company page URL. Empty string when not available. - `website_domain` string: Primary website domain (no scheme), e.g. "acme.com". Empty string when not available. - `twitter_url` string: Twitter/X profile URL. Key omitted when url not available - `discord_url` string: Discord server URL. Key omitted when url not available - `facebook_url` string: Facebook page URL. Key omitted when url not available - `instagram_url` string: Instagram profile URL. Key omitted when url not available - `pinterest_url` string: Pinterest profile URL. Key omitted when url not available - `tiktok_url` string: TikTok profile URL. Key omitted when url not available - `youtube_url` string: YouTube channel URL. Key omitted when url not available - `github_url` string: GitHub organization URL. Key omitted when url not available - `reddit_url` string: Reddit profile/subreddit URL. Key omitted when url not available - `crunchbase_url` string: Crunchbase organization URL. Key omitted when url not available - `location` object: Company's headquarters location. - `city` string: City name. Can be an empty string. - `state` string: State or province name. Can be an empty string. - `country` string: Country name. Can be an empty string. - `company_locations` object[]: All known locations for this company. Exactly one entry has `is_primary: true` and carries the structured fields (`country`, `city`, `state`, `street`, `zip_code`, `regions`); non-primary entries usually contain only `location_address` and `is_primary`. Structured fields are omitted (not `null`) when unknown. - `location_address` string: Free-form address string. Can be an empty string. - `is_primary` boolean: Whether this is the primary (headquarters) location. - `country` string: Country name. Present only on the primary location when known. - `city` string: City name. Present only on the primary location when known. - `state` string: State or province name. Present only on the primary location when known. - `street` string: Street address. Present only on the primary location when known. - `zip_code` string: Postal code. Present only on the primary location when known. - `regions` string[]: Geographic region tags for the location, e.g. ["Europe", "Northern Europe", "EMEA", "EU"]. Present only on the primary location when known. - `founded_year` number: Year the company was founded. Can be returned as an empty string "" instead of a number when unknown. - `industry` string: Company industry. Can be an empty string. - `type` string, nullable: Company type, or `null` when unknown. Otherwise one of "Privately Held", "Public Company", "Self-Owned", "Self-Employed", "Partnership", "Nonprofit", "Educational", "Government Agency". These are the same values accepted by the request-side `type` filter. This response field loosely, but not exactly, correlates with the separate `ownership_status` request-side filter. - `is_b2b` boolean, nullable: Whether the company is flagged as B2B. `null` when unknown. - `sic_codes` string[]: SIC (Standard Industrial Classification) codes for this company. Empty array when the company has none. - `naics_codes` string[]: NAICS (North American Industry Classification System) codes for this company. Empty array when the company has none. - `employee_count` number, nullable: Total employee count. Occasionally `null`. - `revealType` 'enriched' | 'notEnriched' | 'imported', nullable: How this company was enriched or added to your account. `null` when not saved. - `socials` string[]: Aggregated social and web presence links for this company — LinkedIn, website, Twitter/X, Facebook, Instagram, YouTube, Crunchbase, etc. All platforms are mixed together in one array with no per-item label. May contain more entries than the dedicated `*_url` fields (e.g. alternate pages or secondary domains). Prefer the dedicated `*_url` / `website_domain` fields when you need a specific platform. - object - `message` string - `payload` unknown[]: Empty when no results match — `payload` itself becomes a literal empty array instead of an object with an empty `company` array. Client code should check `Array.isArray(payload)` before reading `payload.company`. - unknown ## Other responses - `400`: 1001: Invalid token

## Changes - **2026-10-23** `e7a29c931aa7`: 1 breaking, 1 warning, 15 info - added `#/components/schemas/CompanyNameFilterDto` to the `company_name` request property `allOf` list - removed `#/components/schemas/CompanyIncludesExcludesSimpleFilterDto` from the `company_name` request property `allOf` list - added the new optional request property `tab` - added the optional property `oneOf[subschema #1: Success]/payload/company/items/company_locations` to the response with the `201` status - …13 more - **2026-09-18** `78695b8296c5`: 4 breaking, 8 info - removed the enum value `Private` of the request property `type` - removed the enum value `Public` of the request property `type` - the response property `oneOf[subschema #1: Success]/payload/company/items/is_b2b` became nullable for the status `201` - the response property `oneOf[subschema #1: Success]/payload/company/items/type` became nullable for the status `201` - …8 more - …earlier changes not shown [Operation history](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy/changes/v1/search/companies/post.md) --- [API](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy.md) - [All operations](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy/llms.txt) - [OpenAPI document](https://skmtc.dev/saleshandy/apis/develop-with-saleshandy/revisions/e7a29c931aa7?raw)