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

# New Company Finder Search

> Find companies that match firmographic, funding and hiring criteria.

<Note>
  Several filters only accept **exact** values from a fixed list: industries, technologies, revenue
  ranges and funding round names. Look them up in [Taxonomies](/api-reference/taxonomies). A value
  that is not in the list silently matches nothing.
</Note>

<Warning>
  Company Finder has **no webhook**. Retrieve the results by polling
  [`GET /company_finder/async/{request_id}`](/api-reference/endpoint/company_finder_get).
</Warning>

## Filters

* List filters only take `include`. Unlike Lead Finder, there is no `exclude`: it is silently ignored.
* Unknown keys are silently ignored too, so check the spelling against the reference below. Lead
  Finder keys such as `job_title` do not exist here.
* At least one filter must hold a real value, otherwise the request is refused with `400`.
* `company` is case-sensitive: send domains in lowercase.

## Pagination

`limit` and `offset` paginate a single search. `offset` is **zero-based**: keep `limit` constant and
step `offset` by `limit` on each call.

| Call | `limit` | `offset` | Companies |
| - | - | - | - |
| 1st | `100` | `0` (or omitted) | 1 to 100 |
| 2nd | `100` | `100` | 101 to 200 |
| 3rd | `100` | `200` | 201 to 300 |

The total number of matching companies is returned as `summary.companies_found`, so you know how many
pages to walk. Each page is a new search and is charged on its own, see [Credits](/api-reference/credits).


## OpenAPI

````yaml POST /company_finder/async
openapi: 3.0.1
info:
  title: BetterContact API
  description: >-
    The official BetterContact API to find new leads and enrich them with
    verified work emails and mobile phone numbers.
  version: 2.0.0
  contact:
    name: BetterContact Support
    email: contact@bettercontact.rocks
    url: https://doc.bettercontact.rocks
servers:
  - url: https://app.bettercontact.rocks/api/v2
security:
  - apiKey: []
paths:
  /company_finder/async:
    post:
      summary: New Company Finder search
      description: >-
        Find companies from firmographic, funding and hiring criteria.


        This endpoint is asynchronous: it answers immediately with a
        `request_id` and searches in the background. Retrieve the results with
        [`GET
        /company_finder/async/{request_id}`](/api-reference/endpoint/company_finder_get).
        Company Finder does not send webhooks.


        Several filters only accept exact values from a fixed list. See
        [Taxonomies](/api-reference/taxonomies).
      operationId: createCompanyFinderSearch
      requestBody:
        description: Filters and pagination for the company search
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyFinderRequest'
            example:
              limit: 25
              offset: 0
              filters:
                company_industry:
                  include:
                    - Software Development
                company_hq_location:
                  include:
                    - United States
                company_headcount_min: 51
                company_headcount_max: 500
                is_b2b: true
      responses:
        '202':
          description: >-
            Company Finder request accepted. Poll `GET
            /company_finder/async/{request_id}`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Company finder request accepted.
                  request_id:
                    type: string
                    example: bc39ffbfc24cf043b748
        '400':
          description: >-
            Bad request. The `filters` object is missing or empty, or every
            filter in it is blank.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error: Filters parameter is invalid. Include values can not be blank
                message: Filters parameter is invalid. Include values can not be blank
        '401':
          description: Unauthorized. The API key is missing, invalid or deactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '402':
          description: Payment required. The account has no credits left.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error: You do not have enough tokens to use Company Finder API.
                message: You do not have enough tokens to use Company Finder API.
        '422':
          description: >-
            Unprocessable. The free search quota is exhausted, or `limit` is
            above 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error: >-
                  You are out of free company finder requests. Please upgrade
                  your plan to continue using this feature.
                message: >-
                  You are out of free company finder requests. Please upgrade
                  your plan to continue using this feature.
        '429':
          description: >-
            [Rate limit](/api-reference/api_rate_limits) exceeded. Back off and
            retry.
        '500':
          description: >-
            Unexpected server error. Safe to retry with backoff, after checking
            that the first attempt did not create a request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                message: Company finder request failed.
      security:
        - apiKey: []
