Order extract

POST /v1/transparenzregister/extracts

JavaScript

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);

201

{
  "id": "<string>",
  "status": "processing",
  "company_id": "<string>",
  "ekrn": "<string>",
  "submitted_at": "2023-11-07T05:31:56Z"
}

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 [e-mail]. 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

Status	Cause
400	Invalid parameters (e.g. reserved credential name where not allowed, invalid company_id)
401	Authentication required
402	Transparenzregister API access requires a paid API plan
403	Transparenzregister rejected authentication for the selected credential mode (EiS: account not unlocked, identification incomplete, or account locked)
404	Company not found, credentials not found, or no Transparenzregister match for the company
409	Multiple Transparenzregister companies matched — request cannot be disambiguated
429	Production extract quota exceeded for the rolling 30-day window
500	Internal 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

201

application/json

Extract request submitted successfully

Response from creating a Transparenzregister extract. Only fields known at creation time are present. Poll GET /v1/transparenzregister/extracts/{extract_id} to retrieve report and documents.

id · string · required

Stable extract identifier. Use this to poll the get-extract endpoint. Example: "tre_12345678"

status · enum<string> · required

Always processing on create. Poll the get-extract endpoint for terminal state.

Available options: processing

company_id · string | null · required

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

ekrn · string | null · required

EKRN used to request this extract.

submitted_at · string<date-time> · required

Timestamp when extract submission started.