Country filter for company and contact search

Effective date: November 3, 2026

Company search and contact search can now filter by country. The filter matches the country of the company's headquarters (HQ). It is live for every workspace, in the API, the API Explorer and the hosted MCP server.

The new `country` filter

POST /v1/companies/search and POST /v1/contacts/search accept a new country parameter:

{
  "signal_types": ["hiring-trends"],
  "industries": ["Software"],
  "country": ["DE", "AT", "CH"],
  "limit": 25
}

Detail	How it works
What it matches	The company's HQ country, the same value as `hq_country` on each company (ISO-2).
Contact search	It matches the HQ country of the contact's company, not where the person lives. Check `company.hq_country` on each contact. The contact's own `country` can be different.
Values	ISO-2 codes (`"US"`), ISO-3 codes (`"DEU"`) or country names (`"Germany"`). Case does not matter.
Names	Accents are optional (`"México"` or `"Mexico"`). Common short forms work: `"USA"`, `"UK"`, `"Britain"`, `"Holland"`, `"UAE"`, `"Swiss"`, `"KSA"` and local names like `"Deutschland"`, `"España"`, `"Brasil"`, `"Italia"`, `"Polska"`.
More than one value	Any match counts (OR). Up to 250 values.
Alias	`company_country` is the same filter. If you send both, the values are combined.
Other filters	Use it with `signal_types`, `signal_subtypes`, `industries`, `employee_count_min` / `_max`, `revenue_min` / `_max`, `seniority`, `department`, `job_title` and `detected_after`.
Unknown HQ	A company with no known HQ country never matches. About 72% of companies in search have a known HQ country.
Price	No change. Search costs the same per result. A search with no results costs 0 credits.

Find the valid values

GET /v1/filters (free) has a new search_country entry with all 250 codes and the parameter names:

"search_country": {
  "values": ["AD", "AE", "AF", "..."],
  "match": "exact-normalized",
  "params": ["country", "company_country"],
  "applies_to": ["companies/search", "contacts/search"]
}

Clear errors, 0 credits

A bad value returns HTTP 400, costs 0 credits, and tells you what to send:

You send	You get
`"country": ["Untied States"]`	`Invalid country value(s): 'Untied States'. Did you mean 'US'?`
`"country": ["OO"]`	`'OO' is not a country code. Send ISO-2 or ISO-3 codes or country names (e.g. ["US"]).`
`"country": [""]`	`Invalid country value(s): empty string.`
`"country": "US"` (not a list)	`country must be an array of strings`
`"contact_country": ["US"]`	`contact_country is not supported on this endpoint: the search country filter matches the company's HQ country. Use country (ISO-2 codes or names, e.g. ["US"]).`

Contact search: the company always matches your filters

With any company filter (industries, employee count, revenue or country), each contact now shows only signals from companies that pass the filter. Before, a contact who changed jobs could show a company outside your filter. In our tests, that was about 8 in 100 contacts.

Buyer intent: accented country names

The existing country filter on /v1/buyer-intent/contacts and its export now also accepts accented names, for example "México" or "Türkiye".

API Explorer

Company and contact search have a Country picker.
Type a code, a name or a short form. For example, "usa" finds United States and "uk" finds United Kingdom.
Select all N shown picks every value that matches your search. This works in every multi-select in the Explorer.

MCP server

searchCompanies and searchContacts have the country and company_country parameters on the hosted MCP server (version 1.3.2).
The MCP server no longer drops parameters it does not know. It sends them to the API, and the API checks them. Before, an unknown filter was dropped without a message, and you paid for unfiltered results. Now you get the API's answer: the filtered results, or a clear 400 at 0 credits.

Questions? [email protected]

The new country filter