Search

GET /v1/search for autocomplete by name or identifier, and the explicit fuzzy mode.

GET /v1/search?q=<text>&mode=default|fuzzy&limit=<1-20>

Parameter	Default	Meaning
`q`	required	A name or an identifier, 1–200 characters.
`mode`	`default`	`fuzzy` corrects typos; it is explicit, rate-limited and may be disabled.
`limit`	`10`	At most 20.

curl -H "Authorization: Bearer $KEY" "http://localhost:8080/v1/search?q=rybka%20zlata"

{
  "mode": "default",
  "results": [
    { "ico": "99900001", "name": "Zlatá Rybka, s.r.o.", "municipality": "Fiktívne Mesto",
      "address": { "street": "Testovacia", "buildingNumber": "1", "postalCode": "999 99", "municipality": "Fiktívne Mesto", "country": "Slovenská republika" }, "kind": "legal_person", "active": true },
    { "ico": "99900002", "name": "Strieborná Rybka, a.s.", "municipality": "Fiktívne Mesto",
      "address": { "street": "Testovacia", "buildingNumber": "1", "postalCode": "999 99", "municipality": "Fiktívne Mesto", "country": "Slovenská republika" }, "kind": "legal_person", "active": true }
  ],
  "dataAsOf": "2026-11-10",
  "attribution": ["Register právnických osôb, Ministerstvo vnútra SR, CC BY 4.0", "Zdroj údajov: Finančná správa SR"]
}

curl -H "Authorization: Bearer $KEY" "http://localhost:8080/v1/search?q=SK2099900100"

An IČO, DIČ or IČ DPH is matched exactly. A VAT group’s IČ DPH returns every member with an IČO. A terminated subject is returned too, with active: false.

curl -H "Authorization: Bearer $KEY" "http://localhost:8080/v1/search?mode=fuzzy&q=zlta%20rybka"

{
  "mode": "fuzzy",
  "results": [
    { "ico": "99900001", "name": "Zlatá Rybka, s.r.o.", "kind": "legal_person", "active": true, "typos": 1 }
  ],
  "corrections": ["zlta→zlata"],
  "attribution": ["…"]
}

The result card

Field	Meaning
`ico`	The subject’s IČO (absent for a record without one).
`name`	The display name, with diacritics and legal form.
`matchedName`	The official name that matched, when it is not the display name (a sole trader’s other name).
`municipality`	Municipality of the seat or place of business.
`address`	The full seat or place of business as published in RPO: `street`, `buildingNumber`, `postalCode`, `municipality`, `country`. The same as in the lookup.
`kind`	`legal_person`, `sole_trader`, `public_body` or `other`.
`active`	`false` only for a terminated subject found by identifier.
`typos`	Fuzzy only: corrections needed.

Search proposes; it does not resolve. When the user picks a card, call GET /v1/lookup/{ico} for the full record.

Good client behaviour

Debounce typing by about 120–250 ms. Without it, every keystroke is a request.
Never auto-select the first result. Two subjects can share a name.
Offer fuzzy only as an explicit action, for example “Nothing found. Search with typos?”, and only when /v1/capabilities says it is enabled.
On 429, wait the number of seconds in Retry-After.