Data models

Key concepts

RPO responses are built around two concepts that explain almost everything:

Validity: most fields are timed, which means they carry a validity window.
Codes: most categorical values link to a codelist entry — see Codelists.

Internalize these two concepts before reading the individual type docs — they appear on nearly every field in the API.

Type hierarchy

RPO’s type system is shallow by design. A handful of primitives compose into the types you’ll work with directly.

Embedded types

object

A categorical value pairing a human-readable label with its codelist reference. Used wherever a field belongs to a controlled vocabulary.

code can be an empty string — not null, not absent — when no matching codelist entry exists. Always guard against "" before using it as a lookup key.

Show properties

string

required

Human-readable label (in Slovak). Always use this for display.

string

required

Codelist entry key. Empty string if no matching entry exists.

string

required

Identifies the codelist, e.g. CL000056. See Codelists.

object

A string value with a validity window. The building block for any scalar field that can change over time — names, identifiers, and similar.

Show properties

string

required

The scalar value for this time period.

string

Validity start (YYYY-MM-DD). Absent if the start date is unknown.

string

Validity end (YYYY-MM-DD). Absent means this is the current value — not a data gap.

object

The timed variant of a codelist-backed value. Wraps a CodeValue in a validity window so you can track when a classification like legal form or legal status changed.

Note the double .value — the outer one is the timed entry property, the inner one is the human-readable label on the CodeValue.

Show properties

CodeValue

required

The categorical value for this period. Has its own .value, .code, and .codelistCode.

string

Validity start (YYYY-MM-DD).

string

Validity end. Absent if current.

object

A structured postal address with a validity window. Use formatedAddress for display; parse the sub-fields only when filtering or grouping by location.

Show properties

string

Pre-formatted full address string. Use for display.

string

Validity start (YYYY-MM-DD).

string

Validity end. Absent if current address.

string

Street name.

number

Registry number (súpisné číslo).

string

Orientation number (orientačné číslo).

string[]

Array of postal codes. Usually one entry.

CodeValue

Municipality from codelist CL000025 or UCE.

CodeValue

City quarter from codelist CL010141 or UCE.

CodeValue

Country from codelist CL000086 or STA.

string

Building identifier from the Address Register.

Entity types

object

A registered economic activity. Activities can be individually suspended without being terminated — giving three distinct states to check.

Active = no validTo and not suspended. Suspended = suspendedFrom set, suspendedTo absent. Deregistered = validTo set.

Show properties

string

Free-text description of the activity.

string

Date from which the activity is registered.

string

Date the activity was deregistered. Absent if still registered.

string

Suspension start date.

string

Suspension end date. Absent if currently suspended.

object

A structured name for a natural person. All components are arrays — a person may have multiple given names or titles.

Show properties

string

Pre-formatted full name. Use for display.

string[]

First name(s).

string[]

Current family name(s).

string[]

Birth family name(s).

CodeValue[]

Titles before the name (e.g. Ing., JUDr.) from codelist CL000062.

CodeValue[]

Titles after the name (e.g. PhD.) from codelist CL000063.

object

A person or organisation with a formal relationship to the entity — shareholders, partners, members, and similar roles. May be a natural person (FO) or a legal entity (PO/OZ).

Show properties

CodeValue

Role from codelist CL010109 (e.g. shareholder, partner).

string

Relationship start date.

string

Relationship end date. Absent if current.

Address

Address of the stakeholder.

PersonName

Name of the natural person. Present for FO only.

string

IČO of the legal entity or organisational unit. Present for PO/OZ only.

string

Full name of the legal entity. Present for PO/OZ only.

string

Date of incorporation. Present for PO/OZ only.

string

Date of dissolution. Present for PO/OZ only.

object

A person or organisation authorised to act on behalf of the entity. Structurally identical to Stakeholder with one addition: statutoryBodyMember captures the specific role within a collective board.

Show properties

CodeValue

Type of statutory body from codelist CL010113.

CodeValue

Role within a collective body from codelist CL010470 (e.g. chairman, member).

string

Appointment start date.

string

Appointment end date. Absent if current.

Address

Address of the statutory body.

PersonName

Name of the natural person. Present for FO only.

string

IČO of the legal entity. Present for PO/OZ only.

string

Full name of the legal entity. Present for PO/OZ only.

string

Date of incorporation. Present for PO/OZ only.

string

Date of dissolution. Present for PO/OZ only.

Timed values

Instead of a single current value, most fields return an array of time-scoped entries. The current value is always the entry where validTo is absent. Entries with both validFrom and validTo set are historical.

{
  "fullNames": [
    { "value": "Acme s.r.o.", "validFrom": "2021-03-15" }
  ]
}

{
  "fullNames": [
    { "value": "Acme s.r.o.", "validFrom": "2021-03-15" },
    { "value": "Beta s.r.o.", "validFrom": "2010-01-01", "validTo": "2021-03-14" }
  ]
}

Historical data is opt-in. Pass showHistoricalData=true on the detail endpoint — without it, all entries with a validTo are omitted.

Examples

Get the current value of a timed field

The current entry is the one with no validTo. Safe to use on any timed array — fullNames, identifiers, legalForms, etc.

const current = entity.fullNames.find(e => !e.validTo);
console.log(current.value); // "Acme s.r.o."

Look up a value at a specific past date

Useful for reconstructing entity state at a point in time — auditing, historical reports, or change detection.

function valueAt(entries, date) {
  return entries.find(e =>
    e.validFrom <= date && (!e.validTo || e.validTo >= date)
  );
}

const nameIn2015 = valueAt(entity.fullNames, "2015-06-01");
console.log(nameIn2015?.value); // "Beta s.r.o."

List the full history of a field, newest first

Sort by validFrom descending to get a chronological changelog of any timed field.

const history = [...entity.fullNames]
  .sort((a, b) => b.validFrom.localeCompare(a.validFrom));

history.forEach(e => {
  const to = e.validTo ?? "present";
  console.log(`${e.validFrom} → ${to}: ${e.value}`);
});
// 2021-03-15 → present:     Acme s.r.o.
// 2010-01-01 → 2021-03-14:  Beta s.r.o.

Getting started

Concepts

API Reference

Key concepts

Type hierarchy

Embedded types

Entity types

Timed values

Examples

​Key concepts

​Type hierarchy

​Embedded types

​Entity types

​Timed values

​Examples

Key concepts

Type hierarchy

Embedded types

Entity types

Timed values

Examples