Search Companies

POST/api/v1/companies/search

Search the company index with filters and a free-text query. Returns matching companies, a total count, facet aggregations, and a cursor for pagination.

Authentication#

Requires a token with the read scope, sent as Authorization: Bearer cornect_….

Request#

Body parameters (all optional):

Name	Type	Required	Description
`query`	string	No	Free-text search across company name + description.
`countries`	string[]	No	Full country names to include — e.g. `"Germany"`, `"United States"`, `"United Kingdom"`. Not ISO codes: `"DE"` / `"US"` match nothing. Exact match (use `"United States"`, not `"usa"`).
`states`	string[]	No	States/regions to include (full names, same convention as countries).
`cities`	string[]	No	Cities to include. Not country-scoped on their own — also set `countries` to avoid matching same-named cities elsewhere (e.g. Berlin, Germany vs Berlin, Connecticut).
`industries`	string[]	No	Industry labels to include.
`exclude_industries`	string[]	No	Industry labels to EXCLUDE (must_not). Companies in any of these industries are removed. Coexists with industries.
`naics_codes`	string[]	No	NAICS industry codes.
`technologies`	string[]	No	Detected technologies the company uses.
`technology_categories`	string[]	No	Technology categories.
`employee_count_min`	integer	No	Minimum employee count.
`employee_count_max`	integer	No	Maximum employee count.
`founded_year_min`	integer	No	Earliest founding year.
`founded_year_max`	integer	No	Latest founding year.
`keywords`	string[]	No	Keyword filters (phrase-match on name + description, OR across chips).
`exclude_keywords`	string[]	No	Keywords to EXCLUDE (must_not, same name+description match). A company matching ANY excluded keyword is removed.
`connections`	object[]	No	“Has connection” filters. Each entry is `{category?, connected_company_id?, connected_domain?}` and matches companies that have a connected company as that category (e.g. `{"category":"vendor","connected_domain":"salesforce.com"}` → companies that have Salesforce as a vendor). Category is one of `vendor, investor, partner, integration, customer, parent, holding`. Fields within an entry must match the same connection; multiple entries are AND'd. Max 10.
`sort_by`	string	No	Field to sort by.
`sort_order`	string	No	`asc` or `desc` (default `desc`).
`cursor`	string	No	Opaque pagination cursor from a prior response's next_cursor.

Response#

json

{
  "items": [
    {
      "company_id": "predictleads:acme.com",
      "name": "Acme Inc.",
      "domain": "acme.com",
      "industry": "Software",
      "employee_count": 320,
      "country": "United States",
      "city": "San Francisco",
      "technologies": ["aws", "stripe"],
      "founded_year": 2014
    }
  ],
  "total": 4213,
  "aggregations": { "industries": [ /* facet counts */ ] },
  "next_cursor": "eyJvZmZzZXQiOjI1fQ"
}

Code samples#

curl -X POST https://api.cornect.io/api/v1/companies/search \
  -H "Authorization: Bearer cornect_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"fintech","countries":["United States"],"employee_count_min":50,"exclude_industries":["Staffing and Recruiting"],"exclude_keywords":["consulting"],"connections":[{"category":"vendor","connected_domain":"salesforce.com"}]}'

Errors#

See Errors for the full table. Codes you're most likely to see here:

Code	Status	When
`INSUFFICIENT_SCOPE`	403	A token without read scope (shouldn't occur — read_write includes read).
—	429	Rate limit exceeded (60/min).

Interactive reference#

Loading interactive reference…