Skip to main content
GET
/
v1
/
companies
/
search
Search Companies
curl --request GET \
  --url https://api.extruct.ai/v1/companies/search \
  --header 'Authorization: Bearer <token>'
{
  "results": [
    {
      "id": "<string>",
      "domain": "<string>",
      "name": "<string>",
      "short_description": "<string>",
      "full_description": "<string>",
      "products_services": "<string>",
      "use_cases": "<string>",
      "target_audience": "<string>",
      "other_considerations": "<string>",
      "founding_year": 123,
      "employee_count": "<string>",
      "hq_country": "<string>",
      "hq_state_province": "<string>",
      "hq_city": "<string>",
      "hq_full_address": "<string>",
      "social_profiles": {},
      "website_authority": {
        "score": 123,
        "tier": "<string>",
        "tier_label": "<string>"
      },
      "relevance_score": 123
    }
  ],
  "request": {
    "offset": 123,
    "limit": 123,
    "query": "<string>",
    "filters": {
      "include": {
        "size": [],
        "country": [
          "<string>"
        ],
        "city": [
          "<string>"
        ]
      },
      "exclude": {
        "size": [],
        "country": [
          "<string>"
        ],
        "city": [
          "<string>"
        ],
        "domains": [
          "<string>"
        ]
      },
      "range": {
        "founded": {
          "min": 123,
          "max": 123
        }
      }
    }
  }
}
Prefer POST /v1/companies/search. This GET endpoint is deprecated. It still works and returns identical results, but POST is the recommended default: it takes filters as a JSON object and is not limited by URL length (required for large exclude.domains lists).

​
Overview

Semantic Search returns companies that match a natural-language query, with optional firmographic filters. It is the recall-first search endpoint over the Extruct index and the usual starting point before lookalike or Deep Search.

​
Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

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"

​
Key parameters

  • q (required): Natural-language query.
  • filters (optional): JSON string used to narrow results.
  • offset (optional): Pagination offset.
  • limit (optional): Page size, up to 250 per request.
For supported filters, see Search Filters Reference.

​
Endpoint behavior

  • Results are ranked by semantic match in the Extruct index.
  • filters narrow the candidate set; they do not replace the query.
  • A single request returns at most 250 results. Page with offset to read deeper: paid plans (Starter, Pro) can reach up to 2,000 results per query; the free tier is capped at 25.
  • Good matches from search often become inputs for Company Lookup, seed companies for Lookalike Search, or a shortlist for Deep Search.

​
Success signal

A successful response returns results and request metadata. Reuse results[].id or results[].domain as downstream identifiers, including company lookup and lookalike input.

​
Common errors

​
401 Unauthorized

Check that your header is Authorization: Bearer ${EXTRUCT_API_TOKEN}.

​
422 Unprocessable Entity

Most often caused by malformed filters JSON. Validate before sending: 
echo '<filters-json>' | jq empty

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
q
string
required

Search query

​
filters
string | null

JSON string of SearchFilters. Supported keys only: include.size/country/city, exclude.size/country/city/domains, range.founded.min/max.

​
offset
integer | null
​
limit
integer | null

Response

Successful Response

Semantic search response wrapper.

​
results
CompanySearchResult · object[]
required

Search results

​
request
SearchRequestInfo · object
required

Request parameters echo