Search Companies

GET

companies

Search Companies

curl --request GET \
  --url https://api.extruct.ai/v1/companies/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.extruct.ai/v1/companies/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.extruct.ai/v1/companies/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.extruct.ai/v1/companies/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.extruct.ai/v1/companies/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
        }
      }
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

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

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

Show child attributes

request

SearchRequestInfo · object

required

Request parameters echo

Show child attributes

Search Companies

curl --request GET \
  --url https://api.extruct.ai/v1/companies/search \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.extruct.ai/v1/companies/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.extruct.ai/v1/companies/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.extruct.ai/v1/companies/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.extruct.ai/v1/companies/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
        }
      }
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

Company Search

Deep Search

Deep Research

Table Management

Table Execution

Other

Overview

Example request

Key parameters

Endpoint behavior

Success signal

Common errors

`401 Unauthorized`

`422 Unprocessable Entity`

Authorizations

Query Parameters

Response

​Overview

​Example request

​Key parameters

​Endpoint behavior

​Success signal

​Common errors

​401 Unauthorized

​422 Unprocessable Entity

​Related endpoints

​Related guides

Authorizations

Query Parameters

Response

Overview

Example request

Key parameters

Endpoint behavior

Success signal

Common errors

`401 Unauthorized`

`422 Unprocessable Entity`

Related endpoints

Related guides