components:
  schemas:
    CompanyFinderRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/CompanyFinderFilters'
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 100
          example: 100
          description: >-
            Number of companies to return for this page, between 1 and 200.
            Defaults to 100. A value above 200 is refused with `422`; `0`, a
            negative number or a non-numeric value falls back to the default.
        offset:
          type: integer
          minimum: 0
          default: 0
          example: 0
          description: >-
            Zero-based number of matches to skip. A negative value is treated as
            `0`.


            To walk through results, keep `limit` constant and increase `offset`
            by `limit` on each call. The total number of matching companies is
            returned as `summary.companies_found`.
    ApiError:
      type: object
      description: >-
        Generic error envelope. Depending on the endpoint the human readable
        text is carried by `error` or by `message`, so always read both.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Human readable error message.
        message:
          type: string
          description: Human readable error message.
    UnauthorizedError:
      type: object
      properties:
        success:
          type: boolean
          example: false
          description: Not returned by the enrichment endpoints.
        error:
          type: string
          example: Your are not authorized. Please check your api_key.
    CompanyFinderFilters:
      type: object
      description: >-
        Company criteria. At least one filter must hold a real value. Unknown
        keys are ignored, and so is `exclude`: a request made only of those is
        refused with `400`.
      properties:
        company:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Company domains, in lowercase: the match is case-sensitive, so
            `HUBSPOT.COM` finds nothing. A leading `http://`, `https://` or
            `www.` is stripped, but a path is not: pass `acme.com`, not
            `https://acme.com/about`.
          example:
            include:
              - acme.com
        company_linkedin_url:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: Company LinkedIn page URLs.
          example:
            include:
              - https://www.linkedin.com/company/acme
        company_industry:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Industries. Must be exact values from [Taxonomies -
            Industries](/api-reference/taxonomies#industries).
          example:
            include:
              - Software Development
        company_hq_location:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Matched against the full headquarters address, so a city, a state or
            a country all work.
          example:
            include:
              - Austin
              - Germany
        company_technologies:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Technologies the company uses. Must be exact values from [Taxonomies
            - Technologies](/api-reference/taxonomies#technologies).
          example:
            include:
              - Salesforce
        company_keywords:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Keywords or phrases matched against the company profile. Matched the
            same way as `company_description`.
          example:
            include:
              - fintech
        company_description:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Phrases matched against the company profile. Matched the same way as
            `company_keywords`.
          example:
            include:
              - payment infrastructure
        company_headcount_min:
          type: integer
          minimum: 0
          description: >-
            Minimum number of employees, inclusive. Mapped onto the size buckets
            of [Taxonomies - Company size
            ranges](/api-reference/taxonomies#company-size-ranges): every bucket
            that overlaps your range is kept, so `60` still returns companies
            from the `51-200` bucket.
          example: 51
        company_headcount_max:
          type: integer
          minimum: 0
          description: >-
            Maximum number of employees, inclusive. Mapped onto size buckets the
            same way as `company_headcount_min`.
          example: 500
        is_b2b:
          type: boolean
          description: >-
            `true` keeps companies that sell to businesses. Omit the field when
            you do not want to filter on it.
        is_b2c:
          type: boolean
          description: >-
            `true` keeps companies that sell to consumers. Omit the field when
            you do not want to filter on it.
        is_public:
          type: boolean
          description: >-
            `true` keeps publicly listed companies. Omit the field when you do
            not want to filter on it.
        revenue_ranges:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Revenue brackets. Must be exact values from [Taxonomies - Revenue
            ranges](/api-reference/taxonomies#revenue-ranges).
          example:
            include:
              - $20M-$100M
        last_funding_round_names:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: >-
            Name of the latest funding round. Must be exact values from
            [Taxonomies - Funding round
            names](/api-reference/taxonomies#funding-round-names).
          example:
            include:
              - Series B
        last_funding_date_range:
          allOf:
            - $ref: '#/components/schemas/RangeFilter'
          description: Date of the last funding round, as `YYYY-MM-DD` strings.
          example:
            gte: '2024-01-01'
            lte: '2025-12-31'
        last_amount_raised_usd:
          allOf:
            - $ref: '#/components/schemas/RangeFilter'
          description: Amount raised in the last round, in USD, as integers.
          example:
            gte: 1000000
        total_amount_raised_usd:
          allOf:
            - $ref: '#/components/schemas/RangeFilter'
          description: Total amount raised, in USD, as integers.
          example:
            gte: 5000000
            lte: 50000000
        job_post_titles:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: Job titles the company is currently hiring for.
          example:
            include:
              - Account Executive
        job_posting_countries:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: Countries the company is currently hiring in.
          example:
            include:
              - United States
        job_posting_locations:
          allOf:
            - $ref: '#/components/schemas/CompanyFinderIncludeFilter'
          description: Cities or regions the company is currently hiring in.
          example:
            include:
              - Berlin
    CompanyFinderIncludeFilter:
      type: object
      properties:
        include:
          type: array
          items:
            type: string
          description: Values that must match.
      description: Company Finder list filters only take `include`. There is no `exclude`.
    RangeFilter:
      type: object
      description: Inclusive range. Provide `gte`, `lte` or both.
      properties:
        gte:
          description: Greater than or equal to.
        lte:
          description: Lower than or equal to.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

````