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);
qinstead ofnameon search and onGET /formations(Parameters);GET /company-eventsandGET /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.
| Kind | Prefix | Kind | Prefix |
|---|---|---|---|
| company, formation | cmp_ | monitor | mon_ |
| person | per_ | destination | dst_ |
| role | rol_ | delivery | dlv_ |
| shareholding | shr_ | list | lst_ |
| event | evt_ | list item | lsi_ |
| register entry | rge_ | job | job_ |
| document | doc_ | workspace | wsp_ |
| financial statement | fst_ |
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
DeprecationandSunset. Responses always carry the prefixed id. - Since 17 November 2026 this includes the candidates of a
409 register_identity_ambiguous:candidates[].idis the company'scmp_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, anderrors[].namenames the parameter. It used to answer404. - 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 newdst_…ormon_…id is derived one way, so read it fromGET /destinationsorGET /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.
| Before | Now |
|---|---|
"object": "list" (lists), "object": "search_result" (search) | "object": "page" |
has_more: false | next_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 shareholders | extract (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:
returnA 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
| Before | Now | The old path answers |
|---|---|---|
GET /companies/{id}/officers | GET /companies/{company_id}/roles | 410 |
GET /persons/{id}/positions | GET /persons/{person_id}/roles (offices) and GET /persons/{person_id}/holdings (interests) | 410 |
GET /companies/{id}/shareholders?depth=n | GET /companies/{company_id}/ownership-tree?depth=n; /shareholders lists direct holders only | 400 for depth |
GET /company-events | GET /events | the 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 /alerts | GET /events?monitor_id= (what a monitor matched) and GET /deliveries (what was sent where) | 410 |
GET /monitor-event-types | GET /event-types and GET /event-groups | 410 |
/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
| Where | Before | Now |
|---|---|---|
/search/companies, /search/persons, /search/suggestions, /formations | q | name (q until 31 Dec 2026) |
/company-events → /events | q | name (/company-events keeps q until it goes, on 31 Dec 2026) |
| every list | starting_after, ending_before | cursor (the old two answer 400) |
search, POST /search/companies/filter | page | cursor |
GET /companies/{company_id} | expand=officers | expand=roles |
GET /persons/{person_id} | expand=positions | expand=roles |
/events | officer_role | role_type |
/events | — | subject_id, monitor_id (new; with monitor_id the read is free) |
/companies/{company_id}/shareholders | depth | moved to /ownership-tree |
GET /companies/{id}/officers → GET /companies/{company_id}/roles | role | role_type |
GET /persons/{person_id}/roles | — | role_type (new) |
POST /search/companies/filter | shareholders criteria, owner_type | holder_type (person or company, unchanged values) |
POST /search/companies/filter | officers criteria, with role | roles criteria, with role_type |
POST /monitors | company_id | subject_id (company_id answers 400, with no alias) |
POST /monitors | company: {register_court, register_type, register_number} | register: {court, type, number} |
POST /notification-endpoints → POST /destinations | destination | address |
POST /collections/{id}/items → POST /lists/{list_id}/items | entity: {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" }| Before | Now |
|---|---|
type: "person" / type: "company" on a party | object |
person.id, company.id nested in a party | id (null when the holder could not be matched to a record) |
| birth date, city and country on a party | a 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 holder | dropped |
match_confidence on a party | on the role or shareholding that contains it |
Companies and search
| Object | Before | Now |
|---|---|---|
company | officers (with expand=officers) | roles |
company | counts.current_officers | counts.current_roles |
| search hit | object: "company_summary" | object: "summary", type: "company" |
| search hit | object: "person_summary" | object: "summary", type: "person" |
| search hit | city | address.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.
| Before | Now | |
|---|---|---|
legal_form | gmbh (a gGmbH) | ggmbh |
legal_form | ug (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.
| Before | Now |
|---|---|
object: "officer", object: "person_position" | object: "role" |
company_id (officer), company (position) | company (a party) |
appointee | holder (a party) |
role (officer), officer_role (position) | type |
role_as_registered | type_as_registered |
type: "shareholder", type: "limited_partner" (position) | a shareholding at /persons/{person_id}/holdings |
appointee.match_confidence | match_confidence |
Shareholdings
| Before | Now |
|---|---|
owner | holder (a party) |
company (CompanyRef) | company (a party) |
source.document_id, source.document_date | source.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 availability | page 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
| Before | Now |
|---|---|
object: "company_event" | object: "event" |
company_id, company | subject (a party) |
previous, current | data.previous, data.current for a *.changed type, typed like the field they change |
officer_role, officers | data.holder (a party) and data.role_type for a company.role.* type |
register_entry_number | source: {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.
| Before | Now |
|---|---|
company.officer.appointed | company.role.added |
company.officer.changed | company.role.changed |
company.officer.removed | company.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
| Before | Now |
|---|---|
monitor.company | monitor.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 webhook | channel: 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.notified | delivery.status: pending, sent or failed |
alert.label, alert.label_de | label, label_de on GET /event-types |
object: "monitor_event_type", unavailable_groups | event_type (GET /event-types) and event_group (GET /event-groups) |
A deleted destination answers {object: "destination", id, deleted: true}.
Lists
| Before | Now |
|---|---|
object: "collection" | object: "list" |
object: "collection_item" | object: "list_item" |
collection_id | list_id |
entity | subject (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
| Before | Now |
|---|---|
positions (with expand=positions) | roles (with expand=roles) |
city, country | address.city, address.country |
Jobs
One change of 19 November 2026 breaks a client that reads lookup jobs. The changelog has the rest.
| Before | Now |
|---|---|
A lookup that found several companies: result.candidates and result.candidates_truncated on a failed job | lookup.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_id | A 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
| Before | Now |
|---|---|
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
}| Before | Now |
|---|---|
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 |
type | each event's type |
data.object (one alert) | events (one or more events) |
data.object.monitor_id | the 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
| Before | Now |
|---|---|
400 invalid_request for a field that fails validation | 400 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_request | a 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 kind | 400 validation_failed |
a renamed path: 404 | 410 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.