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

# Codelists

> Controlled vocabularies referenced by CodeValue fields across the API.

***

## What are codelists?

Categorical fields like legal form, legal status, and municipality return a coded value rather than a plain string. Each coded value has the same shape:

```json theme={null}
{
  "value": "spoločnosť s ručením obmedzeným",
  "code": "112",
  "codelistCode": "CL000056"
}
```

* `value` — human-readable label in Slovak. Use for display.
* `code` — stable entry key. Use for storing, filtering, and comparing.
* `codelistCode` — identifies which codelist this value belongs to.

<Note>
  Most codelists are published by the Statistical Office of the Slovak Republic (ŠÚR). `UCE` and `STA` are maintained by the Ministry of Interior and are not publicly available in the same way.
</Note>

***

## Why codes matter

Codes are stable keys that never change — the human-readable label can. A field value might get a wording update, a typo fix, or a punctuation change in the source data. The code behind it won't.

Two situations where this matters:

* **Storing or comparing data.** Always store the code, not the label. Matching on a label that could silently change will eventually break.
* **Building in another language.** Use the code as a key into your own translation table instead of parsing Slovak strings.

<Warning>
  `code` can be an empty string when no matching codelist entry exists. Always guard against `""` before using it as a lookup key.
</Warning>

***

## Codelist reference

| Code       | Description                         | Resolves field                             |
| ---------- | ----------------------------------- | ------------------------------------------ |
| `CL000025` | Municipality                        | `address.municipality`                     |
| `CL000056` | Legal form                          | `legalForms[].value`                       |
| `CL000062` | Title before name                   | `personName.prefixes[]`                    |
| `CL000063` | Title after name                    | `personName.postfixes[]`                   |
| `CL000083` | Currency unit                       | `equities`                                 |
| `CL000086` | Country                             | `address.country`                          |
| `CL005205` | Economic activity                   | `statisticalCodes`                         |
| `CL010010` | ESA 2010 institutional sub-sector   | `statisticalCodes`                         |
| `CL010108` | Legal status                        | `legalStatuses[].value`                    |
| `CL010109` | Type of interested party            | `stakeholders[].stakeholderType`           |
| `CL010110` | Type of organisational unit         | `organizationUnits`                        |
| `CL010111` | Type of share                       | `equities.shares`                          |
| `CL010112` | Source register                     | `sourceRegister`                           |
| `CL010113` | Type of statutory body              | `statutoryBodies[].stakeholderType`        |
| `CL010141` | City quarter                        | `address.district`                         |
| `CL010470` | Role in collective statutory body   | `statutoryBodies[].statutoryBodyMember`    |
| `UCE`      | Municipality (Ministry of Interior) | `address.municipality`, `address.district` |
| `STA`      | Country (Ministry of Interior)      | `address.country`                          |

***

## Resolving a code

Match on both `code` and `codelistCode` to avoid false positives — the same code string can appear in different codelists with different meanings.

```js theme={null}
// Resolve the current legal form label
const form = entity.legalForms.find(f => !f.validTo);
console.log(form?.value.value); // "spoločnosť s ručením obmedzeným"

// Filter by a specific code
const isSro = entity.legalForms
  .filter(f => !f.validTo)
  .some(f =>
    f.value.codelistCode === "CL000056" &&
    f.value.code === "112"
  );
```

***

## Dual codelists on address fields

`municipality`, `district`, and `country` can reference entries from either a Statistical Office or a Ministry of Interior codelist, depending on which source register the entity comes from. Always check `codelistCode` before doing a lookup.

| Field          | Statistical Office | Ministry of Interior |
| -------------- | ------------------ | -------------------- |
| `municipality` | `CL000025`         | `UCE`                |
| `district`     | `CL010141`         | `UCE`                |
| `country`      | `CL000086`         | `STA`                |

```js theme={null}
if (address.municipality.codelistCode === "CL000025") {
  // Statistical Office codelist
} else if (address.municipality.codelistCode === "UCE") {
  // Ministry of Interior codelist
}
```