> ## Documentation Index > Fetch the complete documentation index at: https://docs.openregister.de/llms.txt > Use this file to discover all available pages before exploring further. # Get extract > Get the results of a Transparenzregister extract request. This endpoint handles all internal complexity including polling request status, selecting all available documents, creating Transparenzregister baskets, and returning download URLs when ready. If the request is still processing, it will return a pending status. Polling reuses the credential mode stored on the extract at create time. Sandbox extracts keep using the Transparenzregister test client automatically; no credential header is accepted on this endpoint. ## Get Transparenzregister extract Returns the current state of a previously ordered extract. Poll this endpoint after calling the [order extract endpoint](/api/endpoint/transparenzregister-extract-create) until `status` is `completed` or `failed`. **Recommended polling interval:** every 5–10 seconds. Most extracts complete within 5-60 seconds, but can take longer depending on Transparenzregister availability. * **`200`** — Extract retrieved; may still be `processing` or terminal `completed` / `failed` * **`202`** — Extract is still processing (same response schema as `200`) Do **not** send `X-Credential-Name` on this request. Polling reuses the credential mode stored when the extract was created; sandbox extracts keep using the Transparenzregister test client automatically. Once `status` is `completed`, results are cached — you can fetch the same `extract_id` again without re-processing or incurring additional costs. **Cost:** 0 credits ### Status values | Status | Meaning | What to do | | ------------ | ---------------------------------------------- | ------------------------------ | | `processing` | Queued or still handled by Transparenzregister | Continue polling | | `completed` | Structured report and/or documents are ready | Read `report` and `documents` | | `failed` | Extract could not be completed | Terminal — order a new extract | #### Top-level extract fields | Field | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------ | | `id` | Stable OpenRegister extract id (e.g. `tre_12345678`) | | `status` | `completed` \| `processing` \| `failed` | | `company_id` | Company identifier; `null` for sandbox extracts | | `ekrn` | 14-character Einheitliche und kontinuierliche Rechtseinheitsnummer (upstream `ekrn`) | | `reference_number` | Upstream `referenznummer` (6 characters); identifies the register extract and chains corrections | | `submitted_at` / `completed_at` | OpenRegister timestamps (not present in upstream JSON) | #### `report` — parsed register entry Derived from the JSON variant of the extract document. | API field | Upstream | Notes | | ------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `created_at` | `erstellungsdatum` | `dd.mm.jjjj` → ISO `YYYY-MM-DD` | | `notice_type` | `angabenZumAuszug.artDerMitteilung` | e.g. `Mitteilung wirtschaftlich Berechtigter nach §§ 20, 21 GwG`, `Automatische Eintragung nach § 20a GwG` | | `validity.from` / `validity.until` | `gueltigVonDatum` / `gueltigVonSonstiges`, `gueltigBisDatum` / `gueltigBisSonstiges` | Each side has `date` and/or `note` (e.g. `Unbekannt`, `vor dem 01.10.2017`, `bis auf Weiteres`) | | `status_flags.deleted` | `loeschkennzeichen` | | | `status_flags.deletion_date` | `loeschdatum` | Only when entity is deleted | | `status_flags.discrepancy_note` | `vermerkUnstimmigkeitsmeldung` | e.g. ongoing § 23a GwG review, or completed on a date | | `status_flags.corrected_references` | `berichtigt` | List of 6-char reference numbers this extract corrects | | `status_flags.corrected_by_reference` | `wirdBerichtigtDurch` | Reference of a later extract that corrects this one (see EiS § 8) | | `groups[].position` | `gruppen[].position` | | | `groups[].interest_type` | `gruppen[].wirtschaftlichesInteresseGruppe` | Often the § 3 Abs. 3 Nr. 4 GwG group-of-beneficiaries case | | `groups[].description` | `gruppen[].beschreibungGruppe` | Free text (up to 10 000 chars upstream) | | `ubos[].position` | `wirtschaftlichBerechtigte[].position` | | | `ubos[].natural_person.title` | `titel` | e.g. `Dr.` / `Prof.` — not a job title | | `ubos[].natural_person.first_name` / `last_name` | `vorname` / `nachname` | As on ID document | | `ubos[].natural_person.full_name` | — | Derived (space-joined first + last) | | `ubos[].natural_person.date_of_birth` | `geburtsdatum` | ISO date | | `ubos[].natural_person.nationalities` | `staatsangehoerigkeit` | Mapped toward ISO 3166-1 alpha-2 where known (`Deutschland`→`DE`, `Österreich`→`AT`, `Schweiz`→`CH`; 2-letter codes uppercased) | | `ubos[].natural_person.city` | `wohnort` | Primary residence | | `ubos[].natural_person.country` | `wohnSitzLand` | Same country mapping as nationalities | | `ubos[].interest.type` | `wirtschaftlichesInteresseArt` | Legal category (capital, voting rights, control, trust roles, foundation, etc. — see EiS § 7.1 enumeration) | | `ubos[].interest.scope` | `wirtschaftlichesInteresseUmfang` | Free text (up to 10 000 chars) | | `ubos[].interest.percentage` | — | **Derived:** best-effort parse of a percentage from `scope` text (regex); `null` if none found — not authoritative | | `fictional_ubo_reason` | `grundFiktiveWb` | When no natural-person UBO per § 3 GwG could be determined (enumerated upstream strings) | #### `ubos[].interest.type` — enumeration Values are the full German strings returned by the register, including legal references. Examples include: * `Beteiligung an der Vereinigung selbst, insbesondere der Höhe der Kapitalanteile (§ 19 Abs. 3 Nr. 1a GwG)` * `Beteiligung an der Vereinigung selbst, insbesondere der Stimmrechte (§ 19 Abs. 3 Nr. 1a GwG)` * `Ausübung von Kontrolle auf sonstige Weise (§ 19 Abs. 3 Nr. 1b GwG)` * `Treugeber (Settlor), Trustee oder Protektor (§ 3 Abs. 3 Nr. 1 GwG)` * `Mitglied des Vorstands der Stiftung (§ 3 Abs. 3 Nr. 2 GwG)` * `Begünstigter (§ 3 Abs. 3 Nr. 3 GwG)` * `Person mit sonstigem beherrschendem Einfluss auf Vermögensverwaltung / Ertragsverteilung (§ 3 Abs. 3 Nr. 5 GwG)` * `Sonstige Funktion des gesetzlichen Vertreters (§ 19 Abs. 3 Nr. 1c GwG)` * `Funktion des geschäftsführenden Gesellschafters oder Partners (§ 19 Abs. 3 Nr. 1c GwG)` * `Person mit beherrschendem Einfluss nach § 3 Abs. 3 Nr. 6 GwG` * `Funktion des gesetzlichen Vertreters, geschäftsführenden Gesellschafters oder Partners (§ 19 Abs. 3 Nr. 1c GwG)` * `Person mit beherrschendem Einfluss auf eine Vereinigung, die Mitglied des Vorstands der Stiftung ist oder die als Begünstigte der Stiftung bestimmt worden ist (§ 3 Abs. 3 Nr. 6a GwG)` * `Person mit beherrschendem Einfluss auf eine Vereinigung, die als Treugeber (Settlor), Verwalter von Trusts (Trustee) oder Protektor handelt oder die als Begünstigte der Rechtseinheit bestimmt worden ist (§ 3 Abs. 3 Nr. 6b GwG)` #### `fictional_ubo_reason` — upstream `grundFiktiveWb` When set, typical values include: * `Es wurde keine natürliche Person ermittelt, die die Voraussetzungen eines wirtschaftlich Berechtigten nach § 3 Abs. 1 oder Abs. 2 S. 1 - 4 GwG erfüllt.` * `Die Ermittlung eines wirtschaftlich Berechtigten nach § 3 Abs. 1 oder Abs. 2 S. 1 - 4 GwG war nach Durchführung umfassender Prüfungen nicht möglich.` * `keine Angabe` #### `documents[]` | Field | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `document_id` | Stable UUID for this document | | `url` | Short-lived download URL | | `format` | e.g. `pdf` (human-readable extract), `json` (structured extract feeding `report`), `svg` (Eigentums- und Kontrollstrukturübersicht when present — EiS § 9), `xml` when returned by TR | | `filename` | Suggested filename | ## OpenAPI ````yaml GET /v1/transparenzregister/extracts/{extract_id} openapi: 3.1.0 info: title: OpenRegister API version: 2.0.0 description: > API for accessing comprehensive company data from official registers. This API provides access to company information, shareholder data, financial reports, and contact details. servers: - url: https://api.openregister.de description: Production security: - BearerAuth: [] paths: /v1/transparenzregister/extracts/{extract_id}: get: tags: - v1 summary: Get Transparenzregister extract description: > Get the results of a Transparenzregister extract request. This endpoint handles all internal complexity including polling request status, selecting all available documents, creating Transparenzregister baskets, and returning download URLs when ready. If the request is still processing, it will return a pending status. Polling reuses the credential mode stored on the extract at create time. Sandbox extracts keep using the Transparenzregister test client automatically; no credential header is accepted on this endpoint. operationId: getTransparenzregisterExtract parameters: - name: extract_id in: path required: true description: | Extract ID from the submit endpoint. Example: "tre_12345678" schema: type: string responses: '200': description: Extract retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TransparenzregisterExtract' '202': description: Extract is still processing content: application/json: schema: $ref: '#/components/schemas/TransparenzregisterExtract' '400': description: Bad Request - Invalid extract ID or parameters '401': description: Unauthorized - Authentication required '404': description: Not Found - Extract not found '500': description: >- Internal Server Error - An error occurred while processing the request x-codeSamples: - lang: JavaScript source: >- 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.getV1('extract_id'); console.log(transparenzregisterExtract.id); - lang: Python source: >- import os from openregister import Openregister client = Openregister( api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted ) transparenzregister_extract = client.transparenzregister.extract.get_v1( "extract_id", ) print(transparenzregister_extract.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/oregister/openregister-go\"\n\t\"github.com/oregister/openregister-go/option\"\n)\n\nfunc main() {\n\tclient := openregister.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\ttransparenzregisterExtract, err := client.Transparenzregister.Extract.GetV1(context.TODO(), \"extract_id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", transparenzregisterExtract.ID)\n}\n" - lang: CLI source: |- openregister transparenzregister:extract get-v1 \ --api-key 'My API Key' \ --extract-id extract_id components: schemas: TransparenzregisterExtract: type: object description: > Transparenzregister extract resource including processing state, parsed report, and downloadable documents. properties: id: type: string description: | Stable extract identifier. Example: "tre_12345678" status: type: string enum: - completed - processing - failed description: | Status of the Transparenzregister extract. company_id: type: string nullable: true description: | Company identifier associated with this extract request. May be null when using sandbox credentials. ekrn: type: string nullable: true description: | EKRN used to request this extract. reference_number: type: string nullable: true description: | Transparenzregister reference number from the extract. submitted_at: type: string format: date-time description: | Timestamp when extract submission started. completed_at: type: string format: date-time nullable: true description: | Timestamp when extract processing completed. report: $ref: '#/components/schemas/TransparenzregisterReport' documents: type: array items: $ref: '#/components/schemas/TransparenzregisterDocument' description: | URLs for downloading available extract documents. required: - id - status TransparenzregisterReport: type: object nullable: true description: > Parsed Transparenzregister extract report limited to UBO-relevant fields. properties: created_at: type: string format: date nullable: true description: | Extract creation date. notice_type: type: string nullable: true description: | Type of Transparenzregister notice. validity: $ref: '#/components/schemas/TransparenzregisterValidity' status_flags: $ref: '#/components/schemas/TransparenzregisterStatusFlags' groups: type: array items: $ref: '#/components/schemas/TransparenzregisterGroup' ubos: type: array items: $ref: '#/components/schemas/TransparenzregisterUBO' fictional_ubo_reason: type: string nullable: true description: | Reason indicating no natural person UBO could be determined. TransparenzregisterDocument: type: object description: | Download URL for a document with format information. properties: document_id: type: string format: uuid description: | Stable UUID for this document. url: type: string description: | Download URL for the document. Example: "https://api.example.com/download/abc123" format: type: string description: | Format of the downloadable document. Example: "xml", "pdf", "json" filename: type: string description: | Suggested filename for the download. Example: "registerauszug_company_12345.pdf" required: - document_id - url - format - filename TransparenzregisterValidity: type: object nullable: true properties: from: $ref: '#/components/schemas/TransparenzregisterValidityPoint' until: $ref: '#/components/schemas/TransparenzregisterValidityPoint' TransparenzregisterStatusFlags: type: object nullable: true properties: deleted: type: boolean deletion_date: type: string format: date nullable: true discrepancy_note: type: string nullable: true corrected_references: type: array items: type: string corrected_by_reference: type: string nullable: true TransparenzregisterGroup: type: object properties: position: type: integer format: int32 interest_type: type: string nullable: true description: type: string nullable: true TransparenzregisterUBO: type: object properties: position: type: integer format: int32 natural_person: $ref: '#/components/schemas/TransparenzregisterUBONaturalPerson' interest: $ref: '#/components/schemas/TransparenzregisterUBOInterest' TransparenzregisterValidityPoint: type: object nullable: true properties: date: type: string format: date nullable: true note: type: string nullable: true TransparenzregisterUBONaturalPerson: type: object nullable: true properties: title: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true full_name: type: string nullable: true date_of_birth: type: string format: date nullable: true nationalities: type: array items: type: string description: | ISO 3166-1 alpha-2 nationality codes where available. city: type: string nullable: true country: type: string nullable: true TransparenzregisterUBOInterest: type: object nullable: true properties: type: type: string nullable: true scope: type: string nullable: true percentage: type: number format: double nullable: true securitySchemes: BearerAuth: type: http scheme: bearer description: | API Key Authentication Provide your API key as a Bearer token in the Authorization header. ````