Order a Transparenzregister extract
Ask the Transparenzregister for the current extract of a company with your own register account, and read its beneficial owners and files.
The Transparenzregister holds the beneficial owners (wirtschaftlich Berechtigte) that companies and other legal persons report under the GwG. Its EiS interface hands an official extract to a registered user who may retrieve it under § 23 Abs. 3 GwG. This API orders that extract for you, with your own Transparenzregister account, and gives you the register's PDF, its JSON and, when the register draws one, the ownership chart.
The extract is the register's own record. It is not the computed beneficial owners, which Registercheck derives from shareholder lists, and it is not stored in a company's data here. It belongs to your workspace.
What it costs
| What | Price |
|---|---|
| An extract | 25 credits, charged only when the extract succeeds. The credits are debited when the extract is accepted and given back in full when it ends failed or canceled. A test extract costs the same 25 credits. |
| The register's own fee | 1,65 EUR for each retrieved document, billed by the Transparenzregister to your own Transparenzregister account. Registercheck neither collects nor passes it on. It applies to live connections only: the test environment uses the register's published test account and bills nothing. |
| Connections, reading and listing extracts, files, cancel, redact | Free. |
How it works
- Store your register login as a connection (
POST /connections). - Order an extract with it (
POST /transparency-register/extracts). The register decides each access request, which can take until its next working hours, so an extract can staypendingovernight. Registercheck checks a pending extract every 15 minutes on weekdays from 7:00 to 19:00 Berlin time and hourly otherwise, and gives up after seven days withregister_timeout. - Read the extract, poll it or wait for the webhook until it is
succeeded, then download its files. - Redact it when you no longer need it. Its data and files are deleted 30 days after it ended in any case.
An extract is in one of five statuses: queued (accepted, not yet asked), pending (the register has not decided),
succeeded, failed and canceled. The last three are final.
Connections
A connection is a stored login of a register account your workspace uses. A workspace can hold several, for example one
per client of yours; give each a label and metadata to tell them apart. Only a workspace administrator
may create, change or delete one.
A live connection
A live connection holds the e-mail and the password of your own Transparenzregister account. The account must be
cleared by the register for API retrieval; otherwise an extract fails with account_not_cleared.
curl -X POST "https://api.registercheck.de/v1/connections" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "transparency_register",
"environment": "live",
"credentials": {"email": "compliance@example.de", "password": "an-example-password"},
"label": "Kunde A",
"metadata": {"client_id": "k-1042"}
}'The answer is 201 with the connection:
{
"id": "conn_01k6hb7xq0fm8a4q2t7bw9c5ve",
"object": "connection",
"provider": "transparency_register",
"environment": "live",
"status": "verified",
"error": null,
"account": {"email_masked": "c***@example.de"},
"label": "Kunde A",
"metadata": {"client_id": "k-1042"},
"created_at": "2026-11-17T09:58:12Z",
"updated_at": "2026-11-17T09:58:12Z",
"last_verified_at": "2026-11-17T09:58:12Z"
}The password is encrypted, written once and never returned; the e-mail is returned masked. The register is asked once
whether it logs the account in, and status says how it answered: verified, unverified (the register could not be
asked) or refused. A refused login is stored all the same, with its error. Replace it with
PATCH /connections/{connection_id} and new credentials, which are checked again. At most five live logins an hour
are checked for a workspace; past that the call answers 429 and stores nothing.
No Idempotency-Key is stored or replayed on a connection, because its body is a password.
The test connection
A test connection holds no login. It uses the register's published test account and its test system, takes no
credentials, and bills nothing at the register. The environment belongs to the connection, so an extract ordered with
it runs in the test system. The test system holds none of our companies, so order by ekrn.
curl -X POST "https://api.registercheck.de/v1/connections" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider": "transparency_register", "environment": "test", "label": "Sandbox"}'List, change, delete
curl "https://api.registercheck.de/v1/connections?environment=live" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"
curl -X PATCH "https://api.registercheck.de/v1/connections/conn_01k6hb7xq0fm8a4q2t7bw9c5ve" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "Kunde A (neu)", "metadata": {"client_id": null}}'
curl -X DELETE "https://api.registercheck.de/v1/connections/conn_01k6hb7xq0fm8a4q2t7bw9c5ve" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"A PATCH changes only the fields it names. metadata merges and null removes a key, and label: null clears the
label. A test connection takes no credentials. Deleting a connection wipes its login. Extracts that name it keep the
reference, and extracts still open on it fail with login_refused and are refunded.
Order an extract
Name the subject by exactly one of ekrn (the register's number of the legal person, DE and twelve digits) or company (one of
our companies, looked up by its register court, type and number). Name the connection in connection. Without it the
workspace's only live connection is used: none answers 409 transparency_register_not_connected, and several answer
400 validation_failed. Send include_real_estate: true to ask for the real estate the register records.
Without Prefer: answer at once, then poll
curl -X POST "https://api.registercheck.de/v1/transparency-register/extracts" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: kyb-2026-118204-trx" \
-d '{
"ekrn": "DE727032388716",
"connection": "conn_01k6hb7xq0fm8a4q2t7bw9c5ve",
"metadata": {"case_id": "KYB-2026-118204"}
}'The answer is 202 at once, with Location and Retry-After (seconds):
{
"id": "trx_01k6hb8z0yfmx9y02bhrp1tpkf",
"object": "transparency_register.extract",
"environment": "live",
"status": "pending",
"connection": "conn_01k6hb7xq0fm8a4q2t7bw9c5ve",
"subject": {"ekrn": "DE727032388716", "company_id": null},
"include_real_estate": false,
"failure": null,
"extract": null,
"files": [],
"credits": {"charged": 25, "refunded": 0},
"metadata": {"case_id": "KYB-2026-118204"},
"created_at": "2026-11-17T10:00:02Z",
"completed_at": null,
"expires_at": null,
"redacted": false,
"redacted_at": null,
"redaction": null
}Read it at Location after Retry-After seconds, and again until status is final. Reading an extract is free.
curl "https://api.registercheck.de/v1/transparency-register/extracts/trx_01k6hb8z0yfmx9y02bhrp1tpkf" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"With Prefer: wait=N: wait for the register
Prefer: wait=55 (RFC 7240) makes the call wait up to that many seconds for
the register. The most it waits is 55 seconds, and a larger N is read as 55.
curl -X POST "https://api.registercheck.de/v1/transparency-register/extracts" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: wait=55" \
-d '{"ekrn": "DE727032388716", "connection": "conn_01k6hb7xq0fm8a4q2t7bw9c5ve"}'- If the extract ended in that time, the answer is
200withPreference-Applied: wait=55and the extract. - If it is still open, the answer is
202withLocationandRetry-After, exactly as withoutPrefer. The extract carries on in the background; read it, cancel it or wait for its webhook.
A request that waits is not cancelled when your client stops waiting. Do not send the same order again: it answers
409 transparency_register_extract_in_progress, naming the open extract in existing_id. Send an Idempotency-Key to
repeat a call safely.
One open extract per subject and connection
While an extract of the same subject (the same ekrn or the same company) is open on a connection, another order of it
with that connection answers 409 transparency_register_extract_in_progress, with the open extract in existing_id,
and charges nothing. Two connections, for example two end clients of yours, can each have an extract of the same
company open.
The extract
When it has succeeded, extract holds the register's record in our words: the legal person, the validity of the
entry, the beneficial_owners with name, birth date, residence, nationalities and the kind and extent of the interest,
the groups of beneficiaries, a fictitious beneficial owner when the register names one, and the real estate when you
asked for it. Every key is always present; what the register left out is null or an empty list, and register texts
stay in German beside their reading (as_registered). Names, birth dates and residences are personal data. Handle them
as such.
GET /transparency-register/extracts
lists your workspace's extracts, newest first, and filters by status, connection, ekrn and company.
Files
A succeeded extract lists its files: pdf, json and, when the register draws one, ownership_chart (SVG). Each is an
object with an id of its own (file_…), its content_type, size, sha256 and the url to download it.
curl "https://api.registercheck.de/v1/files/file_01k6hb9d3sf4a7c1v9x3z5b8dg" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"
curl "https://api.registercheck.de/v1/files/file_01k6hb9d3sf4a7c1v9x3z5b8dg/content" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-o extract.pdf/files/{file_id} answers the file's metadata and /files/{file_id}/content its bytes, as the register handed them out,
with their own content type and Cache-Control: private, no-store. Both are free. Compare the bytes with sha256. A file
belongs to your workspace; the id of another workspace's file answers 404. Files are kept 30 days after the extract
ended (expires_at). After that, or once the extract is redacted, both answer 404.
Cancel
curl -X POST "https://api.registercheck.de/v1/transparency-register/extracts/trx_01k6hb8z0yfmx9y02bhrp1tpkf/cancel" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"Only a queued or pending extract can be canceled. It becomes canceled, its 25 credits are refunded
(credits.refunded is 25) and the canceled webhook is sent. The register has no cancel: nothing is sent to it, and
what it decides about the access request afterwards is ignored. An extract in any other status answers 409 conflict.
The call is free.
Redact
curl -X POST "https://api.registercheck.de/v1/transparency-register/extracts/trx_01k6hb8z0yfmx9y02bhrp1tpkf/redact" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY"Only a final extract can be redacted; an open one answers 409 conflict. Redacting deletes its extract data (the
beneficial owners as parsed) and its files now. The extract keeps its id, status, subject, credits and times, with
redacted: true, redacted_at and redaction.reason requested. Redacting again changes nothing. The same happens by
itself 30 days after the extract ended, with redaction.reason expired. The call is free.
Webhooks
A webhook destination whose enabled_events lists transparency_register.extract.succeeded,
transparency_register.extract.failed or transparency_register.extract.canceled is sent a request when an extract of
your workspace ends that way. Set the events with
PATCH /destinations/{destination_id}. The body names the extract
and where to read it, and carries no personal data:
{
"type": "transparency_register.extract.succeeded",
"timestamp": "2026-11-17T10:00:44Z",
"data": {
"object": "transparency_register.extract",
"id": "trx_01k6hb8z0yfmx9y02bhrp1tpkf",
"url": "https://api.registercheck.de/v1/transparency-register/extracts/trx_01k6hb8z0yfmx9y02bhrp1tpkf"
}
}It is signed like every other delivery, with svix-id, svix-timestamp and svix-signature; svix-id is the same on
every retry, so deduplicate on it. Webhooks shows how to verify the signature. Read the extract
with GET /transparency-register/extracts/{extract_id}.
Errors
Every refusal below charges nothing. The errors page has the full list.
| Status | code | When | What to do |
|---|---|---|---|
409 | transparency_register_not_connected | No connection was named and the workspace has no live connection. | Create one, or name a connection. |
409 | transparency_register_login_refused | The register refused the connection's login. | PATCH /connections/{connection_id} with new credentials. |
409 | transparency_register_extract_in_progress | An extract of this subject is already open on this connection. existing_id names it. | Read that extract. |
422 | transparency_register_company_not_resolvable | We do not hold the company's register court, type or number. | Name its ekrn. |
503 | transparency_register_unavailable | Extracts cannot be requested right now. Retry-After is 300 seconds. | Retry after that. |
409 | conflict | Cancel of an extract that is not queued or pending, or redact of one that is still open. | Read the extract's status. |
More refusals are 400 validation_failed: several live connections and no connection, a company with a test
connection, both or neither of ekrn and company. A call without the workspace role it needs answers 403 forbidden.
A connection or an extract of another workspace answers 404 not_found.
An extract that was accepted and then fails is failed, with a failure that has a code and a message, and is
refunded: login_refused, account_not_cleared, no_current_extract, register_error, register_unavailable,
register_timeout, manufacturer_key (an error on our side) and two codes for a subject the register cannot find or finds
more than once. The extract's reference page
lists them all. Branch on code.