Ejerdata API: legale ejere, koncernrelationer og ultimative ejere

Når man spørger, hvem der ejer en virksomhed, kan man mene tre forskellige ting. Det er vigtigt at holde dem adskilt, fordi de har forskellig juridisk betydning.

Fra Basis-planen får du ejerregisteret og ledelsen. Feltet history.register_entries viser ejere med ejerandel og stemmeandel, og executives og board_members viser direktion og bestyrelse.

curl "https://firmaapi.dk/api/v1/company/12345678?include=history" \
  -H "Authorization: Bearer cvr_live_din_api_nøgle"

{
  "cvr": "12345678",
  "name": "Eksempel Drift ApS",
  "history": {
    "register_entries": [
      {
        "name": "Eksempel Holding ApS",
        "participant_cvr": "87654321",
        "ownership_percentage": 1,
        "voting_percentage": 1,
        "valid_from": "2019-05-01",
        "valid_to": null
      }
    ]
  },
  "executives": [
    { "name": "Eva Eksempel", "function": "ADM. DIR." }
  ]
}

Bemærk, at ownership_percentage og voting_percentage i ejerregisteret er decimaler, hvor 1 betyder 100 procent og 0,25 betyder 25 procent. Er ejeren et selskab, står dets CVR-nummer i participant_cvr. Det kan du bruge til at slå ejeren op og gå et led opad selv. Er ejeren en person eller en udenlandsk enhed, er feltet ofte null.

Med include=relations får du de direkte moder- og datterselskaber. Hver relation har CVR-nummer, navn, ejerandel og stemmeandel i procent, hvor 50 betyder 50 procent. Feltet inferred viser, at relationen er udledt af ejerregistret og ikke er registreret som en selvstændig koncernoplysning.

Relationerne er et godt udgangspunkt for at tegne en koncernstruktur. De følger kun ét led ad gangen. Vil du have hele kæden til personerne, bruger du i stedet ultimative ejere.

Med include=ultimate_owners følger FirmaAPI de legale ejere op gennem kæden, indtil hver gren ender i en fysisk person. Den effektive ejerandel er produktet af andelene langs kæden, og andelene lægges sammen, hvis samme person ejer via flere grene.

curl "https://firmaapi.dk/api/v1/company/12345678?include=ultimate_owners&max_depth=10" \
  -H "Authorization: Bearer cvr_live_din_api_nøgle"

{
  "cvr": "12345678",
  "ultimate_owners": {
    "method": "calculated_from_legal_owners",
    "disclaimer": "Beregnet af FirmaAPI ud fra de registrerede legale ejere ...",
    "threshold_percent": 25,
    "persons": [
      {
        "name": "Eva Eksempel",
        "effective_ownership_percent": { "min": 50, "max": 66.66 },
        "is_interval": true,
        "meets_threshold": true,
        "threshold_status": "met",
        "paths": [
          {
            "depth": 2,
            "chain": [
              { "cvr": "87654321", "name": "Eksempel Holding ApS" },
              { "cvr": null, "name": "Eva Eksempel" }
            ]
          }
        ]
      }
    ],
    "unresolved": [],
    "truncated": false
  }
}

Det er værd at forstå, hvad svaret fortæller:

• Intervaller. Effektiv andel er et interval med min og max, fordi CVR angiver andele i intervaller.
• 25 procent. meets_threshold er sand, når nedre grænse er mindst 25 procent. threshold_status er met, possible eller not_met.
• Grene uden person. De står i unresolved med en årsag, fx foreign_owner for en udenlandsk ejer eller no_registered_owners for fx en fond.
• Krydsejerskab. Registreres i cycles og følges ikke rundt.
• Grænser. Højst 10 niveauer, 500 selskaber og 5.000 ejerstier. Rammes en grænse, er truncated sat til sand.

Resultatet caches i 24 timer pr. CVR-nummer og dybde. Andre planer end Professionel og Enterprise får 403 PLAN_UPGRADE_REQUIRED med et upgrade_url.

import os
import requests

API_KEY = os.environ["FIRMAAPI_KEY"]

def ultimative_ejere(cvr: str, max_depth: int = 10) -> dict:
    res = requests.get(
        f"https://firmaapi.dk/api/v1/company/{cvr}",
        params={"include": "ultimate_owners", "max_depth": max_depth},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=20,
    )
    if res.status_code == 403:
        fejl = res.json()["error"]
        raise PermissionError(fejl.get("message", "Kræver Professionel"))
    res.raise_for_status()
    return res.json()["ultimate_owners"]

resultat = ultimative_ejere("12345678")
for person in resultat["persons"]:
    andel = person["effective_ownership_percent"]
    print(person["name"], andel["min"], andel["max"], person["threshold_status"])

if resultat["unresolved"]:
    print("Grene uden identificeret person:", len(resultat["unresolved"]))

Eksemplet håndterer 403, hvis planen ikke har adgang, og lader dig se, om der er grene, som ikke kunne føres helt til en person. Det er en vigtig del af at bruge resultatet ansvarligt: en tom liste af personer er ikke det samme som, at virksomheden ingen ejere har.

Den avancerede søgning har filteret owner_kind, der matcher de direkte, aktive legale ejere. Værdierne er person, holding, fund, company og foreign. Det er ikke den ultimative ejer.

curl "https://firmaapi.dk/api/v1/search/advanced?owner_kind=holding,fund&status=Aktiv&industry=62&limit=20" \
  -H "Authorization: Bearer cvr_live_din_api_nøgle"

Hvis du bruger ejerdata til screening, bør du gemme tidspunktet for opslaget og versionen af svaret, så du senere kan dokumentere, hvad du vidste. Læs også om, hvordan du får besked, når ejere ændrer sig, på siden om CVR webhooks. Se priser for planer.