Skip to main content

​
Overview

This page documents the filters JSON shape supported by semantic and lookalike search.

​
Prerequisites

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"
Generate tokens in Dashboard API Tokens. For full setup, see Authentication.

​
Endpoints used

​
Filters shape

Send filters as a JSON string. 
{
  "include": {
    "country": ["United States"]
  },
  "exclude": {
    "size": ["1-10"]
  },
  "range": {
    "founded": {
      "min": 2018,
      "max": 2024
    }
  }
}
All sections are optional. range.founded.max shown here is an example value, not a product limit.

​
Supported fields

Field pathTypeMeaning
include.sizestring[]Keep these company size buckets.
include.countrystring[]Keep these countries.
include.citystring[]Keep these cities.
exclude.sizestring[]Remove these company size buckets.
exclude.countrystring[]Remove these countries.
exclude.citystring[]Remove these cities.
range.founded.minintegerKeep companies founded on/after year.
range.founded.maxintegerKeep companies founded on/before year.

​
Supported size values

Use exact values:
  • 1-10
  • 11-50
  • 51-200
  • 201-500
  • 501-1000
  • 1001-5000
  • 5001-10000
  • 10001+

​
Copy-paste request example

curl --get "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "q=fintech treasury automation" \
  --data-urlencode 'filters={"include":{"country":["United States"],"size":["51-200"]},"range":{"founded":{"min":2018}}}' \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"

​
Troubleshooting

​
422 Unprocessable Entity

The filters JSON is malformed or includes unsupported keys. Validate your filters JSON before sending: echo '<filters-json>' | jq empty.

​
Filter returns no results

Start broad, then narrow one filter dimension at a time. Remove all but one filter group (include, exclude, or range) and re-run to find the limiting condition.