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

On the GET endpoints, send filters as a JSON string (URL-encoded). On the POST endpoints, send filters as a native JSON object in the request body. 
{
  "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.
exclude.domainsstring[]Remove companies by domain or URL (normalized server-side, alias-aware, max 1000).
range.founded.minintegerKeep companies founded on/after year.
range.founded.maxintegerKeep companies founded on/before year.
exclude.domains accepts company domains or full URLs; each is normalized to its registered domain, so https://www.stripe.com/pricing, stripe.com, and blog.stripe.com all exclude stripe.com. A large exclusion list does not fit a GET URL — use the POST endpoints for lists beyond a few hundred domains.

​
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"
For a large exclude.domains list, POST filters as a JSON object instead: 
curl -X POST "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"q":"fintech treasury automation","filters":{"exclude":{"domains":["stripe.com","adyen.com"]}},"pagination":{"offset":0,"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.