> ## 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 > 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. ## Description Lists the filters the Partner API search endpoints accept, with the codes each filter takes, and the markets a search can be scoped to. Use it to build the `filters` and `country` parts of a search request. The list is the same for every caller and changes rarely, so fetch it once and cache it. The call is not charged. ## Choosing filters Pass `identifiers` to get only the filters you need. Without it, every filter is returned. ```bash theme={null} curl "https://api.firmable.com/filter-options?identifiers=company_size,seniority" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Separate identifiers with commas, or repeat the parameter: `?identifiers=industry&identifiers=location`. An unknown identifier returns a `400` that lists the valid ones. ## Searching and paging Four filters have long code lists: `industry`, `location`, `hq_location` and `people_location`. Their values come 20 at a time, with a `page` object: ```json theme={null} "page": { "offset": 0, "size": 20, "total": 20 } ``` To find a value or see the next page, ask for one of these filters on its own and add: * `search`: text to match against a value's label or code, case-insensitive. * `offset`: how many matching values to skip. The page size is always 20 and can't be changed. ```bash theme={null} curl "https://api.firmable.com/filter-options?identifiers=location&search=new%20south" \ -H "Authorization: Bearer YOUR_API_KEY" ``` `search` and `offset` work with exactly one of those four filters in `identifiers`. With any other filter, or with more than one, the call returns `400`. ## Industry levels Industry has two levels. By default, `industry` returns its top-level codes, such as `l1:J`. A top-level code matches every industry beneath it. To list the second-level codes under one top-level code, sorted A–Z by label, pass it as `levelOne`: ```bash theme={null} curl "https://api.firmable.com/filter-options?identifiers=industry&levelOne=l1:J" \ -H "Authorization: Bearer YOUR_API_KEY" ``` `search` and `offset` also work with `levelOne`. ## Filter identifiers **Search endpoints:** C = company search, P = people search, PC = people in a company. | Identifier | Label | Kind | Endpoints | Values | | - | - | - | - | - | | `industry` | Industry | industry | C, P | Top-level codes (`l1:J`); second-level codes (`2`) through `levelOne`. Paged | | `location` | Location (Company) | location | C, P | State codes such as `state:NSW, AU:AU`. Paged | | `hq_location` | Headquarters (Location) | hq\_location | C, P | Country or state codes such as `country:AU:AU`. Paged | | `company_size` | Employee count (Country) | list or range | C, P | Band codes, or a range such as `range:50-250` | | `global_company_size` | Employee count (Global) | list or range | C, P | Band codes, or a range such as `range:1000-` | | `revenue` | Revenue | list | C, P | Band codes | | `company_type` | Type | list | C, P | Codes | | `year_founded` | Year founded | list or range | C, P | Band codes, or a range such as `range:2010-2020` | | `is_mnc` | Multinational | list | C, P | Codes | | `b2b_vs_b2c` | Target customer type | list | C, P | Codes | | `target_market` | Target market focus | list | C, P | Codes | | `multiple_locations` | Multiple locations | list | C, P | Codes | | `job_posts` | Job posts | list | C, P | Codes | | `keywords` | Keywords | text | C, P | Any text as `contains:` | | `services` | Services provided | text | C, P | Any text as `contains:` | | `products` | Products | text | C, P | Any text as `contains:` | | `position` | Job title | text | C, P, PC | Any text as `contains:` | | `seniority` | Seniority | list | C, P, PC | Codes | | `department` | Department | list | C, P, PC | Codes | | `skills` | Skills | text | C, P, PC | Any text as `contains:` | | `current_role_duration` | Job change | list | C, P, PC | Codes | | `people_location` | Location (People) | location | C, P, PC | State codes such as `state:VIC, AU:AU`. Paged | Text filters return no `values`; they take any text. Company filters on people search apply to the person's employer. ## Using the codes in a search ```json theme={null} { "filters": { "industry": ["l1:J"], "company_size": ["range:51-200"], "position": ["contains:CTO"] }, "country": ["AU"] } ``` A search with a code that isn't in filter options returns `422 invalid_filter_value`, naming the filter and the value. ## Errors | Status | Code | When | | - | - | - | | `400` | `invalid_request` | An unknown identifier, a `size` parameter, `search`, `offset` or `levelOne` without exactly one paged filter, `levelOne` on a filter other than industry, or an unknown `levelOne` code | | `401` | | A missing or invalid API key | | `403` | `org_required` | The key has no organisation | | `500` | `error` | Something went wrong. Try again | ## 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.