registercheckby openlaw group

Migration guide

Every name /v1 changed in October 2026, old next to new, and what to change in your code.

In October 2026 /v1 moved to one model: one word for each thing the register holds, ids that say what they name, one page envelope for every list, and one shape for every reference to a company or person. The glossary has the words; this page has every change, old next to new.

The changes are breaking, and they happen in place. The base URL stays https://api.registercheck.de/v1; there is no /v2.

What keeps working until 31 December 2026

Three old forms are still accepted, so you can move at your own pace:

  • a raw UUID wherever an id is expected (Ids);
  • q instead of name on search and on GET /formations (Parameters);
  • GET /company-events and GET /company-events/{id} instead of /events (Paths).

A response to a request that used one carries Deprecation (when the replacement shipped), Sunset: Thu, 31 Dec 2026 23:59:59 GMT (the last moment it is served) and Link: <…>; rel="deprecation"; type="text/html": this page for a raw UUID and for /company-events, and How name matches for q. Log every response that has a Deprecation header and you have your to-do list.

Every other renamed path answers 410 endpoint_retired from the release on, and detail names its replacement. Nothing else is aliased.

What to change

Ids. Convert the ids you have stored to prefixed ids, or keep sending UUIDs until 31 December 2026 and convert before then. Ids

Paging. Replace starting_after, ending_before, page, has_more and next_page with cursor and next_cursor. Pagination

Paths. Point every call at its new path. Paths

Fields. Rename the fields you read, and read every reference to a company or person as a party. Objects and fields

Jobs. Read a lookup's candidates from lookup, and ask for result.company on GET /jobs with expand. Jobs

Webhooks. Parse a monitor's webhook body as a delivery with an events array. Webhooks

Ids

Every id now starts with the kind of thing it names. The part after the _ is the same 128-bit value as the UUID it replaces, written as a TypeID (version 0.3.0): 26 characters of lowercase Crockford base32.

KindPrefixKindPrefix
company, formationcmp_monitormon_
personper_destinationdst_
rolerol_deliverydlv_
shareholdingshr_listlst_
eventevt_list itemlsi_
register entryrge_jobjob_
documentdoc_workspacewsp_
financial statementfst_

Workspace ids are the exception. workspace.id on GET /account was the app's own id (org_personal_…), not a UUID; it is now a wsp_ id derived from it one way, so it cannot be turned back into the app's id and matches nothing the app shows. If you stored or compared it, read it again from GET /account. No request takes a workspace id, so nothing else changes.

  • Until 31 December 2026 a raw UUID is still accepted wherever an id is expected, and the response carries Deprecation and Sunset. Responses always carry the prefixed id.
  • Since 17 November 2026 this includes the candidates of a 409 register_identity_ambiguous: candidates[].id is the company's cmp_ id (it was the raw UUID). Store and send that id.
  • An id of the wrong kind — a person id where a company id belongs — answers 400 validation_failed, and errors[].name names the parameter. It used to answer 404.
  • Legal forms, event types, event groups and register types are codes, not ids, and take no prefix. Some event types were renamed, and gGmbHs and gUGs have codes of their own: see Events and Non-profit GmbHs and UGs.
  • Destinations created in the app before /v1, and a few early monitors, had an id that was not a UUID. Their new dst_… or mon_… id is derived one way, so read it from GET /destinations or GET /monitors. Until 31 December 2026 the old id is still accepted in the path.

For every id that was a UUID, the conversion is lossless and needs no call to us. Any TypeID library does it; so do these few lines, which you can run over your database once:

import uuid

ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"

def to_typeid(prefix: str, raw: str) -> str:
    n = uuid.UUID(raw).int
    return prefix + "_" + "".join(ALPHABET[(n >> 5 * i) & 31] for i in reversed(range(26)))

def to_uuid(typeid: str) -> str:
    n = 0
    for ch in typeid.rpartition("_")[2]:
        n = n * 32 + ALPHABET.index(ch)
    return str(uuid.UUID(int=n))

to_typeid("cmp", stored_company_id)

Both produce the spec's test vectors for prefixed ids, which are the only kind /v1 uses. A company id and the id of its formation are the same cmp_… id.

Pagination

Every list and every search now answers one envelope, and pages forward with one cursor.

