Search Filters Reference

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 path	Type	Meaning
`include.size`	`string[]`	Keep these company size buckets.
`include.country`	`string[]`	Keep these countries.
`include.city`	`string[]`	Keep these cities.
`exclude.size`	`string[]`	Remove these company size buckets.
`exclude.country`	`string[]`	Remove these countries.
`exclude.city`	`string[]`	Remove these cities.
`exclude.domains`	`string[]`	Remove companies by domain or URL (normalized server-side, alias-aware, max 1000).
`range.founded.min`	`integer`	Keep companies founded on/after year.
`range.founded.max`	`integer`	Keep 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.

API Guides

Build with AI Agents

Integrations

Search Filters Reference

Overview

Prerequisites

Endpoints used

Filters shape

Supported fields

Supported size values

Copy-paste request example

Troubleshooting

`422 Unprocessable Entity`

Filter returns no results

​Overview

​Prerequisites

​Endpoints used

​Filters shape

​Supported fields

​Supported size values

​Copy-paste request example

​Troubleshooting

​422 Unprocessable Entity

​Filter returns no results

Overview

Prerequisites

Endpoints used

Filters shape

Supported fields

Supported size values

Copy-paste request example

Troubleshooting

`422 Unprocessable Entity`

Filter returns no results