View as Markdown

Company Search

POST/v2/companies/search

Search our company database by identity, company attributes and free-text keywords. Look up specific companies by name, domain or LinkedIn id, or build a target list by industry, location (city, state, country or region), headcount, founded year, company type, business type, revenue stream and NAICS codes: filters AND together, and at least one include condition is required. Results return 25 per page by default (per_page: 25, 50 or 100), sorted by relevance when keywords are present and by followers otherwise - see the body parameters below for every filter and its nuances. Free: spends no credits; 1 unit of the search rate limit per 25 results. Authenticate with your API key in the x-api-key header.

How are credits spent?

Company Search is free. Searching and paging through results never charges credits - credits are only spent when you enrich people or reveal contact data on other endpoints.

How filtering works

Send one filters object. Every filter is optional, but at least one include condition is required (exclude-only searches are rejected), and a request can carry at most 20,000 filter values in total. Most filters share the same shape - an include list ("match any of these") and an exclude list ("reject these") - and all active filters combine with AND:

  • Identity filters (company.id, company.name, company.domain, company.linkedin_id) look up specific companies you already know - the same keys as People Search's company filter.
  • Company attribute filters describe the kind of company: company_industry, company_country (any office location by default, headquarters_only to restrict), headcount (company_headcount_range buckets or company_headcount_custom raw numbers), company_founded, company_type, company_business_type, company_revenue_stream, and company_naics.
  • company_keywords matches free-text phrases across the company's profile; narrow it with sources and include_all.

Enum-backed filters only accept values from Enums; each parameter below links to its own value list.

Companies you already know

company.id takes our own company id - the value on every result here and on every Company Enrich response. It is the exact way to name companies you have already resolved, and the one identifier that can never be ambiguous: a name or a domain can be shared by several companies, while an id names exactly one.

So when you start from something like a company website or LinkedIn URL, the reliable path is two steps - enrich first, keep the ids, then filter by them:

  1. Call Company Enrich with the domain, name, linkedin_url or linkedin_id you hold, and read id off the response.
  2. Send those ids here as company.id.include (up to 20,000 per request - the request-wide filter-value cap), or to People Search's company.id filter, which takes the same value.

company.id.exclude rejects companies the same way, and - like every other exclude - it needs at least one include filter beside it.

This two-step is also the answer for LinkedIn: company.linkedin_id takes LinkedIn's numeric company id, never a linkedin.com/company/... URL. Enrich the URL into an id and filter on that.

Finding the people who work there

Each result carries an id. Pass those ids to People Search's company.id filter to list the people working at the companies you found - the classic two-step for building an account-based prospect list.

Sorting and pagination

Results come back 25 per page by default; set per_page to 50 or 100 for bigger pages. A search reaches 25,000 results at any page size: page 1000 at 25, page 250 at 100. The default order is relevance when company_keywords is present and follower count otherwise; override it with sort_by and sort_direction. The response metadata echoes the sort_by / sort_direction that actually ran, so you can confirm which default kicked in. See Pagination for the response envelope and paging patterns.

