curl --request GET \
--url https://api.firmable.com/filter-options \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.firmable.com/filter-options"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.firmable.com/filter-options', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.firmable.com/filter-options",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.firmable.com/filter-options"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.firmable.com/filter-options")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.firmable.com/filter-options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"markets": [
{
"code": "AU",
"label": "Australia"
}
],
"filters": [
{
"identifier": "industry",
"label": "Industry",
"group": "company",
"kind": "list",
"endpoints": [
"company_search"
],
"accepts": "<string>",
"counts": "per_market",
"values": [
{
"code": "l1:J",
"label": "Industrial and manufacturing"
}
],
"page": {
"offset": 0,
"size": 20,
"total": 20
}
}
]
}{
"error": {
"code": "invalid_request",
"reason": "Unknown filter identifier: bogus."
}
}{
"error": {
"code": "invalid_request",
"reason": "Unknown filter identifier: bogus."
}
}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.
curl --request GET \
--url https://api.firmable.com/filter-options \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.firmable.com/filter-options"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.firmable.com/filter-options', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.firmable.com/filter-options",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.firmable.com/filter-options"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.firmable.com/filter-options")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.firmable.com/filter-options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"markets": [
{
"code": "AU",
"label": "Australia"
}
],
"filters": [
{
"identifier": "industry",
"label": "Industry",
"group": "company",
"kind": "list",
"endpoints": [
"company_search"
],
"accepts": "<string>",
"counts": "per_market",
"values": [
{
"code": "l1:J",
"label": "Industrial and manufacturing"
}
],
"page": {
"offset": 0,
"size": 20,
"total": 20
}
}
]
}{
"error": {
"code": "invalid_request",
"reason": "Unknown filter identifier: bogus."
}
}{
"error": {
"code": "invalid_request",
"reason": "Unknown filter identifier: bogus."
}
}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 thefilters 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
Passidentifiers to get only the filters you need. Without it, every filter is returned.
curl "https://api.firmable.com/filter-options?identifiers=company_size,seniority" \
-H "Authorization: Bearer YOUR_API_KEY"
?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:
"page": { "offset": 0, "size": 20, "total": 20 }
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.
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:
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:<text> |
services | Services provided | text | C, P | Any text as contains:<text> |
products | Products | text | C, P | Any text as contains:<text> |
position | Job title | text | C, P, PC | Any text as contains:<text> |
seniority | Seniority | list | C, P, PC | Codes |
department | Department | list | C, P, PC | Codes |
skills | Skills | text | C, P, PC | Any text as contains:<text> |
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 |
values; they take any text. Company filters on people search apply to the person’s employer.
Using the codes in a search
{
"filters": {
"industry": ["l1:J"],
"company_size": ["range:51-200"],
"position": ["contains:CTO"]
},
"country": ["AU"]
}
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 |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Comma-separated filter identifiers to return. Returns every filter when omitted. (example: industry,company_size)
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 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)
1 - 100How 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)
x >= 0A top-level industry code, to list its second-level codes, sorted A–Z by label. Only with identifiers=industry. (example: l1:J)
^l1:[A-Za-z]+$