BeforeNow
"object": "list" (lists), "object": "search_result" (search)"object": "page"
has_more: falsenext_cursor: null
starting_after=<last id>cursor=<next_cursor>
page=<next_page> (search and filter)cursor=<next_cursor>
ending_before (paging backwards)gone: page forwards from the start
total_count (search)unchanged
availability on a page of shareholdersextract (see Shareholdings)
the old { "object": "list", "has_more" } answer, kept last by the reference-data lists (/legal-forms, /courts, /role-types, /industries, /event-types, /event-groups)gone: they answer the page envelope above and page with limit and cursor like every other list — and with no limit sent, the whole list still arrives in one page, next_cursor null, as before the switch
def every_item(session, url, **params):
    cursor = None
    while True:
        page = session.get(url, params={**params, "limit": 100,
                                        **({"cursor": cursor} if cursor else {})}).json()
        yield from page["data"]
        cursor = page["next_cursor"]
        if cursor is None:
            return

A cursor belongs to the list and the filters it came from. Sent with another list or other filters, it answers 400 validation_failed. See Pagination.

Paths

BeforeNowThe old path answers
GET /companies/{id}/officersGET /companies/{company_id}/roles410
GET /persons/{id}/positionsGET /persons/{person_id}/roles (offices) and GET /persons/{person_id}/holdings (interests)410
GET /companies/{id}/shareholders?depth=nGET /companies/{company_id}/ownership-tree?depth=n; /shareholders lists direct holders only400 for depth
GET /company-eventsGET /eventsthe same answer as /events (with officer_role and q for role_type and name), with Deprecation and Sunset, until 31 Dec 2026
GET /company-events/{id}GET /events/{event_id}the same answer as /events/{event_id}, with Deprecation and Sunset, until 31 Dec 2026
GET /alertsGET /events?monitor_id= (what a monitor matched) and GET /deliveries (what was sent where)410
GET /monitor-event-typesGET /event-types and GET /event-groups410
/notification-endpoints, /notification-endpoints/{id}/destinations, /destinations/{destination_id}410
/collections, /collections/{id}/lists, /lists/{list_id}410
/collections/{id}/items, /collections/{id}/items/{item_id}/lists/{list_id}/items, /lists/{list_id}/items/{item_id}410

GET /companies/{company_id}/events stays: it is GET /events?subject_id= for one company.

The contact paths and the by-id reads of documents and financial statements left the reference without a successor. Jobs left too, and are served again since 5 November 2026: POST /jobs.

Parameters

WhereBeforeNow
/search/companies, /search/persons, /search/suggestions, /formationsqname (q until 31 Dec 2026)
/company-events → /eventsqname (/company-events keeps q until it goes, on 31 Dec 2026)
every liststarting_after, ending_beforecursor (the old two answer 400)
search, POST /search/companies/filterpagecursor
GET /companies/{company_id}expand=officersexpand=roles
GET /persons/{person_id}expand=positionsexpand=roles
/eventsofficer_rolerole_type
/events—subject_id, monitor_id (new; with monitor_id the read is free)
/companies/{company_id}/shareholdersdepthmoved to /ownership-tree
GET /companies/{id}/officers → GET /companies/{company_id}/rolesrolerole_type
GET /persons/{person_id}/roles—role_type (new)
POST /search/companies/filtershareholders criteria, owner_typeholder_type (person or company, unchanged values)
POST /search/companies/filterofficers criteria, with roleroles criteria, with role_type
POST /monitorscompany_idsubject_id (company_id answers 400, with no alias)
POST /monitorscompany: {register_court, register_type, register_number}register: {court, type, number}
POST /notification-endpoints → POST /destinationsdestinationaddress
POST /collections/{id}/items → POST /lists/{list_id}/itemsentity: {object, id}subject_id

Sending q and name together answers 400 validation_failed naming q: send one.

An array parameter repeats its name: type=company.name.changed&type=company.address.changed. A comma-joined value is refused with 400 validation_failed.

Objects and fields

References to a company or person

Five shapes — CompanyRef, PersonRef, EntityRef, EntityIdentifier and the NaturalPersonParty / LegalEntityParty pair — are now one, party:

