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

# Company search

> Find companies matching structured filters

Company search accepts every company and people filter. With people filters, it returns companies
where one person matches all of them together. See [Filters](https://docs.firmable.com/partner/filters.md) for the filters and
the forms their codes take.

Each record carries one object per market searched, keyed by the lowercase market code. With people
filters, a page can return one record fewer than `page.size`. `total` stays correct.

Codes such as `"revenue": "4"` are explained in [Codes in responses](https://docs.firmable.com/partner/codes.md).


## OpenAPI

````yaml POST /partner/{partner}/companies/search
openapi: 3.0.1
info:
  title: Firmable API
  description: >-
    The Firmable API provides access to company and people data across multiple
    countries including Australia, New Zealand, Singapore, Malaysia, Indonesia,
    Philippines, Hong Kong, Japan, Vietnam, South Korea, Thailand, United
    States, and Canada. Use it to look up company profiles, retrieve contact
    information, and search for people by company, position, seniority, and
    department.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.firmable.com
security:
  - bearerAuth: []
paths:
  /partner/{partner}/companies/search:
    post:
      description: >-
        Returns companies matching structured filters. Accepts every company and
        people filter. With people filters, it returns companies where one
        person matches all of them together.
      parameters:
        - name: partner
          in: path
          required: true
          description: >-
            Your platform's identifier. Firmable gives it to you during
            onboarding.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerSearchRequest'
            example:
              filters:
                industry:
                  - l1:R
                location:
                  - state:VIC, AU:AU
                company_size:
                  - range:100-
              country:
                - AU
              page:
                from: 0
                size: 25
      responses:
        '200':
          description: Matching companies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCompanySearch'
              example:
                records:
                  - company_id: f000000000101
                    name: Harbourline Logistics
                    website: https://www.harbourline.example
                    industry:
                      - l2: Logistics and supply chain services
                    hq_country: AU
                    revenue: '4'
                    global_company_size: '4'
                    multiple_locations: '2'
                    au:
                      employee_count: 312
                      company_size: 4
                      hq_location:
                        - country: AU
                          state: VIC, AU
                      has_company_phone: true
                      has_company_mobile: false
                total: 86
                page:
                  from: 0
                  size: 25
        '401':
          description: Missing or invalid API key
components:
  schemas:
    PartnerSearchRequest:
      type: object
      properties:
        filters:
          type: object
          description: >-
            An object of filter identifier to an array of 1 to 100 codes. Codes
            within one filter are combined with OR. Different filters are
            combined with AND. Get codes from GET /filter-options. Accepts every
            company and people filter.
          properties:
            industry:
              type: array
              description: 'Industry codes, two levels. Example codes: l1:K, 80'
              minItems: 1
              maxItems: 100
              items:
                type: string
            location:
              type: array
              description: 'Location (Company). State codes. Example codes: state:VIC, AU:AU'
              minItems: 1
              maxItems: 100
              items:
                type: string
            hq_location:
              type: array
              description: >-
                Headquarters (Location). Country or state codes. Example codes:
                country:US:US, state:NSW, AU:AU
              minItems: 1
              maxItems: 100
              items:
                type: string
            company_size:
              type: array
              description: >-
                Employee count (Country). Band codes, or one range, per market.
                Example codes: 3, range:100-
              minItems: 1
              maxItems: 100
              items:
                type: string
            global_company_size:
              type: array
              description: >-
                Employee count (Global). Band codes, or one range, worldwide.
                Example codes: 8, range:10000-
              minItems: 1
              maxItems: 100
              items:
                type: string
            revenue:
              type: array
              description: 'Revenue. List codes. Example codes: 2, 9'
              minItems: 1
              maxItems: 100
              items:
                type: string
            company_type:
              type: array
              description: 'Type. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            year_founded:
              type: array
              description: >-
                Year founded. Band codes, or one range. Example codes: 1,
                range:2015-2020
              minItems: 1
              maxItems: 100
              items:
                type: string
            is_mnc:
              type: array
              description: 'Multinational. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            b2b_vs_b2c:
              type: array
              description: 'Target customer type. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            target_market:
              type: array
              description: 'Target market focus. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            multiple_locations:
              type: array
              description: 'Multiple locations. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            job_posts:
              type: array
              description: 'Job posts. List codes. Example codes: 4, 7'
              minItems: 1
              maxItems: 100
              items:
                type: string
            keywords:
              type: array
              description: 'Keywords. Free text. Example codes: contains:payroll'
              minItems: 1
              maxItems: 100
              items:
                type: string
            services:
              type: array
              description: 'Services provided. Free text. Example codes: contains:plumbing'
              minItems: 1
              maxItems: 100
              items:
                type: string
            products:
              type: array
              description: 'Products. Free text. Example codes: contains:solar panels'
              minItems: 1
              maxItems: 100
              items:
                type: string
            position:
              type: array
              description: >-
                Job title. Free text. Example codes: contains:chief financial
                officer
              minItems: 1
              maxItems: 100
              items:
                type: string
            seniority:
              type: array
              description: 'Seniority. List codes. Example codes: 3, 4'
              minItems: 1
              maxItems: 100
              items:
                type: string
            department:
              type: array
              description: 'Department. List codes. Example codes: 2, 14'
              minItems: 1
              maxItems: 100
              items:
                type: string
            skills:
              type: array
              description: 'Skills. Free text. Example codes: contains:python'
              minItems: 1
              maxItems: 100
              items:
                type: string
            current_role_duration:
              type: array
              description: 'Job change. List codes. Example codes: 4, 13'
              minItems: 1
              maxItems: 100
              items:
                type: string
            people_location:
              type: array
              description: 'Location (People). State codes. Example codes: state:QLD, AU:AU'
              minItems: 1
              maxItems: 100
              items:
                type: string
        country:
          type: array
          description: The markets to search, as market codes. Every market when omitted.
          items:
            type: string
            enum:
              - AU
              - NZ
              - SG
              - MY
              - ID
              - PH
              - TH
              - VN
              - HK
              - JP
              - KR
              - US
              - CA
        page:
          type: object
          properties:
            from:
              type: integer
              minimum: 0
              maximum: 10000
              default: 0
              description: Offset, 0 to 10,000.
            size:
              type: integer
              minimum: 1
              maximum: 100
              default: 25
              description: Records per page, 1 to 100.
    PartnerCompanySearch:
      type: object
      properties:
        records:
          type: array
          items:
            type: object
            description: >-
              One company. Carries one object per market searched, keyed by the
              lowercase market code (for example au).
            properties:
              company_id:
                type: string
                description: Firmable company id
              name:
                type: string
                description: Company name
              website:
                type: string
                description: Website
              industry:
                type: array
                items:
                  type: object
                  properties:
                    l2:
                      type: string
                      description: Second-level industry label
              hq_country:
                type: string
                description: Headquarters market code
              revenue:
                type: string
                description: Code from the revenue filter
              global_company_size:
                type: string
                description: Code from the global_company_size filter
              multiple_locations:
                type: string
                description: Code from the multiple_locations filter
            additionalProperties:
              type: object
              description: Per-market data
              properties:
                employee_count:
                  type: integer
                  description: Employee count in the market
                company_size:
                  type: integer
                  description: Code from the company_size filter
                hq_location:
                  type: array
                  items:
                    type: object
                    properties:
                      country:
                        type: string
                        description: Market code
                      state:
                        type: string
                        description: State
                has_company_phone:
                  type: boolean
                  description: Firmable holds a company phone number in the market
                has_company_mobile:
                  type: boolean
                  description: Firmable holds a company mobile number in the market
        total:
          type: integer
          description: Total matching companies
        page:
          type: object
          properties:
            from:
              type: integer
              minimum: 0
              maximum: 10000
              default: 0
              description: Offset, 0 to 10,000.
            size:
              type: integer
              minimum: 1
              maximum: 100
              default: 25
              description: Records per page, 1 to 100.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.