> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Company Search

> Find companies and obtain the ID required for verification and onboarding

Search is the entry point to Topograph. Before you can retrieve company data, download documents, or set up monitoring, you need the company's unique identifier. Search gives you that identifier.

<Info>
  For endpoint details, request/response schemas, and code examples, see the [Search API Reference](/api-reference/search/search-for-companies).
</Info>

## Why Search Matters

Every Topograph integration starts with a company ID:

* **Onboarding**: Pass the ID to [`POST /v2/company`](/essentials/retrieve_company) with `mode: "onboarding"` to prefill customer forms ([modes](/essentials/modes))
* **Verification**: Pass the ID to [`/v2/company`](/essentials/retrieve_company) to fetch authoritative register data
* **Documents**: Use the ID to retrieve official PDFs from public registers
* **Monitoring**: Use the ID to [track changes](/essentials/monitoring) over time

Search is how you get that ID. It's free, fast, and designed to handle the complexity of finding companies across different countries with different identifier formats.

## How Search Works

Topograph combines multiple data sources to give you the best possible results:

### Registry Search

For most queries, we leverage the search capabilities of official company registries directly. This gives you authoritative, up-to-date results. The registry's own search algorithm determines relevance. Some registries have sophisticated fuzzy matching, while others only support exact matches.

### Cached Index Search

For select countries, we maintain a local index of company data. This enables:

* **Faster results**: Sub-second response times without registry latency
* **Better fuzzy matching**: Our own search algorithms handle typos and partial matches
* **Consistent behavior**: Same matching quality regardless of registry quirks
* **Higher availability**: Results even when the registry is temporarily down

When both sources are available, we query them in parallel and merge the results. This gives you the speed of fast search with the comprehensiveness of live registry data.

<Tip>
  Use [streaming mode](/api-reference/search/search-for-companies) to display results as they arrive. In countries with multiple sources, your users see initial results almost instantly while additional results load in the background.
</Tip>

## Understanding Results

### Match Types

Every result includes a `matchReason` that explains how it was found. This helps you assess result quality and build appropriate logic around different confidence levels.

| Match Type       | Meaning                                                             | Reliability         |
| ---------------- | ------------------------------------------------------------------- | ------------------- |
| `id`             | Exact match on a unique identifier (VAT, registration number, etc.) | Guaranteed correct  |
| `exactLegalName` | Legal name exactly matches your query                               | Very high           |
| `partialId`      | Matched on a partial identifier that isn't globally unique          | High, but verify    |
| `default`        | Generic match from registry search                                  | Depends on registry |

**When `matchType` is `id` or `partialId`**, the response includes an `identifier` field showing exactly what matched (e.g., `{ "VAT": "02580590541" }` or `{ "CCIAA": "TO", "REA Code": "1234567" }`).

**When `matchType` is `default`**, the result came from the registry's own search algorithm. Quality varies significantly: some registries return highly relevant results, others may include tangential matches. Consider `default` results as suggestions that benefit from user confirmation.

<Warning>
  Results with `matchType: "default"` depend entirely on the underlying registry's search quality. Always verify these matches when precision matters, especially for automated processing.
</Warning>

### Result Ordering

Results are automatically sorted by match reliability:

1. **`id`**: Guaranteed matches appear first
2. **`exactLegalName`**: Exact name matches second
3. **`partialId`**: Partial identifier matches third
4. **`default`**: Generic matches last

This ordering ensures the most trustworthy results appear at the top. When building UIs, consider visually distinguishing high-confidence matches from `default` matches to help users make informed selections.

## Searching Effectively

### Search by Identifier When Possible

If you have a company's VAT number, registration number, or tax code, search with that. Identifier searches return `id` match types, guaranteed 1:1 matches with no ambiguity. This is always the most reliable approach.

### Scope by Country

Always specify the country. Country-scoped searches are faster and return more relevant results. If you're building an onboarding flow, you likely already know the customer's country from earlier in your form.

### Handle Ambiguous Results

When your search returns multiple results with `default` match types, present them to the user for selection rather than auto-selecting. The first result isn't always the right one, and registries don't always order by relevance.

### Use Streaming for Interactive UIs

In interactive applications, enable streaming to show results progressively. This improves perceived performance significantly. Users see initial results in under a second rather than waiting for all sources to complete.