{ "object": "company", "id": "cmp_01h455vb4pex5vsknk084sn02q", "name": "Beispiel Analytics GmbH" }
BeforeNow
type: "person" / type: "company" on a partyobject
person.id, company.id nested in a partyid (null when the holder could not be matched to a record)
birth date, city and country on a partya role carries the entry's birth date and city in holder_as_registered; the person's record is GET /persons/{person_id}
register number and city of an unmatched company holderdropped
match_confidence on a partyon the role or shareholding that contains it
ObjectBeforeNow
companyofficers (with expand=officers)roles
companycounts.current_officerscounts.current_roles
search hitobject: "company_summary"object: "summary", type: "company"
search hitobject: "person_summary"object: "summary", type: "person"
search hitcityaddress.city

Apart from object (summary) and type, every field a summary has, the record has, at the same path. One difference: a company summary's registration_date is always null today, so read it on the record.

Non-profit GmbHs and UGs

A non-profit GmbH or UG is a form of its own: legal_form: "gmbh" became "ggmbh" for a gGmbH and "ug" became "gug" for a gUG (GET /legal-forms lists both). A filter that named gmbh or ug no longer returns them — ask for both codes to keep the old set.

BeforeNow
legal_formgmbh (a gGmbH)ggmbh
legal_formug (a gUG)gug
legal_form filter["gmbh"]["gmbh", "ggmbh"]
legal_form filter["ug"]["ug", "gug"]

Roles

officer (a company's officers) and person_position (a person's positions) are one object, role, listed from both sides. A person's shareholdings and Kommanditist interests are no longer positions: they are shareholding objects at /persons/{person_id}/holdings.

BeforeNow
object: "officer", object: "person_position"object: "role"
company_id (officer), company (position)company (a party)
appointeeholder (a party)
role (officer), officer_role (position)type
role_as_registeredtype_as_registered
type: "shareholder", type: "limited_partner" (position)a shareholding at /persons/{person_id}/holdings
appointee.match_confidencematch_confidence

Shareholdings

BeforeNow
ownerholder (a party)
company (CompanyRef)company (a party)
source.document_id, source.document_datesource.id, source.date, with source.object: "document"
ownership_entry wrapping each shareholding when depth > 1/ownership-tree: {object: "ownership_tree", company, nodes: [{shareholding, depth, effective_percentage, via_shareholding_id}]}
page field availabilitypage field extract: {status, fetched_at, document_id}
availability: "available"extract.status: "parsed"
availability: "processing"extract.status: "processing"
availability: "not_filed"extract.status: "not_filed"

Events

BeforeNow
object: "company_event"object: "event"
company_id, companysubject (a party)
previous, currentdata.previous, data.current for a *.changed type, typed like the field they change
officer_role, officersdata.holder (a party) and data.role_type for a company.role.* type
register_entry_numbersource: {object: "register_entry", id, number, published_on, text}, or null when the entry's number is not known (a shareholder-list or accounts event names its document instead)

data is shaped by type; GET /event-types lists every type and its English and German label.

An old name answers 400 naming the new one where it was used: company.officer.appointed, company.officer.removed and company.shareholder.changed in a monitor's event_types; the three company.officer.* names and company.shareholders.changed in the type filter on /events.

BeforeNow
company.officer.appointedcompany.role.added
company.officer.changedcompany.role.changed
company.officer.removedcompany.role.removed
company.shareholder.changed (monitor type; renamed earlier in October 2026)company.shareholding.changed
company.shareholders.changed (event type; renamed earlier in October 2026)company.shareholder_list.changed

A company.role.* event names the actual role in its data.role_type (managing_director, authorized_signatory, …); the type's label is generic (Funktion eingetragen).

Monitors, destinations and deliveries

BeforeNow
monitor.companymonitor.subject (a party)
object: "notification_endpoint"object: "destination"
destination (the address or URL)address
—cadence: instant, daily, weekly or monthly; digests go out at 07:00 in your workspace's time zone (Europe/Berlin unless you changed it)
channel: email or webhookchannel: email, webhook or slack (new: a Slack incoming-webhook URL as address)
object: "alert"gone: the event is an event (GET /events?monitor_id=, free like /alerts was), and whether it was sent is a delivery (GET /deliveries)
alert.notifieddelivery.status: pending, sent or failed
alert.label, alert.label_delabel, label_de on GET /event-types
object: "monitor_event_type", unavailable_groupsevent_type (GET /event-types) and event_group (GET /event-groups)

A deleted destination answers {object: "destination", id, deleted: true}.

Lists

