Search the company catalog

This page documents the canonical HTTP contract for this endpoint.

Choose one or more deterministic filters. At least one filter is required; empty filters and reversed min/max ranges are rejected. Filter values should come from the company catalog vocabulary. The result is scoped to the catalog snapshot, not a complete real-world company census.

The common response envelope contains items, total_found, billable_results, credits_used, pricing_rule, and metadata. Result item fields depend on this search family.

Body parameters

industry_groups · optional
array<string>
Industry-group catalog values; up to 20.
primary_industries · optional
array<string>
Primary-industry catalog values; up to 50.
specialization_ids · optional
array<string>
Specialization IDs; up to 50.
country_codes · optional
array<string>
Country codes; up to 50. Normalized to uppercase.
region_codes · optional
array<string>
Region codes; up to 50. Normalized to uppercase.
cities · optional
array<string>
City names; up to 50.
company_sizes · optional
array<string>
Company-size values; up to 20.
employee_count_min · optional
integer
Minimum employee count; 0 or greater.
employee_count_max · optional
integer
Maximum employee count; 0 or greater.
founded_year_min · optional
integer
Minimum founded year; 1600–2100.
founded_year_max · optional
integer
Maximum founded year; 1600–2100.
require_domain · optional
boolean
Always true; domain-bearing companies are required.
limit · optional
integer
Maximum results; default 10, range 1–25.

Name	Type	Description
industry_groups	array<string>	Industry-group catalog values; up to 20.
primary_industries	array<string>	Primary-industry catalog values; up to 50.
specialization_ids	array<string>	Specialization IDs; up to 50.
country_codes	array<string>	Country codes; up to 50. Normalized to uppercase.
region_codes	array<string>	Region codes; up to 50. Normalized to uppercase.
cities	array<string>	City names; up to 50.
company_sizes	array<string>	Company-size values; up to 20.
employee_count_min	integer	Minimum employee count; 0 or greater.
employee_count_max	integer	Maximum employee count; 0 or greater.
founded_year_min	integer	Minimum founded year; 1600–2100.
founded_year_max	integer	Maximum founded year; 1600–2100.
require_domain	boolean	Always true; domain-bearing companies are required.
limit	integer	Maximum results; default 10, range 1–25.

Errors

Status	Meaning
400	The search command or provider rejected the request.
401	Authentication is required.
402	Insufficient credits for this search.
403	Developer API key lacks required scope: search:run.
422	A request field is missing, outside its allowed range, or fails the typed request contract.

Example

bash

curl -X POST "https://app.autotouch.ai/api/search/catalog-companies" -H "Authorization: Bearer $AUTOTOUCH_API_KEY" -H "Content-Type: application/json" -d '{"country_codes":["US"],"primary_industries":["software"],"employee_count_min":50,"limit":10}'

Request body

json

{
  "country_codes": [
    "US"
  ],
  "primary_industries": [
    "software"
  ],
  "employee_count_min": 50,
  "limit": 10
}

Response example

json

{
  "items": [],
  "total_found": 0,
  "billable_results": 0,
  "credits_used": 0,
  "pricing_rule": "<effective rule for this search>",
  "metadata": {}
}