> ## 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. # Start Job > Start a realtime request without waiting for it. The request returns at once with a pending job. Use this instead of `realtime=true` when your client cannot keep a request open for the minutes the Handelsregister may take. Job types: - `company`: refreshes the company from the Handelsregister, like `GET /v1/company/{company_id}?realtime=true`. - `owners`: refreshes the company's owners, like `GET /v1/company/{company_id}/owners?realtime=true`. - `document`: fetches one document, like `GET /v1/document`. Requires `document_category`. Follow a job either way, or both: - Poll `GET /v1/jobs/{job_id}` until `status` is `completed` or `failed`. A completed job carries its result in `results`: the document for a `document` job, the company or its owners for a `company` or `owners` job. - Configure a webhook endpoint: when the job finishes, OpenRegister sends a `job.completed` or `job.failed` webhook to it. The job can be polled all the same. Jobs are available on paid plans. A completed job costs what the same request with `realtime=true` costs: 20 credits for `company` and `owners`, 10 for `document`. Failed jobs and polling are free. ## Start a realtime job Fetch fresh data from the Handelsregister without waiting for it. The request returns at once with a pending job, and OpenRegister fetches the data in the background. Use a job instead of `realtime=true` when your client cannot keep a request open while the Handelsregister answers. **Cost:** 20 credits for `company` and `owners` jobs, 10 credits for `document` jobs, charged when the job completes. Failed jobs are free. ### Job types | `type` | Fetches | Same as | | - | - | - | | `company` | The company's register data | [`GET /v1/company/{company_id}?realtime=true`](https://docs.openregister.de/endpoint/company) | | `owners` | The company's owners | [`GET /v1/company/{company_id}/owners?realtime=true`](https://docs.openregister.de/endpoint/company-owners) | | `document` | One register document, set by `document_category` | [`GET /v1/document`](https://docs.openregister.de/endpoint/document-realtime) | ### Following a job Follow a job either way, or both: 1. **Polling:** call [Get Job](https://docs.openregister.de/endpoint/job-get.md) with the returned `id` until `status` is `completed` or `failed`. A completed job carries its result in `results`. 2. **Webhook:** configure a webhook endpoint in your [OpenRegister dashboard](https://openregister.de/keys). When the job finishes, OpenRegister sends a `job.completed` or `job.failed` webhook to it. The webhook carries no result; read `results` with [Get Job](https://docs.openregister.de/endpoint/job-get.md). Webhooks are delivered and signed the same way as monitor webhooks, see [Receiving Webhooks](https://docs.openregister.de/guide/monitoring.md#receiving-webhooks) and [Verifying Webhook Signatures](https://docs.openregister.de/guide/monitoring.md#verifying-webhook-signatures). > [!NOTE] > > If your endpoint subscribes to selected event types only, add `job.completed` and `job.failed` to receive job webhooks. ### Webhook payload `job.completed` and `job.failed` share one payload. **event\_type** `string` *required* Event type identifier: `job.completed` or `job.failed`. **job\_id** `string` *required* Job ID, as returned by `POST /v1/jobs`. **type** `string` *required* Job type: `company`, `owners` or `document`. **company\_id** `string` *required* Company register ID the job refreshed (e.g. `DE-HRB-F1103-267645`). **document\_category** `string | null` *required* Document category of a `document` job; `null` for `company` and `owners` jobs. **status** `string` *required* Final job status: `completed` or `failed`. **reason** `string | null` *required* Why the job failed, see [failure reasons](https://docs.openregister.de/endpoint/job-get.md#failure-reasons); `null` for completed jobs. **timestamp** `string` *required* When the job finished (ISO 8601 / RFC 3339). ```json job.completed theme={"dark"} { "event_type": "job.completed", "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "document", "company_id": "DE-HRB-F1103-267645", "document_category": "current_printout", "status": "completed", "reason": null, "timestamp": "2026-11-04T12:00:00Z" } ``` ```json job.failed theme={"dark"} { "event_type": "job.failed", "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "company", "company_id": "DE-HRB-F1103-267645", "document_category": null, "status": "failed", "reason": "timeout", "timestamp": "2026-11-04T12:00:00Z" } ``` ### Error cases | Status | Cause | | - | - | | `400` | Invalid parameters, a `company` job for an inactive company, or an `owners` job for a legal form without [owner data](https://docs.openregister.de/endpoint/company-owners.md#supported-legal-forms) | | `401` | Authentication required | | `402` | Jobs are available on paid plans only | | `404` | Company not found | | `429` | 100 jobs are already pending for your account | | `500` | Internal server error | ### Notes * `document_category` is required for `document` jobs and not allowed for other types. * For `company` and `owners` jobs, `company_id` in the response is the company's latest register ID. It differs from the requested one when the company moved to another register. ## OpenAPI ````yaml POST /v1/jobs openapi: 3.1.0 info: title: OpenRegister API version: 2.5.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/jobs: post: tags: - v1 summary: Start a job description: > Start a realtime request without waiting for it. The request returns at once with a pending job. Use this instead of `realtime=true` when your client cannot keep a request open for the minutes the Handelsregister may take. Job types: - `company`: refreshes the company from the Handelsregister, like `GET /v1/company/{company_id}?realtime=true`. - `owners`: refreshes the company's owners, like `GET /v1/company/{company_id}/owners?realtime=true`. - `document`: fetches one document, like `GET /v1/document`. Requires `document_category`. Follow a job either way, or both: - Poll `GET /v1/jobs/{job_id}` until `status` is `completed` or `failed`. A completed job carries its result in `results`: the document for a `document` job, the company or its owners for a `company` or `owners` job. - Configure a webhook endpoint: when the job finishes, OpenRegister sends a `job.completed` or `job.failed` webhook to it. The job can be polled all the same. Jobs are available on paid plans. A completed job costs what the same request with `realtime=true` costs: 20 credits for `company` and `owners`, 10 for `document`. Failed jobs and polling are free. operationId: createJob requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JobCreate' responses: '202': description: The job was accepted and is pending content: application/json: schema: $ref: '#/components/schemas/Job' '400': description: >- Bad Request - Invalid parameters, an inactive company, or owners not available for the company's legal form '401': description: Unauthorized - Authentication required '402': description: Payment Required - Jobs are available on paid plans only '404': description: Not Found - Company ID doesn't exist '429': description: Too Many Requests - Too many pending jobs '500': description: >- Internal Server Error - An error occurred while processing the request components: schemas: JobCreate: type: object properties: type: $ref: '#/components/schemas/JobType' company_id: type: string description: | Unique company identifier. Example: DE-HRB-F1103-267645 document_category: $ref: '#/components/schemas/JobDocumentCategory' required: - type - company_id Job: type: object properties: id: type: string format: uuid description: | Unique job identifier. Example: f47ac10b-58cc-4372-a567-0e02b2c3d479 type: $ref: '#/components/schemas/JobType' company_id: type: string description: > Company the job refreshes. For `company` and `owners` jobs this is the company's latest register ID, which differs from the requested one when the company moved to another register. Example: DE-HRB-F1103-267645 document_category: allOf: - $ref: '#/components/schemas/JobDocumentCategory' nullable: true status: type: string enum: - pending - completed - failed reason: type: string nullable: true description: > Why a failed job failed: - `not_available`: the register holds no such document for this company. - `timeout`: the Handelsregister did not answer in time; try again later. - `internal_error`: any other failure. enum: - not_available - timeout - internal_error results: allOf: - $ref: '#/components/schemas/JobResults' nullable: true description: >- What a completed job produced, until `expires_at`. Null while the job is pending, when it failed, and after the results expired. expires_at: type: string format: date-time nullable: true description: >- Until when a completed job returns `results`, 12 hours after it finished. created_at: type: string format: date-time finished_at: type: string format: date-time nullable: true required: - id - type - company_id - document_category - status - reason - results - expires_at - created_at - finished_at JobType: type: string enum: - company - owners - document JobDocumentCategory: type: string enum: - current_printout - chronological_printout - historical_printout - structured_information - shareholder_list - articles_of_association JobResults: type: object description: The result of a completed job. Only the field of the job's type is set. properties: document: allOf: - $ref: '#/components/schemas/JobDocument' nullable: true description: The fetched document of a `document` job. company: allOf: - $ref: '#/components/schemas/CompanyV1' nullable: true description: The refreshed company of a `company` job. owners: allOf: - $ref: '#/components/schemas/CompanyOwners' nullable: true description: The refreshed owners of an `owners` job. required: - document - company - owners JobDocument: type: object properties: url: type: string format: uri description: >- Download URL of the document. It expires; read the job again for a new one. file_date: type: string format: date nullable: true file_name: type: string nullable: true required: - url - file_date - file_name CompanyV1: type: object properties: id: type: string description: | Unique company identifier. Example: DE-HRB-F1103-267645 register: $ref: '#/components/schemas/CompanyRegister' description: | Current registration information of the company. registers: description: | Historical registration changes. Shows how registration details changed over time. type: array items: $ref: '#/components/schemas/CompanyRegister' status: description: | Current status of the company: - active: Operating normally - inactive: No longer operating - liquidation: In the process of being dissolved type: string enum: - active - inactive - liquidation name: $ref: '#/components/schemas/CompanyName' description: | Current official name of the company. names: description: | Historical company names. Shows how the company name changed over time. type: array items: $ref: '#/components/schemas/CompanyName' address: $ref: '#/components/schemas/CompanyAddress' description: | Current registered address of the company. addresses: description: | Historical addresses. Shows how the company address changed over time. type: array items: $ref: '#/components/schemas/CompanyAddress' purpose: description: | Current official business purpose of the company. anyOf: - $ref: '#/components/schemas/CompanyPurpose' - type: 'null' purposes: description: | Historical business purposes. Shows how the company purpose changed over time. type: array items: $ref: '#/components/schemas/CompanyPurpose' capital: description: | Current registered capital of the company. anyOf: - $ref: '#/components/schemas/CompanyCapital' - type: 'null' capitals: description: | Historical capital changes. Shows how the company capital changed over time. type: array items: $ref: '#/components/schemas/CompanyCapital' representation: description: | List of individuals or entities authorized to represent the company. Includes directors, officers, and authorized signatories. type: array items: $ref: '#/components/schemas/CompanyRepresentativeV1' representation_rule: description: | The company's current general representation rule (allgemeine Vertretungsregelung), as published in the register. Example: "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten." type: string nullable: true indicators: description: > Key company indicators like net income, employee count, revenue, etc.. type: array items: $ref: '#/components/schemas/CompanyIndicatorSummary' legal_form: $ref: '#/components/schemas/CompanyLegalForm' description: | Legal form of the company. Example: "gmbh" for Gesellschaft mit beschränkter Haftung lei: description: | Legal Entity Identifier (LEI), if available. type: string documents: description: | Available official documents related to the company. type: array items: $ref: '#/components/schemas/CompanyDocument' incorporated_at: description: | Date when the company was officially registered. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date notarized_at: description: > Date of the notarized company agreement (Gesellschaftsvertrag or Satzung). Format: ISO 8601 (YYYY-MM-DD) Example: "2021-12-21" type: string format: date nullable: true terminated_at: description: | Date when the company was officially terminated (if applicable). Format: ISO 8601 (YYYY-MM-DD) Example: "2024-01-01" type: string format: date nullable: true merged_into: description: | If the company ceased to exist through a merger (Verschmelzung), the company it was merged into. anyOf: - $ref: '#/components/schemas/CompanyMergedInto' - type: 'null' acquisitions: description: | Companies that were merged into this company (Verschmelzung durch Aufnahme, as the acquiring entity). type: array items: $ref: '#/components/schemas/CompanyAcquisition' asset_spin_offs: description: | Spin-offs (Ausgliederung, § 123 Abs. 3 UmwG) in which this company transferred assets to another company as the transferring entity. type: array items: $ref: '#/components/schemas/CompanyAssetSpinOff' profit_transfer_agreement: description: | The company's current profit and loss transfer agreement (Gewinnabführungsvertrag), if one exists. The referenced company is the parent receiving this company's profit (Organträger). Null if the company has no active agreement. anyOf: - $ref: '#/components/schemas/CompanyProfitTransferAgreement' - type: 'null' industry_codes: description: | Industry codes of the company, classified from its current purpose (Unternehmensgegenstand). Empty when the purpose has not been classified or describes no codable activity. type: object properties: WZ2025: type: array items: $ref: '#/components/schemas/IndustryCode' required: - WZ2025 contact: description: | Contact information of the company. anyOf: - $ref: '#/components/schemas/Website' - type: 'null' insolvencies: description: | Insolvency proceedings of the company, if any. Contains basic information per proceeding; use the insolvency endpoint to retrieve all events of a proceeding. type: array items: $ref: '#/components/schemas/CompanyInsolvencySummary' estimates: $ref: '#/components/schemas/CompanyEstimates' description: | Modelled revenue, EBITDA and employees for companies that do not report them. One estimate per metric, for the latest fiscal year. sources: description: | Sources of the company data. type: array items: $ref: '#/components/schemas/Source' required: - id - register - registers - status - name - names - address - addresses - purpose - purposes - capital - capitals - representation - representation_rule - indicators - legal_form - documents - incorporated_at - notarized_at - terminated_at - merged_into - acquisitions - asset_spin_offs - profit_transfer_agreement - industry_codes - contact - estimates - sources CompanyOwners: type: object properties: company_id: type: string description: | Unique company identifier. Example: DE-HRB-F1103-267645 owners: type: array items: $ref: '#/components/schemas/CompanyOwnerItem' sources: description: | Sources of the company owners data. type: array items: $ref: '#/components/schemas/Source' best_available: type: boolean description: > When true, the returned owner data is the best available but may not reflect the most current ownership state. This applies to AG and SE companies where ownership data is sourced from Handelsregister decision and articles of association documents, which are not filed on every ownership change. required: - company_id - owners - sources - best_available CompanyRegister: type: object properties: company_id: type: string description: | Unique company identifier. Example: DE-HRB-F1103-267645 register_number: type: string description: | Registration number in the company register. Example: "230633" register_type: $ref: '#/components/schemas/CompanyRegisterType' description: | Type of register where the company is recorded. Example: "HRB" (Commercial Register B) register_court: type: string description: | Court where the company is registered. Example: "Berlin (Charlottenburg)" start_date: description: | Date when this registration information became effective. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date required: - register_number - register_type - register_court CompanyName: type: object properties: name: description: | Official company name including any legal form designations. Example: "Descartes Technologies UG (haftungsbeschränkt)" type: string legal_form: $ref: '#/components/schemas/CompanyLegalForm' description: | Legal form of the company at this point in time. Example: "gmbh" for Gesellschaft mit beschränkter Haftung start_date: description: | Date when this name became effective. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date required: - name - legal_form - start_date CompanyAddress: type: object properties: street: type: string description: | Street name and number. Example: "Musterstraße 1" city: type: string description: | City or locality name. Example: "Berlin" postal_code: type: string description: | Postal or ZIP code. Example: "10117" country: description: | Country name. Example: "Germany" type: string extra: description: | Additional address information such as c/o or attention line. Example: "c/o Max Mustermann" type: string start_date: description: | Date when this address became effective. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date formatted_value: description: | Complete address formatted as a single string. Example: "Musterstraße 1, 10117 Berlin, Germany" type: string required: - city - country - start_date - formatted_value CompanyPurpose: type: object properties: purpose: description: > Official description of the company's business activities and objectives. This is the registered purpose as stated in official documents. type: string start_date: description: | Date when this purpose became effective. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date required: - purpose - start_date CompanyCapital: type: object properties: amount: description: | Capital amount as a decimal number. Example: 100000.00 represents 100,000.00 monetary units type: number format: double currency: description: | Currency code for the capital amount. Example: "EUR" for Euro type: string enum: - EUR - DEM - USD start_date: description: | Date when this capital amount became effective. Format: ISO 8601 (YYYY-MM-DD) Example: "2023-01-01" type: string format: date required: - amount - currency - start_date CompanyRepresentativeV1: type: object properties: id: description: | Unique identifier for the representative. For companies: Format matches company_id pattern For individuals: UUID Example: "DE-HRB-F1103-267645" or UUID May be null for certain representatives. type: string nullable: true name: description: >- The name of the representative. E.g. "Max Mustermann" or "Max Mustermann GmbH" type: string type: $ref: '#/components/schemas/EntityType' description: Whether the representation is a natural person or a legal entity. role: $ref: '#/components/schemas/RepresentationRole' description: | Coarse role bucket. Stable set of values, safe to switch on exhaustively. Use `role_detail` for the precise register role. E.g. "DIRECTOR" role_detail: $ref: '#/components/schemas/RepresentationRoleDetail' description: | The precise role as recorded in the register, plus ready-to-display titles. A Vorstand and a Geschäftsführer both have role "DIRECTOR" but differ here. start_date: description: | Date when this representative role became effective. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date end_date: description: | Date when this representative role ended (if applicable). Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date nullable: true authority: description: > The representative's current individual representation authority (individuelle Vertretungsbefugnis), as published in the register. Null if no special authority is recorded. Example: "einzelvertretungsberechtigt mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen Rechtsgeschäfte abzuschließen" type: string nullable: true authority_detail: description: Structured facts read from `authority`. Null when none are stated. anyOf: - $ref: '#/components/schemas/RepresentationAuthorityDetail' - type: 'null' legal_person: anyOf: - $ref: '#/components/schemas/CompanyRepresentativeV1LegalPerson' - type: 'null' natural_person: anyOf: - $ref: '#/components/schemas/CompanyRepresentativeV1NaturalPerson' - type: 'null' required: - id - name - type - role - role_detail - start_date - end_date - authority - authority_detail CompanyIndicatorSummary: description: | A focused subset of the key company indicators for a given year. Values of the indicator are given in the smallest currency unit (cents). Example: 2099 represents €20.99 for monetary values. For non-monetary values (e.g., employees), the actual number. type: object properties: date: description: | Date to which this financial indicators apply. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date report_id: description: The report id (source) of the indicators. type: string format: uuid short_year: description: A short fiscal year (Rumpfgeschäftsjahr), shorter than twelve months type: boolean balance_sheet_total: description: The balance sheet total of that year (in cents). type: integer format: int64 nullable: true net_income: description: The net income of that year (in cents). type: integer format: int64 nullable: true revenue: description: The revenue of that year (in cents). type: integer format: int64 nullable: true cash: description: The cash of that year (in cents). type: integer format: int64 nullable: true employees: description: The number of employees of that year. type: integer format: int64 nullable: true equity: description: The equity of that year (in cents). type: integer format: int64 nullable: true real_estate: description: The real estate of that year (in cents). type: integer format: int64 nullable: true materials: description: The materials of that year (in cents). type: integer format: int64 nullable: true pension_provisions: description: The pension provisions of that year (in cents). type: integer format: int64 nullable: true salaries: description: The salaries of that year (in cents). type: integer format: int64 nullable: true taxes: description: The taxes of that year (in cents). type: integer format: int64 nullable: true liabilities: description: The liabilities of that year (in cents). type: integer format: int64 nullable: true capital_reserves: description: The capital reserves of that year (in cents). type: integer format: int64 nullable: true required: - date - report_id - short_year - balance_sheet_total - net_income - revenue - cash - employees - equity - real_estate - materials - pension_provisions - salaries - taxes - liabilities - capital_reserves CompanyLegalForm: type: string description: > Legal form of the company. Common German legal forms: - gmbh: Gesellschaft mit beschränkter Haftung (Limited Liability Company) - ag: Aktiengesellschaft (Stock Corporation) - ug: Unternehmergesellschaft (Entrepreneurial Company with limited liability) - ohg: Offene Handelsgesellschaft (General Partnership) - kg: Kommanditgesellschaft (Limited Partnership) - ev: Eingetragener Verein (Registered Association) - foundation: Stiftung (Foundation) enum: - ag - eg - ek - ev - ewiv - foreign - foundation - gbr - ggmbh - gmbh - kg - kgaa - unknown - llp - municipal - ohg - se - ug CompanyDocument: type: object properties: id: description: | Unique identifier for the document. Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479" type: string type: description: | Categorization of the document: - articles_of_association: Company statutes/bylaws - sample_protocol: Standard founding protocol - shareholder_list: List of company shareholders type: string enum: - articles_of_association - sample_protocol - shareholder_list date: description: | Document publication or filing date. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date latest: description: | Whether this is the latest version of the document_type. type: boolean required: - id - type - date - latest CompanyMergedInto: type: object properties: company_id: description: > Unique company identifier of the company this company was merged into. Example: DE-HRB-F1103-267645 type: string name: description: | Current name of the company this company was merged into. type: string registration_date: description: | Date the merger was registered. Format: ISO 8601 (YYYY-MM-DD) type: string format: date agreement_date: description: | Date the underlying contract (Verschmelzungsvertrag) was concluded, as cited in the register entry. Null when the register text does not cite a contract date. Entries sharing an agreement_date belong to the same transaction. Format: ISO 8601 (YYYY-MM-DD) type: string format: date nullable: true required: - company_id - name - registration_date - agreement_date CompanyAcquisition: type: object properties: company_id: description: > Unique company identifier of the company that was merged into this company. Example: DE-HRB-F1103-267645 type: string name: description: | Current name of the company that was merged into this company. type: string registration_date: description: | Date the merger was registered. Format: ISO 8601 (YYYY-MM-DD) type: string format: date agreement_date: description: | Date the underlying contract (Verschmelzungsvertrag) was concluded, as cited in the register entry. Null when the register text does not cite a contract date. Entries sharing an agreement_date belong to the same transaction. Format: ISO 8601 (YYYY-MM-DD) type: string format: date nullable: true required: - company_id - name - registration_date - agreement_date CompanyAssetSpinOff: type: object properties: company_id: description: | Unique company identifier of the company that received the assets. Example: DE-HRB-F1103-267645 type: string name: description: | Current name of the company that received the assets. type: string registration_date: description: | Date the spin-off was registered. Format: ISO 8601 (YYYY-MM-DD) type: string format: date agreement_date: description: | Date the underlying contract (Ausgliederungsvertrag) was concluded, as cited in the register entry. Null when the register text does not cite a contract date. Entries sharing an agreement_date belong to the same transaction. Format: ISO 8601 (YYYY-MM-DD) type: string format: date nullable: true required: - company_id - name - registration_date - agreement_date CompanyProfitTransferAgreement: type: object properties: company_id: description: | Unique company identifier of the parent company receiving this company's profit (Organträger). Example: DE-HRB-F1103-267645 type: string name: description: | Current name of the parent company. type: string registration_date: description: | Date the agreement was registered. Format: ISO 8601 (YYYY-MM-DD) type: string format: date agreement_date: description: > Date the underlying contract (Gewinnabführungsvertrag) was concluded, as cited in the register entry. Null when the register text does not cite a contract date. Entries sharing an agreement_date belong to the same transaction. Format: ISO 8601 (YYYY-MM-DD) type: string format: date nullable: true required: - company_id - name - registration_date - agreement_date IndustryCode: type: object description: | A WZ 2025 class (Klasse) the company is active in, with the subclasses (Unterklassen) behind it. The class of the company's main activity comes first. properties: code: type: string description: | WZ 2025 class. Example: "64.19" label_de: type: string description: | Official German title of the class. Example: "Kreditinstitute, ohne Spezialkreditinstitute" primary: type: boolean description: | Whether the company's main activity falls in this class. True for at most one class. The main activity is classified from the purpose, not recorded in the register. subclasses: type: array description: | The WZ 2025 subclasses within this class, the main activity first. items: $ref: '#/components/schemas/IndustrySubclass' required: - code - label_de - primary - subclasses Website: type: object properties: email: type: string phone: type: string vat_id: type: string website_url: type: string social_media: $ref: '#/components/schemas/SocialMediaLinks' required: - website_url - social_media CompanyInsolvencySummary: type: object description: | Basic information about an insolvency proceeding of the company. Use the insolvency endpoint to retrieve all events of the proceeding. properties: id: description: | Unique identifier of the insolvency proceeding. type: string format: uuid current_status: $ref: '#/components/schemas/InsolvencyStatus' court: description: | Insolvency court handling the proceeding. type: string case_number: description: | Case number of the proceeding at the court. Example: "36d IN 3382/25" type: string proceeding_kind: description: | Kind of insolvency proceeding. Null when unknown. anyOf: - $ref: '#/components/schemas/InsolvencyProceedingKind' - type: 'null' administration_kind: description: > Kind of administration ordered for the proceeding. Null when unknown. anyOf: - $ref: '#/components/schemas/InsolvencyAdministrationKind' - type: 'null' opened_at: description: | Date the proceeding was opened. Format: ISO 8601 (YYYY-MM-DD) type: string format: date nullable: true closed_at: description: | Date the proceeding was closed. Format: ISO 8601 (YYYY-MM-DD) type: string format: date nullable: true required: - id - current_status - court - case_number CompanyEstimates: type: object description: | The latest modelled figure per metric. A metric is null when the company's latest report states it, when there is no estimate, or when the estimate is more than four years old. Search filters on estimated_revenue, estimated_ebitda and estimated_employees use these same estimates. properties: revenue: description: Estimated revenue (in cents). anyOf: - $ref: '#/components/schemas/FinancialEstimate' - type: 'null' ebitda: description: Estimated EBITDA (in cents). anyOf: - $ref: '#/components/schemas/FinancialEstimate' - type: 'null' employees: description: Estimated number of employees. anyOf: - $ref: '#/components/schemas/FinancialEstimate' - type: 'null' required: - revenue - ebitda - employees Source: type: object properties: document_url: description: > Url of the source document. In the form of a presigned url accessible for 30 minutes. type: string required: - document_url CompanyOwnerItem: type: object properties: id: description: | Unique identifier for the shareholder. For companies: Format matches company_id pattern For individuals: UUID Example: "DE-HRB-F1103-267645" or UUID May be null for certain shareholders. type: string nullable: true type: $ref: '#/components/schemas/EntityType' description: The type of shareholder. relation_type: $ref: '#/components/schemas/CompanyRelationType' description: | Type of relationship between the entity and the company. Use `role_detail` for the precise register role. role_detail: $ref: '#/components/schemas/RepresentationRoleDetail' description: | The precise role as recorded in the register, plus ready-to-display titles. A Kommanditist and a Gesellschafter both appear here with their register-level role, while `relation_type` only carries the coarse bucket. name: description: >- The name of the shareholder. E.g. "Max Mustermann" or "Max Mustermann GmbH" type: string natural_person: description: | Details about the natural person. anyOf: - $ref: '#/components/schemas/CompanyOwnerNaturalPerson' - type: 'null' legal_person: description: | Details about the legal person. anyOf: - $ref: '#/components/schemas/CompanyOwnerLegalPerson' - type: 'null' nominal_share: description: | Nominal value of shares in Euro. Example: 100 type: number format: double percentage_share: description: | Percentage of company ownership. Example: 5.36 represents 5.36% ownership type: number format: double nullable: true start: description: > Date when the relation started. Only available for some types of owners. Format: ISO 8601 (YYYY-MM-DD) Example: "2022-01-01" type: string format: date nullable: true required: - id - type - relation_type - role_detail - name - natural_person - legal_person - nominal_share - percentage_share - start CompanyRegisterType: type: string description: > Type of company register where the entity is recorded. Common types: - HRB: Commercial Register B (limited liability companies, stock corporations) - HRA: Commercial Register A (partnerships, sole proprietorships) - PR: Partnership Register - GnR: Cooperative Register - VR: Association Register enum: - HRB - HRA - PR - GnR - VR EntityType: type: string enum: - natural_person - legal_person RepresentationRole: description: | Coarse role bucket. This set is stable: new register roles are folded into an existing bucket rather than added here, so it is safe to match on exhaustively. type: string enum: - DIRECTOR - PROKURA - SHAREHOLDER - OWNER - PARTNER - PERSONAL_LIABLE_DIRECTOR - LIQUIDATOR - OTHER RepresentationRoleDetail: description: | The register-level role behind the coarse `role` bucket, together with display-ready titles in German and English. Always present. type: object properties: code: $ref: '#/components/schemas/RepresentationRoleDetailCode' description: | The precise role as recorded in the register. Example: "EXECUTIVE" for a Vorstand, "DIRECTOR" for a Geschäftsführer — both have role "DIRECTOR". label_de: description: | German title, gender-neutral, as shown on openregister.de. Example: "Vorstand" type: string label_de_short: description: | Abbreviated German title, for dense layouts such as tables. Example: "Vst." type: string label_en: description: | English title. A translation for display, not a legal term — the German title is the one the register uses. Example: "Executive Board Member" type: string label_en_short: description: | Abbreviated English title, for dense layouts such as tables. Example: "Exec. Board" type: string required: - code - label_de - label_de_short - label_en - label_en_short RepresentationAuthorityDetail: type: object properties: type: description: Signing authority. Null when not stated. anyOf: - $ref: '#/components/schemas/RepresentationAuthorityType' - type: 'null' self_dealing_allowed: description: | Fully exempt from self-dealing restrictions (in Germany § 181 BGB). Null when not stated or only partly exempt. type: boolean nullable: true required: - type - self_dealing_allowed CompanyRepresentativeV1LegalPerson: type: object properties: name: type: string city: type: string nullable: true country: description: > Country where the representative is located, in ISO 3166-1 alpha-2 format. Example: "DE" for Germany type: string required: - name - city - country CompanyRepresentativeV1NaturalPerson: type: object properties: city: description: | City where the representative is located. Example: "Berlin" type: string nullable: true first_name: description: | First name of the representative. Example: "Max" type: string nullable: true last_name: description: | Last name of the representative. Example: "Mustermann" type: string nullable: true title: description: | Academic or professional title of the representative. Example: "Dr." type: string nullable: true date_of_birth: description: | Date of birth of the representative. May still be null for natural persons if it is not available. Format: ISO 8601 (YYYY-MM-DD) Example: "1990-01-01" type: string format: date nullable: true required: - city - first_name - last_name - date_of_birth IndustrySubclass: type: object description: | A WZ 2025 subclass (Unterklasse). properties: code: type: string description: | WZ 2025 subclass. Example: "64.19.1" label_de: type: string description: > Official German title of the subclass. Example: "Kreditbanken einschließlich Zweigstellen ausländischer Banken" primary: type: boolean description: | Whether this is the company's main activity. True for at most one subclass. The main activity is classified from the purpose, not recorded in the register. required: - code - label_de - primary SocialMediaLinks: type: object properties: linkedin: type: string instagram: type: string github: type: string twitter: type: string facebook: type: string youtube: type: string xing: type: string tiktok: type: string InsolvencyStatus: type: string description: | Current status of the insolvency proceeding. enum: - preliminary - opened - rejected_no_assets - mass_insufficient - plan_supervised - lifted - discontinued - discharge_pending - discharge_granted - discharge_denied - discharge_revoked - unknown InsolvencyProceedingKind: type: string description: | Kind of insolvency proceeding. enum: - regular_insolvency - consumer_insolvency InsolvencyAdministrationKind: type: string description: | Kind of administration ordered for the proceeding. enum: - external_administration - self_administration - protective_shield FinancialEstimate: type: object description: | A modelled value for one fiscal year. min and max are not hard limits: the true value lies between them with 80% probability. properties: value: description: The estimated figure, the middle of the modelled range. type: integer format: int64 min: description: Lower end of the 80% range. type: integer format: int64 max: description: Upper end of the 80% range. type: integer format: int64 confidence: description: | How narrow the 80% range is, the same tiers the search filters estimated_*_confidence use. Revenue and employees are judged by the ratio of max to min, EBITDA by the range relative to the latest reported balance sheet total (low when there is none). type: string enum: - high - medium - low date: description: | End of the fiscal year the estimate applies to, matching the company's reporting year end. Format: ISO 8601 (YYYY-MM-DD) Example: "2024-12-31" type: string format: date required: - value - min - max - confidence - date CompanyRelationType: type: string enum: - shareholder - stockholder - limited_partner - general_partner CompanyOwnerNaturalPerson: type: object properties: full_name: type: string first_name: type: string last_name: type: string date_of_birth: type: string nullable: true city: type: string country: type: string required: - full_name - first_name - last_name - date_of_birth - city - country CompanyOwnerLegalPerson: type: object properties: name: type: string city: type: string nullable: true country: description: | Country where the owner is located, in ISO 3166-1 alpha-2 format. Example: "DE" for Germany type: string required: - name - city - country RepresentationRoleDetailCode: description: | Register-level role code. Unlike `role`, this set grows as new roles appear in the register. Treat an unrecognised value as OTHER and match on `role` if you need an exhaustive set. type: string enum: - DIRECTOR - EMERGENCY_DIRECTOR - EXECUTIVE - CHAIRMAN - DEPUTY_CHAIRMAN - BOARD - PRESIDENT_BOARD - VICE_PRESIDENT_BOARD - PRESIDENT - MEMBER - NON_EXECUTIVE_DIRECTOR - BOARD_SECRETARY - BOARD_TREASURER - BOARD_SPORTS - BOARD_OTHER - REPRESENTATIVE - SECONDARY_REPRESENTATIVE - COURT_ORDERED_REPRESENTATIVE - PROKURA - PROKURA_SINGLE - PROKURA_JOINT - LIQUIDATOR - INSOLVENCY_DIRECTOR - PRELIMINARY_INSOLVENCY_DIRECTOR - OWNER - SHAREHOLDER - PARTNER - PERSONAL_LIABLE_DIRECTOR - LIMITED_PARTNER - OTHER RepresentationAuthorityType: type: string description: | SOLE may represent alone, JOINT only together with others, NONE is excluded from representation, GENERAL follows the general representation rule. enum: - SOLE - JOINT - NONE - GENERAL securitySchemes: BearerAuth: type: http scheme: bearer description: > API Key Authentication Provide your API key as a Bearer token in the Authorization header. Rejected keys return a JSON body `{"message": "..."}` naming the reason: - 401 `API key is missing`, `API key is invalid`, `API key is disabled` or `API key has expired` - 429 `API key rate limit exceeded` or `API key usage limit exceeded` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.