Skip to main content

​
Key concepts

RPO responses are built around two concepts that explain almost everything:
  1. Validity: most fields are timed, which means they carry a validity window.
  2. 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

​
CodeValue
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.
​
TimedValueEntry
object
A string value with a validity window. The building block for any scalar field that can change over time — names, identifiers, and similar.
​
TimedCodeValueEntry
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.
​
Address
object
A structured postal address with a validity window. Use formatedAddress for display; parse the sub-fields only when filtering or grouping by location.

​
Entity types

​
Activity
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.
​
PersonName
object
A structured name for a natural person. All components are arrays — a person may have multiple given names or titles.
​
Stakeholder
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).
​
StatutoryBody
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.

​
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" }
  ]
}
Historical data is opt-in. Pass showHistoricalData=true on the detail endpoint — without it, all entries with a validTo are omitted.

​
Examples

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."
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."
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.