Body parameters

  • filtersobjectrequired

    Filter configuration. Active filters AND together and at least one include condition is required (exclude-only searches are rejected). A request can carry at most 20,000 filter values in total. See Enums for allowed values per enum filter.

    Child attributes
    • companyobjectoptional

      Look up specific companies you already know - by our own id (the exact one, as returned by Company Enrich), by exact name, by web domain, or by numeric linkedin_id. The same keys as People Search's company filter.

      Child attributes
      • idobjectoptional

        Match by our company id, as returned by this endpoint and by Company Enrich. The exact way to name companies you have already resolved.

        FieldTypeDescription
        includestring[]Only these companies, by id. Max 20000 ids.

        Example: ["64f1a2b3c4d5e6f7a8b9c0d2"]

        excludestring[]Reject these companies (same id values). Max 20000 ids.
      • nameobjectoptional

        Match by company name. Exact, case-insensitive list lookup. A value shaped like a website ("stripe.com", "https://www.stripe.com/about") also matches the company on that domain.

        FieldTypeDescription
        includestring[]Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
        excludestring[]Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
      • domainobjectoptional

        Match by web domain - host only, without scheme or www (e.g. "getprospect.com"). Every domain attached to a company is considered, not just the primary one.

        FieldTypeDescription
        includestring[]Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
        excludestring[]Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
      • linkedin_idobjectoptional

        Match by LinkedIn's numeric company id. Company URLs go through Company Enrich first - see id.

        FieldTypeDescription
        includeinteger[]Match these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by linkedin_url first, then filter by the id that comes back. Max 500 items.

        Example: [162479]

        excludeinteger[]Reject these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by linkedin_url first, then filter by the id that comes back. Max 500 items.
      Example
      {
        "filters": {
          "company": {
            "domain": {
              "include": [
                "intercom.com",
                "stripe.com"
              ]
            }
          }
        }
      }
    • company_industryobjectoptional

      Industry name, or one of the category GROUP names Industries groups them under - a group matches every industry in that category. Same vocabulary as People Search's own company_industry.

      FieldTypeDescription
      includestring[]Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
      excludestring[]Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
      Example
      {
        "filters": {
          "company_industry": {
            "include": [
              "Software & Internet",
              "IT Services & IT Consulting"
            ],
            "exclude": [
              "Staffing & Recruiting"
            ]
          }
        }
      }
    • company_typeobjectoptional

      Company legal/ownership type (see Company types). Values match case-insensitively.

      FieldTypeDescription
      includeenum[]Company types to match (any of).

      Allowed values: Privately Held Public Company Non Profit Self Owned Self Employed Partnership Educational Government Agency Unknown

      excludeenum[]Company types to reject.

      Allowed values: Privately Held Public Company Non Profit Self Owned Self Employed Partnership Educational Government Agency Unknown

      Example
      {
        "filters": {
          "company_type": {
            "include": [
              "Privately Held",
              "Public Company"
            ]
          }
        }
      }
    • company_business_typeobjectoptional

      Audience type (see Business types). Values: B2B, B2C, Nonprofit, Unknown.

      FieldTypeDescription
      includeenum[]Business types to match (any of).

      Allowed values: B2B B2C Nonprofit Unknown

      excludeenum[]Business types to reject.

      Allowed values: B2B B2C Nonprofit Unknown

      Example
      {
        "filters": {
          "company_business_type": {
            "include": [
              "B2B"
            ]
          }
        }
      }
    • company_revenue_streamobjectoptional

      Revenue model (see Revenue streams). Values match case-insensitively.

      FieldTypeDescription
      includeenum[]Revenue streams to match (any of).

      Allowed values: Professional Services Product Sales Grants / Donations Subscriptions / Recurring Project / Contract Work Event / Experience Revenue Transaction Fees Rental / Leasing Advertising Financial Services Licensing / IP Unknown

      excludeenum[]Revenue streams to reject.

      Allowed values: Professional Services Product Sales Grants / Donations Subscriptions / Recurring Project / Contract Work Event / Experience Revenue Transaction Fees Rental / Leasing Advertising Financial Services Licensing / IP Unknown

      Example
      {
        "filters": {
          "company_revenue_stream": {
            "include": [
              "Subscriptions / Recurring",
              "Product Sales"
            ]
          }
        }
      }
    • company_countryobjectoptional

      Country as ISO-3166-1 alpha-2 codes (see Countries). Matches any office location by default; set headquarters_only: true to match the registered headquarters country only.

      FieldTypeDescription
      includestring[]Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items.
      excludestring[]Reject companies whose value is in this list (exact, case-insensitive). 0-500 items.
      headquarters_onlybooleanWhen true, match the company headquarters country only. When false (default), any office country we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). default: false.
      Example
      {
        "filters": {
          "company_country": {
            "include": [
              "US",
              "CA"
            ],
            "headquarters_only": true
          }
        }
      }
    • company_locationobjectoptional

      Company location as unified location strings - a country ("United States"), a state ("Texas, United States"), a city ("San Francisco, California, United States") or a region ("EMEA"). Same format and vocabulary as People Search's company_location and person_location. Any resolved office counts by default; see headquarters_only. Use company_country instead when you already hold ISO-3166-1 alpha-2 codes.

      FieldTypeDescription
      includestring[]Match these locations (any of). Unified strings like "United States", "Texas, United States", "San Francisco, California, United States" - or a region like "EMEA", "APAC", "Europe", "Latin America", which expands to its member countries (full list with member countries: GET /v2/enums/regions). Max 100 items, each 2-200 chars. If none of the values resolve to a known location, the request fails with 400.
      excludestring[]Reject these locations (same unified-string format). Max 100 items, each 2-200 chars. Values that do not resolve are skipped.
      headquarters_onlybooleanWhen true, match the company headquarters location only. When false (default), any office location we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). default: false.
      Example
      {
        "filters": {
          "company_location": {
            "include": [
              "San Francisco, California, United States"
            ],
            "headquarters_only": true
          }
        }
      }
    • company_headcount_rangeenum[]optional

      Bucketed headcount range (see Employee ranges). 1-8 buckets.

      Example
      {
        "filters": {
          "company_headcount_range": [
            "51-200",
            "201-500"
          ]
        }
      }
    • company_headcount_customobjectoptional

      Raw headcount range. min/max are inclusive; either may be omitted.

      FieldTypeDescription
      minnumberLower bound (inclusive). Optional.
      maxnumberUpper bound (inclusive). Must be >= min. Optional.
      Example
      {
        "filters": {
          "company_headcount_custom": {
            "min": 100,
            "max": 5000
          }
        }
      }
    • company_foundedobjectoptional

      Founded year range. min/max are inclusive; either may be omitted.

      FieldTypeDescription
      minnumberLower bound (inclusive). Optional.
      maxnumberUpper bound (inclusive). Must be >= min. Optional.
      Example
      {
        "filters": {
          "company_founded": {
            "min": 2010,
            "max": 2020
          }
        }
      }
    • company_naicsobjectoptional

      NAICS codes (numeric). Matches when any of the company's codes is in the list.

      FieldTypeDescription
      includenumber[]Match companies whose value is in this list - any single value qualifies. Optional - provide include and/or exclude. Max 500 items.
      excludenumber[]Reject companies whose value is in this list. 0-500 items.
      Example
      {
        "filters": {
          "company_naics": {
            "include": [
              541511,
              541512
            ]
          }
        }
      }
    • company_technologiesobjectoptional

      Web technologies detected on the company website, by id: the value of a POST /v2/search/suggest row with type: technology and kind: technology. Websites are rescanned every 30 days.

      FieldTypeDescription
      includestring[]Technology ids to match. match_mode: ANY (default): a company using any of them qualifies; ALL: it must use every one. Max 500.

      Example: ["3421"]

      excludestring[]Reject companies using any of these technology ids. Max 500.
      match_modeenumHow include combines: ANY (default) - at least one; ALL - every one, on the same company.

      Allowed values: ANY ALL

      Example
      {
        "filters": {
          "company_technologies": {
            "include": [
              "3421"
            ],
            "match_mode": "ANY"
          }
        }
      }
    • company_technology_categoriesobjectoptional

      Technology categories (CMS, Ecommerce, Analytics, ...), by id: the value of a suggest row with kind: category. A category matches a company using any technology in it.

      FieldTypeDescription
      includestring[]Category ids to match (any of). Max 200.

      Example: ["1"]

      excludestring[]Reject companies using any technology in these category ids. Max 200.
      Example
      {
        "filters": {
          "company_technology_categories": {
            "include": [
              "1"
            ]
          }
        }
      }
    • company_keywordsobjectoptional

      Free-text keyword match across selected source fields (see Keyword sources). When this filter is active, results are ranked by relevance first.

      FieldTypeDescription
      includestring[]requiredPhrases to search for. 1-20 items, 3-100 chars each. Matched as phrases: a multi-word entry like "email finder" requires those words adjacent and in order within one of the selected source fields, not merely present somewhere in it.
      excludestring[]Phrases that disqualify a company. 0-20 items. Matched as phrases, same as include.
      include_allbooleanWhen true, every phrase in include must match; otherwise any single match qualifies. default: false.
      sourcesenum[]Restrict matching to these source fields (see Keyword sources). Omit to use the default source set - see this company_keywords filter's own description above for what that is.
      Example
      {
        "filters": {
          "company_keywords": {
            "include": [
              "customer support",
              "help desk"
            ],
            "include_all": true,
            "sources": [
              "specialties"
            ]
          }
        }
      }
  • sort_byenumoptional

    Sort key. Omit for the smart default: relevance when filters.company_keywords is present, followers desc otherwise.

    Allowed values: company_name company_employee_count company_industry company_country company_founded company_saved_at

  • sort_directionenumoptional

    Sort direction. Per-key defaults apply; ignored when sort_by is omitted.

    Allowed values: asc desc

  • pageintegeroptionalmin: 1max: 1000default: 1

    Page number, 1-based. The deepest reachable page is 25,000 / per_page: 1,000 at 25, 500 at 50 and 250 at 100 (metadata.pagination.max_page). A result set that runs past it has total_pages clamped to max_page and pagination.truncated=true, while total_count stays the real match count - narrow the filters to reach the rest.

  • per_pageenumoptionaldefault: 25

    Results per page: 25, 50 or 100.

    Allowed values: 25 50 100

Responses

  • 200 A page of companies. metadata.pagination says where it sits: ask for the next page until it reaches total_pages; past 25,000 results truncated is true and total_pages stops at max_page.
  • 400 Invalid request (VALIDATION_ERROR; payload.code says which kind of mistake).
  • 401 Missing, unknown or inactive credentials (UNAUTHORIZED).
  • 429 Over the search rate limit (RATE_LIMIT); wait Retry-After seconds. Sent only where rate limits are enforced.
  • 500 Unexpected server error.

For error handling see Errors. Response objects are described in Person object and Company object.