> For the complete documentation index, see [llms.txt](https://help.bizmachine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bizmachine.com/en/api-and-integrations/api-endpoints/endpoint-suggest.md).

# Endpoint suggest: company search

Search for companies by name or domain and get the Company ID (IČO) to use in other API calls.

*Updated: 5 October 2026*

```
GET /{dataset}/v4/companies/suggest
```

Finds companies by **name**, **Company ID (IČO)**, **VAT ID (DIČ)** or **web domain**. For each company found, it returns the basic identification: name, Company ID, city and website. The default search looks in all of these fields at once, so one `Query` parameter is enough.

***

### When to use this endpoint

* You know the company name or domain and need the Company ID
* You are building a search field where the user starts typing a name, Company ID, VAT ID or website and gets instant suggestions
* As the first step in a pipeline before calling `aggregated-data`, `metrics` or other endpoints

#### What you can search by

The default search (without `FieldsToSearch`) looks in **all fields at once**. No extra setting is needed:

| Example query          | What is searched                                              |
| ---------------------- | ------------------------------------------------------------- |
| `Query=BizMachine`     | Company name (part of the name works too: `Query=BizMac`)     |
| `Query=27082440`       | Company ID                                                    |
| `Query=CZ27082440`     | VAT ID                                                        |
| `Query=bizmachine.com` | Web domain: finds the company even if the name does not match |

#### When to use a different endpoint

| You need                                      | Use instead            |
| --------------------------------------------- | ---------------------- |
| You know the Company ID and want company data | `aggregated-data` (v4) |
| A bulk query for several companies at once    | Collection endpoints   |

***

### Technical details

{% openapi src="/files/FGwu42o2gqsEWtcATX3u" path="/{dataset}/v4/companies/suggest" method="get" %}
[api-spec.temp.json](https://247275268-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYkl7SJ14Nk0vzhVx7upl%2Fuploads%2Fgit-blob-f3abeffbb2534d765afc74352238d1f9ef6bc845%2Fapi-spec.temp.json?alt=media)
{% endopenapi %}

#### What to watch out for

* The search also works on part of the name: `Query=BizMac` finds BizMachine s.r.o. Results are sorted by relevance, not alphabetically, so always verify the name and city.
* Without the `FieldsToSearch` parameter, the query searches all fields at once (name, Company ID, VAT ID, website and others).
* The `Limit` parameter sets the number of results per query (1 to 200, the default is 5) *(as of July 2026)*.

***

### Instructions for AI agents

Copy this block and give it to your agent. It describes how to use the endpoint correctly.

```
## BizMachine API: suggest endpoint (company search / lookup)

Purpose: Search for companies by name or domain and retrieve their national identifier (IČO / nationalIn)
for use with other BizMachine API endpoints.

When to use:
- You have a company name and need its IČO
- You have a domain/website and need the company's IČO
- You are implementing autocomplete over company data
- As the first step in a pipeline before calling aggregated-data, metrics, contacts, etc.

When NOT to use:
- You already know the IČO → call the target endpoint directly
- Bulk search by filters (region, NACE, size) → use collection endpoints

URL:
  GET https://api.bizmachine.com/{dataset}/v4/companies/suggest

Required:
  - Path: dataset - "cz", "sk", "hu", "pl", "de"
  - Query: Query - search string (company name, IČO, DIČ, or domain)
  - Header: X-Api-Key: {api_key}

Optional:
  - Query: Limit - number of results (1 to 200, default 5)

Key response fields:
  data[0].nationalIn             - company IČO → use as {nationalIn} in other endpoints
  data[0].uniqueId               - unique ID (format: "cz-company-27082440")
  data[0].name                   - company name
  data[0].city                   - city (use to verify correct company)
  data[0].contacts.website.url   - company website

Search behavior:
  - Default search (no FieldsToSearch) queries all fields simultaneously (name, IČO, DIČ, website, and more)
  - Partial name match works: "BizMac" will find "BizMachine s.r.o."
  - Domain search works without any extra parameters: Query=bizmachine.com finds "BizMachine s.r.o."
  - Use Limit to control number of results (1 to 200, default 5)

Gotchas:
  - data[0] is the most relevant result but always verify via name + city
  - Relevance ranking is not purely alphabetical - short queries may return larger companies first

Typical workflow (name to IČO):
  1. suggest?Query={company_name}&Limit=1  → get nationalIn from data[0].nationalIn
  2. /{dataset}/v4/companies/{nationalIn}/aggregated-data  → get company profile

Typical workflow (domain to IČO):
  1. suggest?Query={domain}&Limit=1  → get nationalIn from data[0].nationalIn
  2. Call target endpoint with nationalIn
```

***

Need help? Write to <support@bizmachine.com>