---
title: Integrating an application
description: A checklist for using the register in an invoicing or accounting application.
---

**Let your AI agent **integrate** company search and lookup into your application, following these rules.**

> Integrate Accquix Register, a self-hosted API for the Slovak business registers, into this application, so that users can choose a company (a customer or a supplier) on forms such as invoices.
>
> The instance is at `https://register.example.internal` (ask me for the real address). Read its OpenAPI contract at `/openapi.json` and its limits at `/v1/capabilities` (send `Authorization: Bearer <key>`), and build a typed client from the contract instead of guessing fields. Keep the API key in configuration, never in code, tests or logs.
>
> Build it like this:
>
> 1. A search box calls `GET /v1/search` as the user types: from 2–3 characters, with a debounce of about 250–300 ms, cancelling the previous request. Show the name, the IČO and the full address of each result, because different subjects can share a name.
> 2. A search result is a candidate, not a fact. When the user picks one, call `GET /v1/lookup/{ico}` and fill the form only from that answer.
> 3. Store the IČO and each section's `source.version` with the saved company. Later, look it up by IČO instead of searching again, and check for changes once a day with `POST /v1/lookup:batch`.
>
> Rules:
>
> - `503`, a section in state `unknown`, or a `stale` flag means the data is unknown, never "not found". Let the user continue with data they confirm; never block the document.
> - Treat a subject as a VAT payer only when `vat.payer` is `true`. §7 and §7a subjects have an IČ DPH but are not VAT payers. Show the as-of date next to VAT information.
> - An IČ DPH can belong to several subjects (a VAT group): let the user choose.
> - Identifiers are exact: never match or correct an IČO, DIČ or IČ DPH fuzzily.
> - When you show register data to other people, show the `attribution` texts from the response.
> - On `429`, wait for `Retry-After`; retry `GET` requests after connection errors with a backoff.
>
> Cover these rules with tests that use fictional companies only.

The pattern that works for an application such as an invoicing tool:

1. **Search proposes**

    Show `/v1/search` results as the user types, with a debounce. Show the name, the IČO and the full address:
    two subjects can share a name.

2. **Only an exact identifier resolves**

    When the user picks a result, call `/v1/lookup/{ico}` and use that answer. Never fill a form from the first
    search result on your own.

3. **Keep the versions**

    Store each section's `source.version` with your copy of the counterparty.

4. **Check daily**

    Once a day, call `/v1/lookup:batch` with `fields: "versions"` and show the user what changed. See
    [Change detection](/api/changes).

## Rules that keep documents correct

- **Unknown is not "not found".** Treat `503`, `unknown` and `stale` as "unknown". An outage of the register must
  not block issuing a document; let the user continue with the data they confirm.
- **VAT wording.** Print "platiteľ DPH od …" only when `vat.payer` is `true`. §7 and §7a subjects have an IČ DPH but
  are not VAT payers. See [VAT status](/concepts/vat).
- **The register entry pre-fills; the user confirms.** `identity.registrations[]` gives the court and number for a
  supplier's legal line. The genitive court name and the exact wording are yours to build.
- **Cite the date.** "According to the Financial Administration list of 10 Nov 2026" is accurate;
  "is a VAT payer" without a date is not.
- **EU VAT numbers.** Query VIES yourself: the register does not mirror it.
- **Attribution.** If you show the data to others, show the `attribution` texts the licences require.

## Retries and outages

- Retry safe `GET` requests after a connection error, with a backoff.
- Honour `Retry-After` on `429`.
- Read `/v1/capabilities` at start-up: whether fuzzy search is enabled, and the limits.