## Search in the KYB Flow

Search is the critical first step in a typical KYB onboarding flow:

```mermaid theme={null}
flowchart LR
    Search[Search] --> Onboard[Onboard]
    Onboard --> Verify[Verify]
    Verify --> Monitor[Monitor]
```

1. **Search**: Customer finds their company, you capture the ID
2. **Onboard**: Use the ID with [`POST /v2/company`](/essentials/retrieve_company) and [`mode: "onboarding"`](/essentials/modes) to prefill forms quickly (per-country block pricing, P90 \< 5s in most markets)
3. **Verify**: Use the ID with [`/v2/company`](/essentials/retrieve_company) to fetch authoritative register data
4. **Monitor**: Use the ID to [track changes](/essentials/monitoring) and stay compliant

The search step costs nothing and typically completes in under 5 seconds. It's designed to minimize friction at the very start of your funnel.

## Fair Use

Search is free under a fair use policy, proportional to the company lookups it leads to. It's the resolution layer that gives you the ID you pass to [`/v2/company`](/essentials/retrieve_company), so search volume is expected to track the company data you go on to retrieve.

Typeahead is exactly what search is built for. Search accepts partial names and identifiers (a 2-character minimum applies), so you can wire it straight into an autocomplete. Debounce on the client so you send a request when the user pauses typing rather than on every keystroke, and use [streaming mode](/api-reference/search/search-for-companies) for instant feedback.

What sits outside fair use is using search as a standalone database: high-volume exploratory querying that rarely converts into a company lookup, or enumerating a register to harvest its index. Those patterns may be rate-limited. If you expect very high search throughput, [get in touch](mailto:support@topograph.co) so we can size limits to your flow.

<Card title="KYB Onboarding Best Practices" icon="rocket" href="/guides/kyb-onboarding">
  Learn how to combine search with onboarding and verification endpoints to build high-conversion KYB flows.
</Card>

## Country Considerations

Search capabilities vary by country due to differences in registry APIs and data availability:

| Capability         | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| **Name search**    | Most countries support searching by company name                         |
| **ID search**      | Most countries support searching by registration number or VAT           |
| **Fuzzy matching** | Varies by registry. Some handle typos well, others require exact matches |
| **Response time**  | From \~200ms (fast search index) to \~10s (slow registries)              |

Countries with fast search indexes generally offer faster responses and better fuzzy matching. For detailed country-specific information, browse [Country Guides](/essentials/austria).

<Note>
  Company ID formats vary by country. German IDs combine register and city (e.g., "Augsburg HRB 34617"). French IDs are SIREN numbers (9 digits). Italian searches can use VAT, Codice Fiscale, or CCIAA+REA combinations. The ID returned by search is always the correct format to use with other Topograph endpoints.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="For Automated Workflows">
    * Search by identifier (VAT, registration number) whenever available
    * Only trust `id` match types for fully automated processing
    * Filter by match type and queue `default` matches for manual review
    * Store the company IDs you retrieve for future API calls
  </Accordion>

  <Accordion title="For User Interfaces">
    * Use streaming mode for instant feedback as results arrive
    * Display match type indicators to help users assess result confidence
    * Show the matched identifier (VAT, registration number) when available
    * Let users confirm their selection rather than auto-selecting ambiguous matches
    * Consider showing a "Verified" badge for `id` matches
  </Accordion>

  <Accordion title="For High-Volume Operations">
    * Prefer identifier-based searches for maximum reliability
    * Stored source data company IDs from search results for subsequent API calls
    * Set strict match type requirements, only process `id` matches automatically
    * Handle lower-confidence matches in a separate review queue
  </Accordion>
</AccordionGroup>

## Next Steps

Once you have a company ID from search, you're ready to retrieve data:

<CardGroup cols={2}>
  <Card title="Data retrieval modes" icon="bolt" href="/essentials/modes">
    Verification vs onboarding (`mode`) for the same `/v2/company` endpoint
  </Card>

  <Card title="Verification Data" icon="shield-check" href="/essentials/retrieve_company">
    Authoritative data fetched directly from public registers
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/search/search-for-companies">
    Complete endpoint documentation with request/response schemas
  </Card>

  <Card title="Country Guides" icon="globe" href="/essentials/austria">
    Country-level details on search capabilities and identifier formats
  </Card>
</CardGroup>