Skip to main content
POST
/
v1
/
companies
/
search
Search Companies
curl --request POST \
  --url https://api.extruct.ai/v1/companies/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "q": "<string>",
  "filters": {
    "include": {
      "size": [],
      "country": [
        "<string>"
      ],
      "city": [
        "<string>"
      ]
    },
    "exclude": {
      "size": [],
      "country": [
        "<string>"
      ],
      "city": [
        "<string>"
      ],
      "domains": [
        "<string>"
      ]
    },
    "range": {
      "founded": {
        "min": 123,
        "max": 123
      }
    }
  },
  "pagination": {
    "offset": 123,
    "limit": 123
  }
}
'
{
  "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
        }
      }
    }
  }
}

​
Overview

The POST variant of Semantic Search takes the same parameters in a JSON body, with filters as a native object instead of a URL-encoded string. Use it when an exclude.domains list is too large to fit a GET URL.

​
Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl -X POST "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "b2b treasury automation",
    "filters": {
      "include": {"country": ["United States"], "size": ["51-200"]},
      "exclude": {"domains": ["stripe.com", "adyen.com"]}
    },
    "pagination": {"offset": 0, "limit": 20}
  }'

​
Key parameters

  • q (required): Natural-language query.
  • filters (optional): SearchFilters as a JSON object. See Search Filters Reference.
  • pagination (optional): { "offset": <int>, "limit": <int> }; limit up to 250 per request.

​
Endpoint behavior

  • Identical ranking and results to GET /v1/companies/search; only the transport differs.
  • Prefer POST when exclude.domains is large; otherwise either method works.
  • A single request returns at most 250 results. Page with pagination.offset to read deeper: paid plans (Starter, Pro) can reach up to 2,000 results per query; the free tier is capped at 25.

​
Success signal

Returns results and request metadata, the same shape as the GET endpoint. Reuse results[].id or results[].domain as downstream identifiers.

​
Common errors

​
401 Unauthorized

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

​
422 Unprocessable Entity

An invalid domain in exclude.domains, more than 1000 domains after de-duplication, or a malformed body. Validate before sending: 
echo '<body-json>' | jq empty

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Request body for POST company search. Send filters as a JSON object.

​
q
string
required

Search query.

​
filters
SearchFilters · object

Structured filters (same contract as the GET filters string).

​
pagination
Pagination · object

Offset/limit pagination.

Response

Successful Response

Semantic search response wrapper.

​
results
CompanySearchResult · object[]
required

Search results

​
request
SearchRequestInfo · object
required

Request parameters echo