Skip to main content

​
Overview

Semantic Search is the recall-first company search path over the Extruct index. Start with a natural-language query, then narrow with firmographic filters such as country, city, size, and founded year.

​
This Path Works Best When

  • You want broad market coverage before narrowing.
  • You want to explore a category, use case, ICP, or problem space quickly.
  • You expect filters to do most of the refinement work.

​
Choose Another Path If

  • You already have a strong seed company and want similarity ranking instead. Use Lookalike Search.
  • You need custom ranking criteria and evidence-backed evaluation. Use Deep Search.

​
Prerequisites

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

​
Endpoints used

​
Workflow

​
1) Run a broad semantic query

curl --get "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "q=vertical SaaS for logistics procurement" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"

​
2) Narrow with filters

curl --get "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "q=b2b treasury automation" \
  --data-urlencode 'filters={"include":{"country":["United States"],"size":["51-200","201-500"]},"range":{"founded":{"min":2018}}}' \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"
For supported filter fields and values, use Search Filters Reference.

​
3) Page through results

Use fixed increments for stable pagination:
  • Page 1: offset=0&limit=20
  • Page 2: offset=20&limit=20
  • Page 3: offset=40&limit=20

​
4) Expand top seeds with lookalike

After selecting a high-quality company from search results, prefer results[].domain as company_identifier for lookalike. Use results[].id only if domain is missing. 
COMPANY_IDENTIFIER="stripe.com"

curl --get "https://api.extruct.ai/v1/companies/${COMPANY_IDENTIFIER}/similar" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"

​
5) Escalate to Deep Search when filters are not enough

Move to Deep Search when you can describe the companies you want in natural language, but firmographic filters still do not produce the ranking quality you need. Typical signs:
  • Results are relevant but poorly ordered.
  • The distinction you care about is qualitative, not just firmographic.
  • You need explicit scoring and explanations for each candidate.

​
Troubleshooting

​
401 Unauthorized

The token is missing or invalid. Check that EXTRUCT_API_TOKEN is set and the header is exactly Authorization: Bearer ${EXTRUCT_API_TOKEN}.

​
422 Unprocessable Entity

The filters JSON is malformed or includes unsupported keys. Use only keys listed in Search Filters Reference. Validate your filters JSON before sending: echo '<filters-json>' | jq empty.