Skip to main content
POST
/
v1
/
transparenzregister
/
extracts
JavaScript
import Openregister from 'openregister';

const client = new Openregister({
  apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});

const transparenzregisterExtract = await client.transparenzregister.extract.createV1();

console.log(transparenzregisterExtract.id);
{
  "id": "<string>",
  "status": "completed",
  "company_id": "<string>",
  "ekrn": "<string>",
  "reference_number": "<string>",
  "submitted_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "report": {
    "created_at": "2023-12-25",
    "notice_type": "<string>",
    "validity": {
      "from": {
        "date": "2023-12-25",
        "note": "<string>"
      },
      "until": {
        "date": "2023-12-25",
        "note": "<string>"
      }
    },
    "status_flags": {
      "deleted": true,
      "deletion_date": "2023-12-25",
      "discrepancy_note": "<string>",
      "corrected_references": [
        "<string>"
      ],
      "corrected_by_reference": "<string>"
    },
    "groups": [
      {
        "position": 123,
        "interest_type": "<string>",
        "description": "<string>"
      }
    ],
    "ubos": [
      {
        "position": 123,
        "natural_person": {
          "title": "<string>",
          "first_name": "<string>",
          "last_name": "<string>",
          "full_name": "<string>",
          "date_of_birth": "2023-12-25",
          "nationalities": [
            "<string>"
          ],
          "city": "<string>",
          "country": "<string>"
        },
        "interest": {
          "type": "<string>",
          "scope": "<string>",
          "percentage": 123
        }
      }
    ],
    "fictional_ubo_reason": "<string>"
  },
  "documents": [
    {
      "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "format": "<string>",
      "filename": "<string>"
    }
  ]
}

​
Order a Transparenzregister extract

Places an order for a Transparenzregister extract and returns a TransparenzregisterExtract resource with processing status. Use the returned id as the polling handle. The typical flow is:
  1. Store your credentials with the credentials endpoint
  2. Order an extract here with company_id (production) or sandbox mode (see below)
  3. Poll the get extract endpoint with the returned id until status is completed or failed
At the Transparenzregister (EiS), requests are asynchronous: search → submit request → order documents → download. OpenRegister coordinates that workflow internally; you only poll until status leaves processing.

​
Sandbox mode (integration testing)

Send header X-Credential-Name: sandbox and omit company_id (an empty body {} is valid). OpenRegister uses the EiS test environment at https://test2.api.transparenzregister.de with the built-in test user testnutzer-eis@transparenzregister.de. The request uses the fixed test EKRN DE727032388716; the response has company_id: null. Cost: 0 credits.

​
Production mode

Always set X-Credential-Name — use default or another stored credential name you use in production. company_id is required and must resolve to exactly one Transparenzregister legal entity.

​
Error cases

StatusCause
400Invalid parameters (e.g. reserved credential name where not allowed, invalid company_id)
401Authentication required
403Transparenzregister rejected authentication for the selected credential mode, or Transparenzregister access is not enabled for this account (EiS: account not unlocked, identification incomplete, or account locked)
404Company not found, credentials not found, or no Transparenzregister match for the company (EiS: 404 Not Found for bad parameters)
409Multiple Transparenzregister companies matched — request cannot be disambiguated
429 / upstreamRate limiting
500Internal server error
Cost: 25 credits (0 credits when X-Credential-Name: sandbox)

​
Notes

  • The returned id (e.g. tre_12345678) is stable — store it to retrieve the extract later.

Authorizations

​
Authorization
string
header
required

API Key Authentication Provide your API key as a Bearer token in the Authorization header.

Headers

​
X-Credential-Name
string
default:default

Name identifying which credentials to use. Always send this header in production (typically default or another stored name). Reserved values:

  • default: use persisted default credentials for the current user.
  • sandbox: use OpenRegister's built-in Transparenzregister test client, test authentication, and fixed test EKRN. Any other value selects persisted credentials with the same name for the current user. Example: "client_a"

Body

application/json

Request body for creating a Transparenzregister extract.

​
company_id
string

Unique company identifier. Required unless X-Credential-Name is set to sandbox. In sandbox mode this field should be omitted. Example: DE-HRB-F1103-267645

Response

Extract request submitted successfully

Transparenzregister extract resource including processing state, parsed report, and downloadable documents.

​
id
string
required

Stable extract identifier. Example: "tre_12345678"

​
status
enum<string>
required

Status of the Transparenzregister extract.

Available options:
completed,
processing,
failed
​
company_id
string | null

Company identifier associated with this extract request. May be null when using sandbox credentials.

​
ekrn
string | null

EKRN used to request this extract.

​
reference_number
string | null

Transparenzregister reference number from the extract.

​
submitted_at
string<date-time>

Timestamp when extract submission started.

​
completed_at
string<date-time> | null

Timestamp when extract processing completed.

​
report
object

Parsed Transparenzregister extract report limited to UBO-relevant fields.

​
documents
object[]

URLs for downloading available extract documents.