BeforeNow
object: "collection"object: "list"
object: "collection_item"object: "list_item"
collection_idlist_id
entitysubject (a party)

To add an item, send subject_id: a cmp_… or per_… id, whose prefix says which kind it is. Until 31 December 2026 a raw UUID is still accepted there: it is looked up as a company first, then as a person, and the response carries Deprecation and Sunset. An id of another kind (mon_…) answers 400 validation_failed naming subject_id. Deleting a list or an item answers {object: "list", id, deleted: true} or {object: "list_item", id, deleted: true}.

Persons

BeforeNow
positions (with expand=positions)roles (with expand=roles)
city, countryaddress.city, address.country

Jobs

One change of 19 November 2026 breaks a client that reads lookup jobs. The changelog has the rest.

BeforeNow
A lookup that found several companies: result.candidates and result.candidates_truncated on a failed joblookup.candidates and lookup.candidates_has_more; result is null unless the job succeeded
A candidate: flat name, register_court, register_type, register_number, city, status, subject_idA candidate is {object: "company", id, name, register, city, status, subject_lookup}: id is the company id when we hold it (null if not), register is {court: {code, name}, type, number, formatted, country}, and subject_lookup is what to send to POST /jobs for this company (exact when its court is in our court directory; otherwise name, register type and city, which can match several companies)

Every job now carries lookup: null for a job started with a company id, else {outcome, candidates, candidates_has_more} with outcome one of pending, matched, not_found or ambiguous. The failure code is still company_ambiguous or company_not_found. Every job carries subject_lookup (null for a company-id job), also one stored before this date.

GET /jobs and GET /jobs/{job_id} show a job the same way, result.company included. To follow an ambiguous lookup, read lookup.candidates, pick one, and send its subject_lookup (or, when its id is set, subject_id) in a new POST /jobs.

Account

BeforeNow
workspace.id: the app's id (org_personal_…)wsp_…, derived from it one way (see Ids)

Webhooks

A monitor's webhook body was an event wrapping one alert. It is now a delivery holding its events. A webhook destination is always instant, so that is one event (e-mail and Slack digests are deliveries with several); read events as an array anyway. A job's webhook (job.succeeded, job.failed, job.canceled) has its own body; see Webhooks.

{
  "object": "delivery",
  "id": "dlv_01h455vb4pex5vsknk084sn02q",
  "destination_id": "dst_01h455vb4pex5vsknk084sn02r",
  "cadence": "instant",
  "status": "pending",
  "attempt_count": 0,
  "events": [
    {
      "object": "event",
      "id": "evt_01h455vb4pex5vsknk084sn02s",
      "type": "company.registered_office.changed",
      "subject": { "object": "company", "id": "cmp_01h455vb4pex5vsknk084sn02t", "name": "Beispiel Analytics GmbH" },
      "data": { "previous": "Strehla", "current": "Roskow" },
      "source": null,
      "effective_date": "2026-09-21",
      "created_at": "2026-10-20T13:20:15Z"
    }
  ],
  "created_at": "2026-10-20T13:20:17Z",
  "sent_at": null,
  "test": false
}
BeforeNow
object: "event" (the envelope)object: "delivery"
id (the envelope; also svix-id)id, a dlv_… id; still the svix-id, still the key to deduplicate on
typeeach event's type
data.object (one alert)events (one or more events)
data.object.monitor_idthe events a monitor matched: GET /events?monitor_id=

Signing is unchanged: the same headers and the same secret. A retry that was already queued at the release goes out in the new shape. See Webhooks.

Errors

BeforeNow
400 invalid_request for a field that fails validation400 validation_failed, with errors: [{location, name, detail}] naming each field. Monitors, destinations and expand still answer invalid_request, with the field in detail.
400 invalid_requesta body that cannot be parsed, a monitor's or a destination's field, and an expand value that cannot be expanded
404 for an id of the wrong kind400 validation_failed
a renamed path: 404410 endpoint_retired, detail naming the new path

See Errors.

Credits

The October renaming changed no price (later price changes are in the changelog), and reading what your own monitor matched (GET /events?monitor_id=) stays free, as /alerts was. Registercheck-Credits-Charged is now on every response to a call with a key, 0 when nothing was charged; Registercheck-Credits-Remaining comes whenever the call read your balance. See Credits and billing.

On this page