> ## 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.

# Filter options

> List every search filter and the codes it accepts

Returns every filter the search endpoints accept, with its codes. Search accepts only codes that
filter options lists. Lists refresh hourly. Filter options accepts any Firmable API key and is never
charged.

`industry`, `location`, `hq_location` and `people_location` return 20 values at a time with a `page`
object. Every other filter returns all of its values. `search`, `offset` and `levelOne` require
exactly one of these four filters in `identifiers`. `industry` returns its top-level codes unless
`levelOne` is sent.

## Searching a long list

```bash Request theme={null}
curl "https://api.firmable.com/filter-options?identifiers=location&search=new%20south" \
  -H "Authorization: Bearer $FIRMABLE_KEY"
```

```json Response · 200 theme={null}
{
  "markets": [ … 13 markets ],
  "filters": [
    {
      "identifier": "location",
      "kind": "location",
      "values": [ { "code": "state:NSW, AU:AU", "label": "New South Wales, AU" } ],
      "page": { "offset": 0, "size": 20, "total": 1 }
    }
  ]
}
```


## OpenAPI

````yaml GET /filter-options
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:
  /filter-options:
    get:
      description: >-
        Lists the filters the Partner API search endpoints accept, with the
        codes each one takes, and the markets a search can be scoped to. Not
        charged.
      parameters:
        - name: identifiers
          in: query
          description: >-
            Comma-separated filter identifiers to return. Returns every filter
            when omitted. (example: industry,company_size)
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - industry
                - location
                - hq_location
                - company_size
                - global_company_size
                - revenue
                - company_type
                - year_founded
                - is_mnc
                - b2b_vs_b2c
                - target_market
                - multiple_locations
                - job_posts
                - keywords
                - services
                - products
                - position
                - seniority
                - department
                - skills
                - current_role_duration
                - people_location
        - name: search
          in: query
          description: >-
            Text to match against a value's label or code, case-insensitive.
            Only with exactly one of industry, location, hq_location or
            people_location in identifiers. (example: new south)
          schema:
            type: string
            minLength: 1
            maxLength: 100
        - name: offset
          in: query
          description: >-
            How many matching values to skip. Pages are always 20 values. Only
            with exactly one of industry, location, hq_location or
            people_location in identifiers. (example: 20)
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: levelOne
          in: query
          description: >-
            A top-level industry code, to list its second-level codes, sorted
            A–Z by label. Only with identifiers=industry. (example: l1:J)
          schema:
            type: string
            pattern: ^l1:[A-Za-z]+$
      responses:
        '200':
          description: Filter options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterOptions'
        '400':
          description: >-
            Bad request: an unknown identifier, a size parameter, or search,
            offset or levelOne used without exactly one pageable filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerError'
        '401':
          description: Missing or invalid API key
        '403':
          description: The key has no organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerError'
components:
  schemas:
    FilterOptions:
      type: object
      required:
        - markets
        - filters
      properties:
        markets:
          type: array
          description: >-
            Markets a search can be scoped to, for the search body's country
            array.
          items:
            type: object
            properties:
              code:
                type: string
                example: AU
              label:
                type: string
                example: Australia
        filters:
          type: array
          items:
            $ref: '#/components/schemas/FilterOption'
    PartnerError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request
            reason:
              type: string
              example: 'Unknown filter identifier: bogus.'
    FilterOption:
      type: object
      required:
        - identifier
        - label
        - group
        - kind
        - endpoints
        - accepts
      properties:
        identifier:
          type: string
          description: The key to use in a search body's filters object.
          example: industry
        label:
          type: string
          example: Industry
        group:
          type: string
          enum:
            - company
            - people
          description: >-
            company applies to the company (or a person's employer); people
            applies to the person.
        kind:
          type: string
          enum:
            - list
            - list_or_range
            - industry
            - location
            - hq_location
            - text
        counts:
          type: string
          enum:
            - per_market
            - worldwide
          description: Only on some size and revenue filters.
        endpoints:
          type: array
          items:
            type: string
            enum:
              - company_search
              - people_search
              - people_in_company_search
        accepts:
          type: string
          description: What values the filter takes.
        values:
          type: array
          description: Allowed codes. Absent for text filters.
          items:
            type: object
            properties:
              code:
                type: string
                example: l1:J
              label:
                type: string
                example: Industrial and manufacturing
        page:
          type: object
          description: >-
            Only on industry, location, hq_location and people_location, which
            come 20 values at a time.
          properties:
            offset:
              type: integer
              example: 0
            size:
              type: integer
              example: 20
            total:
              type: integer
              description: How many values match.
              example: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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