Get Company Owners

Parse current owners from the latest Handelsregister Gesellschafterliste for a mirrored German company. The enrichment supports embedded-text/table PDFs only and never uses OCR.

[!NOTE] Call get_company first if the company is not yet in the registry mirror. sources[].document_url values are generated fresh for each response and expire after 15 minutes.

Try it

Pricing

10 credits when current owners are parsed from cache or a normal live download.
20 credits when realtime=true bypasses the document cache.
0 credits/refund when the company/document is unavailable, the shareholder list is a scanned legacy PDF, or best_available=true requests unsupported AG/SE beneficial-owner inference in v1.

Endpoint

Input Parameters

realtime=true and best_available=true cannot be combined.

Examples

Current owners

curl -X POST https://api.skael.de/api/enrichments/get_company_owners \
  -H "Authorization: Bearer eak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "DE-HRB-F1103-267645"
  }'

Realtime cache bypass

curl -X POST https://api.skael.de/api/enrichments/get_company_owners \
  -H "Authorization: Bearer eak_..." \
  -d '{
    "company_id": "DE-HRB-F1103-267645",
    "realtime": true,
    "async": true
  }'

Output Fields

Output Shape

owners[] contains aggregated owner records matching the Company Owners schema.
type is natural_person or legal_person.
id is a deterministic natural-person UUID, a linked legal-person company_id, or null when no deterministic legal-person mirror link exists.
nominal_share is the parsed EUR nominal amount.
percentage_share is a fraction from 0.0 to 1.0.
start is the parsed relation start date when available; end is included only when an end date is parsed.
sources[] contains source document objects matching the researched Company Owners schema. document_url is null in stored enrichment output and populated with a fresh signed URL only when the response is presented.
best_available is a top-level boolean. It is false for current GmbH shareholder-list parsing and true only for best-available fallback responses.
_registry_meta.warnings includes percentage_sum_drift when parsed percentages differ from 1.0 by more than 0.005.

Unsupported Legacy Scans

Scanned/OCR-only legacy PDFs return a completed enrichment with no charge:

{
  "owners": [],
  "sources": [{ "document_url": null }],
  "best_available": false,
  "_registry_meta": {
    "status": "legacy_scan_unsupported",
    "warnings": ["legacy_scan_unsupported"]
  }
}

Best Available v1 Behavior

best_available=true is reserved for future AG/SE beneficial-owner inference. In v1 it returns an empty response with best_available_unsupported and refunds credits rather than inventing beneficial-owner data.

Cache and Snapshot Behavior

The latest shareholder list is downloaded through the shared Handelsregister document cache. Normal requests reuse a fresh cached shareholder_list document; realtime=true bypasses the cache lookup and downloads the latest document again.

Parsed owner snapshots are persisted idempotently by company_id and source document ID in the platform mirror. Snapshot rows store only public registry data: owner records, source document ID, parsed document date, raw embedded text, and parser warnings. They do not store tenant, request, callback, secret, or signed URL data.

Feature Disabled (403)

{
    "message": "German registry enrichments are not enabled for this organization."
}