# Authentication
Source: https://docs.openregister.de/authentication
How to authenticate with the API
All API endpoints require authentication using an API key. You must include your API key in the `Authorization` header of each request using the Bearer token format.
## Getting an API Key (takes under a minute)
1. Create an account at [openregister.de](https://openregister.de)
2. Go to the [API Keys](https://openregister.de/keys) page
3. Create a new API key
The free plan includes 500 credits per month - perfect for testing and development. For production use, upgrade to the Pro plan. Learn more about [pricing and credit costs](/pricing).
## Using the API Key
Include the API key in the `Authorization` header of all API requests:
```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```
## Next Steps
Got your API key? Head to the [Quickstart Guide](/quickstart) to start making your first requests with our official SDKs or other integrations.
# Simple company search
Source: https://docs.openregister.de/endpoint/autocomplete-company
GET /v1/autocomplete/company
## Autocomplete company
Fast, lightweight search for companies by name. This endpoint is optimized for autocomplete functionality in user interfaces, returning quick results as users type. It searches both current and historical company names, making it perfect for implementing search-as-you-type features. Returns basic company information including ID, name, and register details.
**Cost:** 1 credit per request
# Company information
Source: https://docs.openregister.de/endpoint/company
GET /v1/company/{company_id}
## Get company information
Returns comprehensive company data including registration details, management, financial indicators, contact information, and complete historical changes.
**Cost:** 10 credits (20 credits with `realtime=true`)
### Realtime Parameter
Add `realtime=true` to fetch the latest data directly from the Handelsregister. Costs an additional 10 credits. Use for compliance checks or when you need guaranteed current data.
### Insolvency Data
When the company has insolvency proceedings, the response includes an `insolvencies` array with a summary of each proceeding. Use the [insolvency endpoint](/endpoint/insolvency) to retrieve the full event history of a proceeding.
# Contact information
Source: https://docs.openregister.de/endpoint/company-contact
GET /v0/company/{company_id}/contact
**Deprecated:** This endpoint is deprecated. Contact information is now included in the [company details endpoint](/endpoint/company) response. Use that endpoint instead to get company data including contact information in a single request.
## Get company contact information
Retrieve contact information for a company including email addresses, phone numbers, and VAT identification numbers. This data is collected from publicly available sources including company websites. The response includes the source URL where each piece of information was found, allowing you to verify the data origin.
**Cost:** 10 credits
# Financials
Source: https://docs.openregister.de/endpoint/company-financials
GET /v1/company/{company_id}/financials
## Get company financials
Retrieve detailed financial reports including balance sheets (Bilanz) and income statements (Gewinn- und Verlustrechnung) from the Bundesanzeiger. This endpoint provides structured financial data across multiple reporting periods, allowing for trend analysis and financial health assessment.
**Cost:** 10 credits
### Financial Data Structure
The response includes complete balance sheet data (assets/Aktiva and liabilities/Passiva) and income statement information when available. Financial reports are structured according to German accounting standards (HGB - Handelsgesetzbuch) and include line items such as current assets, fixed assets, equity, liabilities, revenue, expenses, and net income.
In addition to the raw financial statements, we provide pre-calculated financial indicators extracted from the balance sheet for immediate use. These include key metrics such as balance sheet total, revenue, net income, cash, equity, employees, and other important financial ratios - ready to use without additional calculations. These indicators are also returned at the top level of the response under `indicators`, sorted by date (latest first).
Each report additionally exposes its rendered document under `sources` as a short-lived, presigned `html_url` (valid for 30 minutes), so you can download or display the full original HTML report.
You'll receive data for all available reporting periods, typically covering multiple years. Each report includes the reporting date, currency, and a detailed breakdown of financial positions. Not all companies are required to publish detailed financial statements - data availability depends on company size and legal requirements.
### Use Cases
**Financial Analysis:** Assess a company's financial health by analyzing revenue trends, profitability, liquidity ratios, and capital structure. Compare financial metrics across multiple periods to identify growth patterns or concerns.
**Credit Assessment:** Evaluate creditworthiness by examining equity ratios, debt levels, and cash flow indicators. Banks and suppliers use this data for credit decisions and risk management.
**Market Research:** Identify financially strong companies in your target market. Filter for companies with specific revenue ranges, employee counts, or financial characteristics for business development or investment opportunities.
# Company historical owners
Source: https://docs.openregister.de/endpoint/company-historical-owners
GET /v1/company/{company_id}/owners/historical
## Retrieve the historical ownership changes of a company
Get the full ownership history of a company across all filed documents. Unlike the current owners endpoint, this endpoint returns ownership data from every shareholder list (Gesellschafterliste) ever filed, allowing you to trace how ownership has changed over time.
**Cost:** 25 credits
### Async Processing
This endpoint may need to process data before it can return a result. Depending on the state of the data, you will receive one of two responses:
| Status | Meaning |
| -------------- | ------------------------------------------------------------------------------------- |
| `200 OK` | Data is ready — the response body contains the full ownership history. |
| `202 Accepted` | Processing is still in progress. Re-call the same endpoint until you receive a `200`. |
When you receive a `202`, wait **30 seconds** before retrying. Re-call the same endpoint with the same `company_id`. There is no separate job ID — simply poll until you get a `200`.
**`202` responses are not billed.** Credits are only deducted when the endpoint returns `200` with data.
### Supported Legal Forms
Historical ownership data is available for:
* **GmbH** (Gesellschaft mit beschränkter Haftung) - Limited liability company
### Ownership Data Structure
The response includes ownership snapshots across all filed documents. Each snapshot contains the document date, the owners at that point in time, their ownership stake (as percentage and/or nominal shares), and share capital. For corporate shareholders, you'll receive the company ID to retrieve further details.
### Use Cases
**Ownership Analysis:** Understand who has controlled a company over time and identify indirect ownership through corporate shareholders. Map ownership chains to reveal corporate structures.
**Funding Rounds:** Analyze funding rounds and understand who invested when — trace new shareholders entering the cap table and stake changes over time to reconstruct the company's funding history.
**Risk Assessment:** Identify concentration of ownership, related party transactions, or complex ownership structures that may require additional scrutiny.
**Network Mapping:** Track ownership connections between companies over time to identify business groups, family holdings, or corporate networks.
# Company holdings
Source: https://docs.openregister.de/endpoint/company-holdings
GET /v1/company/{company_id}/holdings
## Retrieve the holdings of a company
Get a list of companies that this company owns or has stakes in. This endpoint reveals a company's investment portfolio and subsidiary structure, showing which other companies it controls or has invested in. Use this to map corporate groups and understand investment strategies.
**Cost:** 10 credits
# Company owners
Source: https://docs.openregister.de/endpoint/company-owners
GET /v1/company/{company_id}/owners
## Retrieve the owners of a company
Get detailed ownership information including shareholders, their ownership percentages, and share capital. This endpoint provides structured ownership data extracted from official register documents including shareholder lists (Gesellschafterlisten) and company registers.
**Cost:** 10 credits (20 credits with `realtime=true`)
### Supported Legal Forms
Ownership data is available for the following legal forms:
* **GmbH** (Gesellschaft mit beschränkter Haftung) - Limited liability company
* **KG** (Kommanditgesellschaft) - Limited partnership
* **e.K.** (eingetragener Kaufmann) - Registered merchant
* **eGbR** (eingetragene Gesellschaft bürgerlichen Rechts) - Registered civil law partnership
* **OHG** (Offene Handelsgesellschaft) - General partnership
### Ownership Data Structure
The response includes each owner's type (natural person, German company, foreign company, etc.), their ownership stake (as percentage and/or nominal shares), and their share class (e.g., Komplementär, Kommanditist for KG structures). For corporate shareholders, you'll receive the company ID to retrieve further details.
### Use Cases
**Ownership Analysis:** Understand who controls a company and identify indirect ownership through corporate shareholders. Map ownership chains to reveal corporate structures.
**Risk Assessment:** Identify concentration of ownership, related party transactions, or complex ownership structures that may require additional scrutiny.
**Network Mapping:** Track ownership connections between companies to identify business groups, family holdings, or corporate networks.
# Company UBOs
Source: https://docs.openregister.de/endpoint/company-ubo
GET /v1/company/{company_id}/ubo
## Retrieve the UBOs of a company
Identify the Ultimate Beneficial Owners (UBOs) - the natural persons who ultimately own or control a company. This endpoint calculates beneficial ownership by traversing the complete ownership chain, including indirect ownership through multiple corporate layers.
**Cost:** 25 credits
### What are UBOs?
Ultimate Beneficial Owners are the natural persons who ultimately own or control a company through direct or indirect ownership. According to German law (GwG - Geldwäschegesetz), individuals holding more than 25% of shares or voting rights are typically considered beneficial owners. Our API automatically calculates these percentages by analyzing multi-level ownership structures.
### Supported Legal Forms
UBO analysis is currently available for:
* **GmbH** - Limited liability company
* **gGmbH** - Non-profit limited liability company
* **UG** - Entrepreneurial company (mini-GmbH)
* **KG** - Limited partnership
### Use Cases
**AML/KYC Compliance:** Financial institutions, lawyers, and notaries use UBO data to fulfill anti-money laundering and know-your-customer requirements. Identify who ultimately controls a business relationship.
**Enhanced Due Diligence:** For high-risk transactions, identify the natural persons who ultimately benefit from and control the company, even when ownership is structured through complex corporate arrangements.
**Regulatory Reporting:** Many industries require disclosure of beneficial ownership. Use this endpoint to automatically identify reportable UBOs for regulatory filings and transparency registers.
# Document Realtime
Source: https://docs.openregister.de/endpoint/document-realtime
GET /v1/document
## Retrieve realtime documents for a company
Request official documents directly from the Handelsregister in real-time. This endpoint fetches documents on-demand from the official register, ensuring you always receive the most current version available.
**Cost:** 10 credits
### Available Document Types
You can retrieve several types of official documents by specifying the `document_category` parameter:
* **current\_printout (AD)** - Current register extract showing the company's current state (PDF)
* **chronological\_printout (CD)** - Complete historical extract showing all changes (PDF)
* **historical\_printout (HD)** - Historical snapshot from a previous point in time (PDF)
* **shareholder\_list (GV)** - Official shareholder list (Gesellschafterliste) (PDF)
* **articles\_of\_association (UT)** - Company articles/bylaws (Satzung/Gesellschaftsvertrag) (PDF)
* **structured\_information (SI)** - Structured company data (XML format)
Most documents are returned as PDF files that can be downloaded and archived, except for structured\_information which is provided in XML format for programmatic processing. These are the same official documents you would receive from the Handelsregister portal, but accessible via API.
### Use Cases
**Legal Documentation:** Lawyers and notaries use this endpoint to obtain official, certified register extracts for transactions, litigation, or regulatory filings. The current printout (AD) is commonly required for contracts and due diligence.
**Compliance Archiving:** Maintain audit trails by periodically downloading and archiving official documents. Keep historical snapshots for regulatory compliance and documentation requirements.
**Automated Verification:** Integrate document retrieval into your workflows to automatically obtain proof of registration, current ownership, or corporate structure whenever needed for client onboarding or transaction processing.
# Document Stored
Source: https://docs.openregister.de/endpoint/document-stored
GET /v1/document/{document_id}
## Retrieve stored documents for a company
Access documents that have been previously retrieved and stored in our database. This endpoint is faster and more cost-effective for accessing historical documents or documents that have already been fetched. For the most current documents, use the [realtime document endpoint](/endpoint/document-realtime) instead.
**Cost:** 10 credits
# Advanced company search
Source: https://docs.openregister.de/endpoint/filter-company
POST /v1/search/company
## Search companies
Perform advanced searches with complex filters to find companies matching specific criteria. Combine multiple filters on company attributes, financial metrics, ownership characteristics, and geographic location to identify your exact target audience.
**Cost:** 10 credits per search
### Powerful Filtering Options
Use filters to search by company status, legal form, location (city, postal code, or radius), industry codes, financial metrics (revenue, employees, balance sheet), incorporation date, ownership structure (family-owned, sole owner, owner-managed), insolvency status (`had_insolvency`, `has_open_insolvency`, `insolvency_stage`, `insolvency_opened_at`), and more. Combine multiple filters with AND logic to narrow your results precisely.
You can filter by over 70 different fields, including more than 45 financial indicators such as balance sheet totals, employee counts, provisions, and receivables, plus youngest owner age, capital amounts, and specific ownership characteristics. See our [filtering guide](/filtering) for detailed examples and all available filter fields.
### Use Cases
**Lead Generation:** Find companies matching your ideal customer profile. For example, search for GmbH companies in a specific industry with 50-200 employees and revenue over €5M in your target region.
**Market Analysis:** Identify all companies in a specific industry sector, analyze their distribution across regions, or find newly incorporated businesses in your market.
**Succession Planning:** Search for owner-managed companies where the owner is approaching retirement age (`youngest_owner_age > 60`, `has_representative_owner = true`) - perfect for identifying acquisition opportunities or succession planning services.
A full list of all German register courts is available [here](https://drive.google.com/file/d/1TkLE8myGlbj65Kub25mTxTbxiKJJ_zzE/view?usp=sharing).
# Search person
Source: https://docs.openregister.de/endpoint/filter-person
POST /v1/search/person
## Search for a person
Search for natural persons by name, city, date of birth, or other attributes. Find people based on their business roles and filter by criteria such as the number of companies they're involved with or their management positions. Use this endpoint to identify individuals for due diligence or to research business networks. More information about filtering can be found [here](/filtering).
**Cost:** 10 credits
# Insolvency proceeding
Source: https://docs.openregister.de/endpoint/insolvency
GET /v1/insolvency/{insolvency_id}
## Retrieve an insolvency proceeding
Get the full record of a single insolvency proceeding, including its complete event history. Each proceeding is assembled from the official insolvency announcements and tracks the case from the first security measures through opening, distributions, and discharge.
**Cost:** 10 credits
### Proceeding Data Structure
The response covers the whole lifecycle of a case:
* **Status:** `current_status` reflects where the proceeding stands (e.g. `preliminary`, `opened`, `rejected_no_assets`, `lifted`, `discharge_granted`)
* **Debtor:** name, kind (legal or natural person), legal form, and — where resolvable — the linked `company_id` for direct lookup of the debtor company
* **Administration:** administrator name and address, administration kind (external administration, self administration, protective shield)
* **Deadlines and distributions:** `claims_filing_deadline`, opening and closing dates, and distribution figures (`distribution_claims_total`, `distribution_available`)
* **Events:** every published announcement as a structured event with a summary, decision and publication dates, and typed `details` (administrator appointments, meetings, discharge decisions, distribution records)
### Use Cases
**Case Tracking:** Follow a specific proceeding over time — new events appear as the courts publish announcements, from preliminary measures to the final discharge decision.
**Due Diligence:** Reconstruct the full insolvency history of a counterparty, including past proceedings, administrators involved, and how the case was resolved.
**Legal Research:** Access structured summaries of each announcement together with meeting dates and locations, without parsing the original court publications yourself.
# Create Monitor
Source: https://docs.openregister.de/endpoint/monitor-create
POST /v1/monitor
## Create a monitor
Create a monitor to receive webhook notifications when a company or person is updated.
**Cost:** 25 credits (50 credits for daily monitors)
Before creating monitors, you must configure a webhook URL in your [OpenRegister dashboard](https://openregister.de/keys). See the [Monitoring guide](/guide/monitoring) for a full overview of how monitoring works.
### Entity ID
The `entity_id` format depends on the `entity_type`:
* **Company** — use the register ID, e.g. `DE-HRB-F1103-267645`. You can find this on the company page or via the search endpoints.
* **Person** — use the person UUID returned by the person search or person endpoint.
### Preferences
Preferences control which data categories trigger a webhook notification. You must provide at least one preference. All values must correspond to the given `entity_type` — mixing preferences across entity types returns a `400 Bad Request`.
**Company** (`entity_type: company`)
| Value | What triggers a notification |
| ---------------- | ------------------------------------------------------------------------ |
| `basic` | Core firmographic data — name, registered address, legal form, or status |
| `representation` | Directors, officers, managing partners, or authorised signatories |
| `financials` | Annual accounts or financial statements filed |
| `documents` | New documents or publications filed with the register |
| `ownership` | Direct owners (shareholders) of the company |
| `holdings` | Companies in which this company holds a stake |
**Person** (`entity_type: person`)
| Value | What triggers a notification |
| ---------------------- | ------------------------------------------------------------- |
| `management_positions` | Board or management roles the person holds across any company |
| `holdings` | Companies in which this person holds a stake |
### Update Frequency
The optional `update_frequency` field controls how often the monitored company is checked for register updates:
| Value | Check cadence | Creation cost | Monthly cost |
| ------------------ | ---------------------- | ------------- | ------------ |
| `weekly` (default) | At least once per week | 25 credits | 25 credits |
| `daily` | Once per day | 50 credits | 50 credits |
If you omit the field, the monitor defaults to `weekly`.
`update_frequency` is only supported for company monitors. Including it when `entity_type` is `person` returns a `400 Bad Request` validation error.
### Use Cases
**Compliance monitoring** — Subscribe to `basic`, `representation` and `ownership` changes on counterparties or customers. Receive alerts on legal form conversions, address moves, or management changes as soon as they appear in the register.
**Ownership change alerts** — Use the `ownership` and `holdings` preferences to detect when a company's shareholder structure changes, keeping your KYC data current without manual re-checks.
**Financial filing alerts** — Monitor the `financials` and `documents` preferences to be notified the moment new annual accounts or register publications are available, enabling automated document retrieval and archiving workflows.
**Due diligence pipelines** — Add a monitor when onboarding a new counterparty. Receive ongoing notifications for the duration of the relationship and remove the monitor when the relationship ends.
# Delete Monitor
Source: https://docs.openregister.de/endpoint/monitor-delete
DELETE /v1/monitor/{entity_id}
## Delete a monitor
Permanently removes a monitor and stops all future webhook notifications for that entity.
**Cost:** 0 credits
See the [Monitoring guide](/guide/monitoring) for a full overview of how monitoring works, including how to manage the monitor lifecycle.
### Entity ID
Pass the same `entity_id` that was used when creating the monitor — the company register ID (e.g. `DE-HRB-F1103-267645`) or the person UUID. Deletion is immediate and permanent. To resume monitoring the same entity you must create a new monitor.
Deletion cannot be undone. All preferences configured on the monitor are removed and no further notifications will be delivered for that entity.
### Use Cases
**Offboarding a client or counterparty** — When a business relationship ends, delete the corresponding monitor to stop receiving notifications for that entity and avoid unnecessary noise.
**Pruning stale monitors** — Periodically review your monitor list and remove entities that are no longer relevant to your business to keep your subscription list clean.
# List Monitors
Source: https://docs.openregister.de/endpoint/monitor-list
GET /v1/monitor
## List monitors
Returns all monitors created for the current API user.
**Cost:** 0 credits
See the [Monitoring guide](/guide/monitoring) for a full overview of how monitoring works, including webhook setup and preference options.
### Response
The response contains an `items` array. Each item represents one active or disabled monitor and includes:
| Field | Type | Description |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `entity_id` | string | The company register ID or person UUID being monitored |
| `entity_type` | string | `company` or `person` |
| `preferences` | array | The data categories this monitor is watching |
| `update_frequency` | string | How often the entity is checked for updates: `daily` or `weekly`. Always `weekly` for person monitors |
| `disabled` | boolean | Whether the monitor has been disabled by the system |
### The `disabled` flag
A monitor is marked `disabled: true` when your account is downgraded to a plan that no longer includes monitoring access. Disabled monitors are preserved so you do not lose your configuration, but they stop delivering notifications.
Monitors are **not** automatically re-enabled when you upgrade again — this is intentional to prevent unexpected billing. To re-enable a disabled monitor, contact the team at [founders@openregister.de](mailto:founders@openregister.de).
Use the list endpoint to check for disabled monitors after any plan change so you can act before missing notifications.
### Use Cases
**Audit active subscriptions** — Retrieve the full list of entities you are currently watching to verify coverage, identify gaps, or reconcile against your internal records.
**Detect disabled monitors** — Filter the response for `disabled: true` items to find monitors that have stopped delivering notifications due to a plan downgrade. Contact [founders@openregister.de](mailto:founders@openregister.de) to get them re-enabled.
**Reconcile with your database** — Periodically compare the list of monitors against your own data to identify entities that should no longer be monitored and clean them up with the delete endpoint.
# Person information
Source: https://docs.openregister.de/endpoint/person
GET /v1/person/{person_id}
## Get person information
Retrieve detailed information about a natural person including their name, date of birth, city of residence, age, and their roles across multiple companies. This endpoint aggregates data about a person's management positions, providing a complete profile of their business activities.
**Cost:** 10 credits
# Person holdings
Source: https://docs.openregister.de/endpoint/person-holdings
GET /v1/person/{person_id}/holdings
## Get person holdings
Retrieve all companies where a person holds ownership stakes. This endpoint provides a portfolio view showing the person's shareholdings across different companies, including ownership percentages. Use this to understand a person's business network and investment portfolio.
**Cost:** 10 credits
# Insolvency search
Source: https://docs.openregister.de/endpoint/search-insolvency
POST /v1/search/insolvency
## Search insolvency proceedings
Search all German insolvency proceedings — for companies and natural persons — sourced from the official insolvency announcements (Insolvenzbekanntmachungen). Combine a free-text query with structured filters to find exactly the proceedings you care about.
**Cost:** 10 credits per search
### Query and Filters
The free-text `query` matches debtor names, case numbers, administrator names, and courts. Filters narrow results by:
* **Proceeding attributes:** `current_status`, `proceeding_kind` (regular or consumer insolvency), `administration_kind` (external administration, self administration, protective shield), `insolvency_grounds`, `has_open_insolvency`
* **Debtor attributes:** `debtor_kind` (legal or natural person), `debtor_legal_form`
* **Location:** `court`, `city`
* **Dates (`YYYY-MM-DD`, range via `min`/`max`):** `opened_at`, `closed_at`, `last_event_at`, `claims_filing_deadline`
* **Entity links:** `company_id`, `person_id` — resolve a proceeding directly to a company or person in OpenRegister
See the [filtering guide](/filtering#insolvency-search-fields) for the full field list and filter types.
### Use Cases
**Risk Monitoring:** Screen your customer and supplier base for open insolvency proceedings. Filter by `has_open_insolvency = true` and `company_id` to check specific counterparties before extending credit.
**Distressed-Asset Sourcing:** Find newly opened proceedings in your target region or industry by filtering on `opened_at` ranges, `court`, and `proceeding_kind` — a reliable early signal for restructuring and acquisition opportunities.
**Claims Management:** Track `claims_filing_deadline` dates across proceedings you are involved in, so filing windows are never missed.
# Search by website URL
Source: https://docs.openregister.de/endpoint/search-lookup
GET /v0/search/lookup
## Find company by website URL
Find a company by providing its website URL. Our system analyzes the website and matches it to companies in our database. The response includes the company ID that you can use with other endpoints to retrieve detailed information like financials, shareholders, and ownership structure. This is useful for enriching web data with company information.
**Cost:** 10 credits
# Store credentials
Source: https://docs.openregister.de/endpoint/transparenzregister-credentials
POST /v1/transparenzregister/credentials
Store username and password credentials for accessing the Transparenzregister API.
These credentials will be used for subsequent requests to retrieve company documents.
Credential names are user-scoped; the reserved name `sandbox` cannot be used.
Credentials are validated against Transparenzregister before they are persisted.
## Store Transparenzregister credentials
Stores Transparenzregister login credentials so that subsequent extract requests can authenticate on your behalf.
Use the body field `name` to identify this credential set. If omitted, `name` defaults to `default`. You can store multiple named credential sets (e.g. per client). Submitting the same `name` again overwrites the stored credentials for that name without affecting extracts already in flight.
The reserved name `sandbox` **cannot** be used — it is reserved for test-mode extracts via `X-Credential-Name: sandbox` on the [order extract](/endpoint/transparenzregister-extract-create) endpoint. Using `sandbox` as a credential name returns `400`.
Your credentials are encrypted at rest. The plaintext values never touch our database — only encrypted ciphertext is persisted, and every decryption is logged and auditable.
### Responses
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `201` | Credentials stored successfully |
| `400` | Invalid body (e.g. reserved name `sandbox`, missing username/password) |
| `401` | Not authenticated, or Transparenzregister rejected the provided username/password |
| `402` | Transparenzregister API access requires a paid API plan — [contact us](mailto:founders@openregister.de) |
| `409` | Maximum number of stored credential sets reached for this account |
| `500` | Internal server error |
**Cost:** 0 credits
# Order extract
Source: https://docs.openregister.de/endpoint/transparenzregister-extract-create
POST /v1/transparenzregister/extracts
Submit a Transparenzregister extract request and return an extract resource with processing status.
Sandbox integration testing (recommended for all non-production testing):
- Send `X-Credential-Name: sandbox`.
- Do not send `company_id` (an empty body `{}` is valid).
- OpenRegister uses the Transparenzregister test environment and built-in test authentication.
- The request is submitted with the fixed test EKRN `DE727032388716`.
- The response has `company_id: null`.
Production usage:
- Always set `X-Credential-Name` to `default` or another stored credential name.
- `company_id` is required and must resolve to exactly one Transparenzregister legal entity.
## 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](/api/endpoint/transparenzregister-credentials)
2. Order an extract here with `company_id` (production) or sandbox mode (see below)
3. Poll the [get extract endpoint](/api/endpoint/transparenzregister-extract-get) 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
| 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.
# Get extract
Source: https://docs.openregister.de/endpoint/transparenzregister-extract-get
GET /v1/transparenzregister/extracts/{extract_id}
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 |
# Filtering Guide
Source: https://docs.openregister.de/filtering
Our [advanced search endpoint](/endpoint/filter-company) offers a flexible and powerful way to find specific companies. This guide explains the various filtering options available.
## Basic Structure
The core of the filtering mechanism is the `filters` array in the request body. Each object in this array represents a single filter condition and must contain a `field` and a corresponding value using one of the available filter types.
```json theme={"dark"}
{
"filters": [
{
"field": "status",
"value": "active"
}
]
}
```
## Free-Text Search Query
Besides structured filters, you can also perform a free-text search using the `query` field. This is useful for finding companies by name or previous names.
```json theme={"dark"}
{
"query": {
"value": "Descartes"
},
"filters": [
{
"field": "city",
"value": "Berlin"
}
]
}
```
This will search for companies with "Descartes" in their name or previous names and are located in Berlin.
## Examples
Here are a few examples of how you can combine different filters to achieve specific search results.
### All Restaurants
To find all companies in the restaurant industry, you can filter by the `industry_codes` field.
```json theme={"dark"}
{
"filters": [
{
"field": "industry_codes",
"value": "56.11"
}
]
}
```
### Newly Founded Companies
To find companies that were incorporated in the last week, you can use a range filter on the `incorporated_at` field.
```json theme={"dark"}
{
"filters": [
{
"field": "incorporated_at",
"min": "15-07-2024"
}
]
}
```
### High-Revenue Companies with a Large Workforce
To find companies with more than 100 employees and over 100 million EUR in revenue, you can combine two range filters. **Monetary filter values (revenue, balance\_sheet\_total, capital\_amount, etc.) are in cents** — 100 million EUR = 10,000,000,000 cents.
```json theme={"dark"}
{
"filters": [
{
"field": "employees",
"min": "100"
},
{
"field": "revenue",
"min": "10000000000"
}
]
}
```
### Companies in a Specific Location
To find all companies with a registered address in a specific postal code.
```json theme={"dark"}
{
"filters": [
{
"field": "zip",
"value": "10117"
}
]
}
```
### Companies with a Specific Legal Form and Capital
To find all GmbH companies with a capital of more than 1 million EUR. **Monetary filter values are in cents** — 1 million EUR = 100,000,000 cents.
```json theme={"dark"}
{
"filters": [
{
"field": "legal_form",
"value": "gmbh"
},
{
"field": "capital_amount",
"min": "100000000"
},
{
"field": "capital_currency",
"value": "EUR"
}
]
}
```
### Companies With or Without a Legal Entity Identifier (LEI)
Use `has_lei` with `value` `"true"` or `"false"` to restrict results to companies that have been indexed with a non-empty LEI (`true`) or without (`false`). Use `lei` with `value` for one LEI, or `values` for several (OR).
```json theme={"dark"}
{
"filters": [
{
"field": "has_lei",
"value": "true"
}
]
}
```
Match one or more exact LEIs (20-character GLEIF identifiers):
```json theme={"dark"}
{
"filters": [
{
"field": "lei",
"values": ["5493001HCMGWDQ4MX390", "529900T8BM49AURSDO55"]
}
]
}
```
### Companies with an Open Insolvency Proceeding
To find companies that currently have an open insolvency proceeding, opened since the start of 2026. The `insolvency_opened_at` range uses the `YYYY-MM-DD` format.
```json theme={"dark"}
{
"filters": [
{
"field": "has_open_insolvency",
"value": "true"
},
{
"field": "insolvency_opened_at",
"min": "2026-01-01"
}
]
}
```
You can also target specific stages of a proceeding, e.g. all companies in preliminary or opened proceedings:
```json theme={"dark"}
{
"filters": [
{
"field": "insolvency_stage",
"values": ["preliminary", "opened"]
}
]
}
```
### Owner-Managed Companies for Succession Planning
To find owner-managed businesses with an older owner - ideal for identifying succession opportunities.
```json theme={"dark"}
{
"filters": [
{
"field": "has_representative_owner",
"value": "true"
},
{
"field": "is_family_owned",
"value": "false"
},
{
"field": "youngest_owner_age",
"min": "60"
}
]
}
```
## Filterable Fields
You can filter on a wide range of fields, listed below in two groups: general company fields and financial indicator fields.
### Company Fields
**Important:** `capital_amount` uses values in **cents**, not euros.
| Field | Description |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | The current status of the company (e.g., `active`, `inactive`, `liquidation`). |
| `legal_form` | The legal form of the company (e.g., `gmbh`, `ag`). |
| `register_number` | The company's registration number. |
| `register_court` | The court where the company is registered. |
| `register_type` | The type of register (e.g., `HRB`, `HRA`). |
| `city` | The city where the company is located. |
| `active` | A boolean indicating if the company is active. |
| `incorporated_at` | The date of incorporation. |
| `purpose` | The business purpose of the company. |
| `zip` | The postal code of the company's address. |
| `address` | The full address of the company. |
| `industry_codes` | The company's industry codes (WZ2025). |
| `capital_amount` | The amount of the company's capital (in cents). |
| `capital_currency` | The currency of the company's capital. |
| `number_of_owners` | The number of company owners/shareholders. (enterprise only) |
| `has_sole_owner` | Boolean indicating if the company has only one owner. (enterprise only) |
| `has_representative_owner` | Boolean indicating if an owner is also in management (owner-managed). (enterprise only) |
| `is_family_owned` | Boolean indicating if the company is family-owned. (enterprise only) |
| `youngest_owner_age` | The age of the youngest owner/shareholder. (enterprise only) |
| `youngest_director_age` | The age of the youngest person currently in management (Geschäftsführer, Vorstand, board members, liquidators). Excludes Prokuristen and owners who hold no management role. (enterprise only) |
| `has_lei` | Boolean string `"true"` or `"false"`: company has a non-empty LEI indexed (`true`) or not (`false`). |
| `lei` | Legal Entity Identifier (GLEIF). Exact match via `value`, or `values` for multiple LEIs (OR). |
| `had_insolvency` | Boolean string `"true"` or `"false"`: company has ever had an insolvency proceeding. |
| `has_open_insolvency` | Boolean string `"true"` or `"false"`: company currently has an open insolvency proceeding. |
| `insolvency_stage` | Stage of the company's most relevant proceeding (e.g., `preliminary`, `opened`, `plan_supervised`, `lifted`, `discharge_granted`). Use `value`, or `values` for multiple stages (OR). |
| `insolvency_opened_at` | The date the insolvency proceeding was opened. Range via `min`/`max` in `YYYY-MM-DD` format (note: unlike `incorporated_at`). |
### Financial Indicator Fields
Every financial indicator can be used as a range filter via `min`/`max`, based on the company's most recent available fiscal year.
**Important:** All financial indicator fields use values in **cents**, not euros — except `employees`. Divide by 100 to convert to EUR.
| Field | Description |
| :------------------------- | :----------------------------------------------------------------------------------------- |
| `balance_sheet_total` | Balance sheet total (Bilanzsumme). |
| `revenue` | Revenue (Umsatzerlöse). |
| `net_income` | Net income (Jahresüberschuss). |
| `parent_net_income` | Net income attributable to the parent company. |
| `income_before_tax` | Income before taxes. |
| `income_after_tax` | Income after taxes. |
| `ebit` | Earnings before interest and taxes. |
| `ebitda` | Earnings before interest, taxes, depreciation, and amortization. |
| `employees` | The number of employees. |
| `equity` | Equity (Eigenkapital). |
| `cash` | Cash reserves. |
| `fixed_assets` | Fixed assets (Anlagevermögen). |
| `current_assets` | Current assets (Umlaufvermögen). |
| `intangible_assets` | Intangible assets (immaterielle Vermögensgegenstände). |
| `tangible_assets` | Tangible assets (Sachanlagen). |
| `financial_assets` | Financial assets (Finanzanlagen). |
| `real_estate` | Real estate (Grundstücke und Bauten). |
| `inventory` | Inventory (Vorräte). |
| `receivables` | Receivables (Forderungen). |
| `trade_receivables` | Trade receivables (Forderungen aus Lieferungen und Leistungen). |
| `active_accruals` | Prepaid expenses (aktive Rechnungsabgrenzungsposten). |
| `passive_accruals` | Deferred income (passive Rechnungsabgrenzungsposten). |
| `liabilities` | Liabilities (Verbindlichkeiten). |
| `other_liabilities` | Other liabilities (sonstige Verbindlichkeiten). |
| `bank_debt` | Liabilities to banks (Verbindlichkeiten gegenüber Kreditinstituten). |
| `trade_payables` | Trade payables (Verbindlichkeiten aus Lieferungen und Leistungen). |
| `shareholder_liabilities` | Liabilities to shareholders (Verbindlichkeiten gegenüber Gesellschaftern). |
| `affiliated_liabilities` | Liabilities to affiliated companies (Verbindlichkeiten gegenüber verbundenen Unternehmen). |
| `financial_debt` | Financial debt (Finanzverbindlichkeiten). |
| `provisions` | Provisions (Rückstellungen). |
| `other_provisions` | Other provisions (sonstige Rückstellungen). |
| `pension_provisions` | Pension provisions (Pensionsrückstellungen). |
| `capital_reserves` | Capital reserves (Kapitalrücklage). |
| `retained_earnings` | Retained earnings (Gewinnrücklagen). |
| `profit_carryforward` | Profit carried forward (Gewinnvortrag). |
| `materials` | Cost of materials (Materialaufwand). |
| `salaries` | Personnel expenses (Personalaufwand). |
| `operating_depreciation` | Depreciation and amortization on fixed assets (Abschreibungen). |
| `financial_depreciation` | Depreciation on financial assets (Abschreibungen auf Finanzanlagen). |
| `other_operating_income` | Other operating income (sonstige betriebliche Erträge). |
| `other_operating_expenses` | Other operating expenses (sonstige betriebliche Aufwendungen). |
| `interest_income` | Interest income (Zinserträge). |
| `interest_expense` | Interest expense (Zinsaufwendungen). |
| `commission_income` | Commission income (Provisionserträge). |
| `commission_expense` | Commission expense (Provisionsaufwendungen). |
| `taxes` | Income taxes (Steuern vom Einkommen und vom Ertrag). |
| `other_taxes` | Other taxes (sonstige Steuern). |
### Insolvency Search Fields
The [insolvency search](/endpoint/search-insolvency) (`POST /v1/search/insolvency`) supports its own set of filterable fields:
| Field | Description |
| :----------------------- | :--------------------------------------------------------------------------------------------------- |
| `current_status` | The current status of the proceeding (e.g., `preliminary`, `opened`, `lifted`, `discharge_granted`). |
| `has_open_insolvency` | Boolean indicating if the proceeding is currently open. |
| `proceeding_kind` | The kind of proceeding (`regular_insolvency`, `consumer_insolvency`). |
| `administration_kind` | The kind of administration (`external_administration`, `self_administration`, `protective_shield`). |
| `insolvency_grounds` | The legal grounds for the insolvency (e.g., `Zahlungsunfähigkeit`). |
| `debtor_kind` | The kind of debtor (`legal_person`, `natural_person`). |
| `debtor_legal_form` | The legal form of the debtor (e.g., `gmbh`). |
| `court` | The insolvency court handling the proceeding. |
| `city` | The city of the debtor. |
| `opened_at` | The date the proceeding was opened. |
| `closed_at` | The date the proceeding was closed. |
| `last_event_at` | The date of the most recent announcement. |
| `claims_filing_deadline` | The deadline for filing claims. |
| `company_id` | The OpenRegister company ID of the debtor. |
| `person_id` | The OpenRegister person ID of the debtor. |
**Note:** The insolvency date fields (`opened_at`, `closed_at`, `last_event_at`, `claims_filing_deadline`) support `min`/`max` ranges and use the `YYYY-MM-DD` format — unlike the company `incorporated_at` examples above.
## Filter Types
There are several ways to specify the filter value, depending on the desired comparison.
### Exact Match: `value`
For a simple exact match, use the `value` property.
```json theme={"dark"}
{
"field": "legal_form",
"value": "gmbh"
}
```
### Multiple Values: `values`
To match against a list of possible values, use the `values` array. This is useful for "OR" conditions.
```json theme={"dark"}
{
"field": "city",
"values": ["Berlin", "Hamburg", "München"]
}
```
### Keyword Matching: `keywords`
For text fields, `keywords` allows you to find records containing any of the specified words.
```json theme={"dark"}
{
"field": "zip",
"keywords": ["10117", "10119"]
}
```
### Range Filtering: `min` and `max`
For numerical and date fields, you can specify a range using `min` and `max`.
```json theme={"dark"}
{
"field": "employees",
"min": "10",
"max": "100"
}
```
You can also specify just a minimum or a maximum. For monetary fields, use cents (e.g. 1 million EUR = 100000000).
```json theme={"dark"}
{
"field": "revenue",
"min": "100000000"
}
```
### Date Formatting
When filtering by date, use the `DD-MM-YYYY` format.
```json theme={"dark"}
{
"field": "incorporated_at",
"min": "01-01-2020",
"max": "31-12-2021"
}
```
## Location Filtering
You can also filter companies based on their geographical location by providing a `location` object in the request body. This allows you to find companies within a certain radius of a given point.
The `location` object requires `latitude` and `longitude`, and optionally accepts a `radius` in kilometers.
```json theme={"dark"}
{
"location": {
"latitude": 52.5200,
"longitude": 13.4050,
"radius": 10
}
}
```
## Combining Filters
You can combine multiple filter objects in the `filters` array. These conditions are joined with an "AND" operator, meaning a company must satisfy all of them to be included in the results.
```json theme={"dark"}
{
"filters": [
{
"field": "legal_form",
"value": "gmbh"
},
{
"field": "employees",
"min": "50"
}
]
}
```
# Monitoring
Source: https://docs.openregister.de/guide/monitoring
Monitor companies and people for updates via webhook
## What is Monitoring?
The monitoring API lets you subscribe to changes on specific companies or persons. When the entity is updated in the official register, OpenRegister delivers a webhook notification to your configured endpoint — no polling required.
API monitors are completely separate from the Watchlist feature in the OpenRegister platform. They are independent systems and do not share state. Monitors created via the API only deliver webhooks to your configured endpoint; they do not appear in the platform Watchlist, and entries in your platform Watchlist do not trigger API webhooks.
## Getting Started
### Step 1: Configure your webhook URL
Before creating any monitors you must configure a webhook endpoint in your [OpenRegister dashboard](https://openregister.de/keys).
Your webhook endpoint must:
* Accept `POST` requests
* Return a `2xx` HTTP response within 15 seconds
* Be publicly reachable over HTTPS
### Step 2: Create a monitor
Call `POST /v1/monitor` with the entity you want to watch, its type, and the data categories (preferences) you care about. The monitor stays active and delivers notifications until you explicitly delete it.
```mermaid theme={"dark"}
flowchart LR
A["Create Monitor"] --> B[Entity updated in register]
B --> C[Webhook delivered to your URL]
C --> D{Still needed?}
D -->|Yes| B
D -->|No| E["Delete Monitor"]
```
## Receiving Webhooks
OpenRegister uses [Svix](https://www.svix.com) to deliver webhook notifications. Svix is a reliable webhook infrastructure service that handles signing, retries, and delivery guarantees on your behalf. For a full overview of consuming Svix-powered webhooks, see the [Svix receiving introduction](https://docs.svix.com/receiving/introduction).
### Delivery behaviour
* OpenRegister sends a `POST` request to your configured endpoint with a JSON body.
* Your endpoint must respond with a `2xx` status code within **15 seconds**. If it does not, Svix treats the delivery as failed and retries automatically with exponential back-off.
* Disable **CSRF protection** for your webhook route — the requests come from Svix servers, not a browser, so CSRF tokens are never present.
### Webhook headers
Every delivery includes three Svix-specific headers used for signature verification:
| Header | Description |
| ---------------- | -------------------------------------------------------------------------- |
| `svix-id` | Unique message ID. Identical across all retry attempts for the same event. |
| `svix-timestamp` | Unix timestamp (seconds) of when the webhook was sent. |
| `svix-signature` | One or more base64-encoded HMAC-SHA256 signatures. |
## Verifying Webhook Signatures
Verifying the signature on each incoming webhook is important for two reasons:
1. **Authenticity** — confirms the request genuinely came from OpenRegister and not an attacker who found your endpoint URL.
2. **Replay protection** — Svix embeds a timestamp in every signature and the official libraries automatically reject messages with a timestamp more than five minutes old, preventing replay attacks.
For a deeper explanation, see [Why Verify Webhooks](https://docs.svix.com/receiving/verifying-payloads/why) in the Svix docs.
### How to verify
Install the Svix library for your language and call the verify method on the webhook instance. Find your signing secret in your [OpenRegister dashboard](https://openregister.de/keys) under the webhook endpoint you created.
Always pass the **raw** (unparsed) request body to `verify`. If your framework parses the JSON and you pass a re-serialised string, the cryptographic signature will not match and verification will fail.
```typescript TypeScript (Node.js / Next.js) theme={"dark"}
import { Webhook } from "svix";
const secret = process.env.WEBHOOK_SECRET!; // whsec_...
export async function POST(req: Request) {
const svixId = req.headers.get("svix-id") ?? "";
const svixTimestamp = req.headers.get("svix-timestamp") ?? "";
const svixSignature = req.headers.get("svix-signature") ?? "";
const body = await req.text(); // raw body — do not parse first
const wh = new Webhook(secret);
let event;
try {
event = wh.verify(body, {
"svix-id": svixId,
"svix-timestamp": svixTimestamp,
"svix-signature": svixSignature,
});
} catch {
return new Response("Bad Request", { status: 400 });
}
// Process event...
return new Response("OK", { status: 200 });
}
```
```python Python (FastAPI) theme={"dark"}
from fastapi import Request, Response, status
from svix.webhooks import Webhook, WebhookVerificationError
secret = "whsec_..." # from your dashboard
async def webhook_handler(request: Request, response: Response):
headers = request.headers
payload = await request.body() # raw bytes — do not parse first
try:
wh = Webhook(secret)
event = wh.verify(payload, headers)
except WebhookVerificationError:
response.status_code = status.HTTP_400_BAD_REQUEST
return
# Process event...
```
```go Go theme={"dark"}
package main
import (
"io"
"net/http"
svix "github.com/svix/svix-webhooks/go"
)
const secret = "whsec_..." // from your dashboard
func webhookHandler(w http.ResponseWriter, r *http.Request) {
payload, err := io.ReadAll(r.Body)
if err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
wh, err := svix.NewWebhook(secret)
if err != nil {
w.WriteHeader(http.StatusInternalServerError)
return
}
err = wh.Verify(payload, r.Header)
if err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
// Process event...
w.WriteHeader(http.StatusNoContent)
}
```
For examples in Python (Django/Flask), Ruby, PHP, Rust, and others, see the [full Svix verification guide](https://docs.svix.com/receiving/verifying-payloads/how).
## Testing with Svix Play
[Svix Play](https://play.svix.com) is a free, no-signup webhook debugger. Use it during development to inspect incoming payloads before you have a publicly reachable endpoint.
**To get started:**
1. Go to [play.svix.com](https://play.svix.com) — you'll receive a unique URL instantly.
2. Set that URL as your webhook endpoint in your [OpenRegister dashboard](https://openregister.de/keys).
3. Trigger an event (e.g. create a monitor and wait for an update, or replay a test event). Every delivery appears in the Svix Play UI with full headers, body, and response details.
### Relay to localhost with the Svix CLI
For end-to-end local testing, install the [Svix CLI](https://github.com/svix/svix-cli) and run:
```bash theme={"dark"}
svix listen http://localhost:8080/webhook
```
The CLI prints a public `play.svix.com` URL. Paste it into your dashboard as the endpoint and all deliveries are forwarded to your local server in real time.
### Simulating failures
Append the `force_status_code` query parameter to your Svix Play URL to make it return a specific error code. This lets you verify that OpenRegister's retry logic works end-to-end:
```text theme={"dark"}
https://api.play.svix.com/api/v1/in/{your-token}/?force_status_code=500
```
For the full set of advanced options — echo mode, random failure rate, programmatic history API — see the [Svix Play docs](https://docs.svix.com/play).
## Pricing
| Action | Cost |
| ----------------------- | -------------------- |
| Create a weekly monitor | 25 credits |
| Create a daily monitor | 50 credits |
| Active weekly monitor | 25 credits per month |
| Active daily monitor | 50 credits per month |
| List monitors | 0 credits |
| Delete a monitor | 0 credits |
[Contact us](mailto:founders@openregister.de) if you have questions about pricing.
## Update Frequency
How often OpenRegister checks an entity for changes depends on the entity type:
**Companies** — checked for changes at least once per week by default. For faster detection, set `update_frequency: daily` when creating the monitor to have the company checked once per day. Daily monitors are billed at a premium (50 credits at creation and per month instead of 25).
**Persons** — all entities are fully checked at least once per month. When a person incorporates a new company, that change is detected daily. Person monitors do not support the `update_frequency` field; including it returns a `400 Bad Request`.
Need even faster updates? [Contact us](mailto:founders@openregister.de) to discuss custom frequencies.
## Preferences
Preferences control which data categories trigger a notification. You must specify at least one preference when creating a monitor, and all preferences must match the `entity_type`.
### Company preferences (`entity_type: company`)
| Preference | What triggers a notification |
| ---------------- | -------------------------------------------------------------------------------- |
| `basic` | Core firmographic data — name, registered address, legal form, or company status |
| `representation` | Directors, officers, managing partners, or authorised signatories |
| `financials` | Annual accounts or financial statements filed |
| `documents` | New documents or publications filed with the register |
| `ownership` | Direct owners (shareholders) of the company |
| `holdings` | Companies in which this company holds a stake |
| `insolvencies` | Insolvency proceedings of the company |
### Person preferences (`entity_type: person`)
| Preference | What triggers a notification |
| ---------------------- | ------------------------------------------------------------- |
| `management_positions` | Board or management roles the person holds across any company |
| `holdings` | Companies in which this person holds a stake |
| `insolvencies` | Insolvency proceedings of the person |
Passing a preference that does not apply to the given `entity_type` returns a `400 Bad Request` validation error. For example, you cannot use `representation` when monitoring a person.
## Use Cases
**Compliance & KYC refresh** — Monitor the companies and persons in your portfolio. When a director change, ownership update, or new financial filing is detected you receive an immediate notification, letting you trigger a re-verification workflow without scheduling periodic re-checks.
**Portfolio monitoring** — Subscribe to `basic` and `representation` changes across all portfolio companies to track legal form conversions, address moves, insolvency filings, or management changes as they appear in the register.
**Ownership chain alerting** — Combine `ownership` and `holdings` preferences to detect restructuring events in complex ownership chains. Useful for banks, investors, and compliance teams that need to know when a beneficial ownership chain changes.
**Due diligence pipelines** — Automatically re-fetch company data and refresh documents when you receive a `documents` or `financials` notification, ensuring your internal records stay in sync with the official register.
## Managing Monitors
Use the three monitor endpoints together to manage your subscriptions:
| Action | Endpoint |
| ----------------- | ------------------------------------------------------------ |
| Create a monitor | [`POST /v1/monitor`](/endpoint/monitor-create) |
| List all monitors | [`GET /v1/monitor`](/endpoint/monitor-list) |
| Delete a monitor | [`DELETE /v1/monitor/{entity_id}`](/endpoint/monitor-delete) |
### The `disabled` flag
Each monitor item in the list response includes a `disabled` boolean. A monitor is disabled when your account is downgraded to a plan that no longer includes monitoring access. Disabled monitors are preserved in your list so you do not lose your configuration, but they stop delivering notifications.
Monitors are **not** automatically re-enabled on upgrade — this is intentional to prevent unexpected billing. To re-enable a disabled monitor, contact [founders@openregister.de](mailto:founders@openregister.de).
# CLI
Source: https://docs.openregister.de/integration/cli
Official CLI for the OpenRegister API
The OpenRegister CLI is the official command-line interface for the OpenRegister REST API.
## Installation
Requires Go 1.22 or later.
```bash theme={"dark"}
go install 'github.com/oregister/openregister-cli/cmd/openregister@latest'
```
The binary is placed in your Go bin directory after installation:
* **Default location:** `$HOME/go/bin` (or `$GOPATH/bin` if `GOPATH` is set)
* **Check your path:** Run `go env GOPATH` to see the base directory
If the `openregister` command is not found after installation, add the Go bin directory to your `PATH`:
```bash theme={"dark"}
export PATH="$PATH:$(go env GOPATH)/bin"
```
```bash theme={"dark"}
export PATH="$PATH:$(go env GOPATH)/bin"
```
## Usage
The CLI follows a resource-based command structure:
```bash theme={"dark"}
openregister [resource] [flags...]
```
Example — fetch company details:
```bash theme={"dark"}
openregister company get-details-v1 \
--api-key 'My API Key' \
--company-id DE-HRB-F1103-267645
```
For details about any command, use the `--help` flag:
```bash theme={"dark"}
openregister --help
openregister company --help
```
## Environment Variables
| Variable | Description | Required |
| ---------------------- | ------------------------------------------------------------------ | -------- |
| `OPENREGISTER_API_KEY` | Your API key, sent as a Bearer token in the `Authorization` header | Yes |
## Global Flags
| Flag | Description |
| ------------------- | ------------------------------------------------------------------------------------- |
| `--api-key` | API key (can also be set with `OPENREGISTER_API_KEY`) |
| `--help` | Show command line usage |
| `--debug` | Enable debug logging, including HTTP request/response details |
| `--version`, `-v` | Show the CLI version |
| `--base-url` | Use a custom API backend URL |
| `--format` | Output format: `auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml` |
| `--format-error` | Output format for errors: `auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml` |
| `--transform` | Transform output using [GJSON](https://github.com/tidwall/gjson) syntax |
| `--transform-error` | Transform error output using GJSON syntax |
# MCP
Source: https://docs.openregister.de/integration/mcp
Integrate the OpenRegister API into your AI assistant or application
The OpenRegister MCP Server enables AI assistants and agent frameworks to interact with the OpenRegister API through the [Model Context Protocol](https://modelcontextprotocol.io/introduction). It exposes company search and data retrieval as tools that any MCP-compatible client can use.
There are two ways to connect: the **remote MCP server** (no local setup needed) or the **local npm package** (for full control).
## Remote MCP Server
The easiest way to connect — no local installation required. The server handles authentication via OAuth when you connect.
| Transport | Endpoint |
| --------------- | --------------------------------- |
| SSE (legacy) | `https://mcp.openregister.de/sse` |
| Streamable HTTP | `https://mcp.openregister.de/mcp` |
### Use in AI Assistants
Connect directly in your browser — no terminal or config files needed.
Claude.ai supports MCP servers natively through its Integrations settings.
1. Open [Claude.ai](https://claude.ai) and go to **Settings → Integrations**
2. Click **+ Add** or **+ Add Custom Integration**
3. Enter the URL: `https://mcp.openregister.de/sse`
4. Follow the authorization flow to connect your API key
ChatGPT supports MCP servers via its Connectors feature (requires Developer Mode).
1. Open [ChatGPT](https://chatgpt.com) and go to **Settings → Advanced**
2. Enable **Developer Mode**
3. Go to **Settings → Connectors** → **+ Add Custom Connector**
4. Enter the URL: `https://mcp.openregister.de/mcp`
5. Follow the authorization flow to connect your API key
### Use in Developer Tools
Edit a config file and restart your client. Requires [Node.js 18+](https://nodejs.org).
Edit your Claude Desktop configuration file:
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={"dark"}
{
"mcpServers": {
"openregister": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.openregister.de/sse"]
}
}
}
```
Restart Claude Desktop. Look for the hammer icon (🔨) to confirm the connection.
Edit `~/.cursor/mcp.json`:
```json theme={"dark"}
{
"mcpServers": {
"openregister": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.openregister.de/sse"]
}
}
}
```
Restart Cursor to activate the connection.
### Build with It
Use the MCP server as a tool source in your own AI agents and pipelines.
```python theme={"dark"}
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
async def main():
async with MCPServerStreamableHttp(
url="https://mcp.openregister.de/mcp",
headers={"Authorization": "Bearer YOUR_API_KEY"},
) as mcp_server:
agent = Agent(
name="company-researcher",
instructions="Use OpenRegister tools to look up German company data.",
mcp_servers=[mcp_server],
)
result = await Runner.run(agent, "Find information about Trade Republic Bank GmbH")
print(result.final_output)
```
```typescript theme={"dark"}
import { createOpenAI } from "@ai-sdk/openai";
import { experimental_createMCPClient, generateText } from "ai";
const mcpClient = await experimental_createMCPClient({
transport: {
type: "sse",
url: "https://mcp.openregister.de/sse",
headers: { Authorization: "Bearer YOUR_API_KEY" },
},
});
const tools = await mcpClient.tools();
const { text } = await generateText({
model: createOpenAI({ apiKey: process.env.OPENAI_API_KEY })("gpt-4o"),
tools,
prompt: "Find information about Trade Republic Bank GmbH",
});
await mcpClient.close();
```
The remote MCP server requires Node.js 18 or higher for `mcp-remote`. If you encounter connection issues, try clearing the MCP auth cache: `rm -rf ~/.mcp-auth`
***
## Local MCP Server (npm)
Run the MCP server locally with your API key for full control.
**Repository**: [openregister-typescript/packages/mcp-server](https://github.com/oregister/openregister-typescript/tree/main/packages/mcp-server)
```bash theme={"dark"}
export OPENREGISTER_API_KEY="your-api-key"
npx -y openregister-mcp@latest
```
For MCP clients that use configuration JSON (like Claude Desktop), add this configuration:
```json theme={"dark"}
{
"mcpServers": {
"openregister": {
"command": "npx",
"args": ["-y", "openregister-mcp", "--client=claude", "--tools=all"],
"env": {
"OPENREGISTER_API_KEY": "your-api-key"
}
}
}
}
```
## Authentication
Set your OpenRegister API key as an environment variable:
```bash theme={"dark"}
export OPENREGISTER_API_KEY="your-api-key-here"
```
Get your API key from [OpenRegister Keys](https://openregister.de/keys).
For more detailed configuration options and advanced usage, see the [full repository documentation](https://github.com/oregister/openregister-typescript/tree/main/packages/mcp-server).
# n8n
Source: https://docs.openregister.de/integration/n8n
Use the OpenRegister API in your n8n workflows with the official verified node
## Overview
n8n is a workflow automation tool to connect services and build automations without writing code. The official OpenRegister node for n8n lets you search for companies, fetch company details, owners, holdings, financials, and documents directly inside your flows.
OpenRegister is available as an **official verified node** on n8n, meaning it's pre-installed and ready to use on n8n Cloud without any manual installation required.
* n8n Integration: [n8n.io/integrations/openregister](https://n8n.io/integrations/openregister/)
* Repository: [oregister/n8n-nodes-openregister](https://github.com/oregister/n8n-nodes-openregister)
* Example workflow: [openregister-example-workflow.json](https://github.com/oregister/n8n-nodes-openregister/blob/master/examples/openregister-example-workflow.json)
## Prerequisites
* An OpenRegister API key — get one in the [OpenRegister Keys](https://openregister.de/keys)
* For n8n Cloud: No additional prerequisites (node is pre-installed)
* For self-hosted n8n: Admin approval for verified nodes (one-time setup)
## Installation
### n8n Cloud (Hosted)
**No installation required!** The OpenRegister node is pre-installed on all n8n Cloud instances. Simply search for "OpenRegister" in the node palette and start using it.
### Self-Hosted n8n
The verified node needs a one-time setup by an instance owner:
1. In n8n, go to Settings → Community Nodes.
2. Enable verified nodes if not already enabled.
3. The OpenRegister node will be available to all users on the instance.
Alternatively, you can install the community package manually:
1. Go to Settings → Community Nodes → Install.
2. Enter the package name: `@oregister/n8n-nodes-openregister` and confirm.
3. Restart n8n if prompted.
## Authentication
1. In n8n, open Credentials → New → search for “OpenRegister”.
2. Paste your API key into the API Key field.
3. Save the credentials and select them in your OpenRegister nodes.
## Available nodes
The package provides nodes that map to common OpenRegister API endpoints. Typical actions include:
* Company search (simple)
* Company information
* Company owners
* Company holdings
* Company financials
Exact inputs and outputs are documented in each node within n8n and align with the API responses described in this documentation.
## Example: Enrich companies with details and financials
This example shows a simple flow to search a company and fetch its details and financials.
1. Add a Trigger (e.g., Manual Trigger).
2. Add “OpenRegister: Search Companies” with a query (e.g., “Miles Mobility”).
3. Add “OpenRegister: Get Company” and set Company ID to the first result from step 2.
4. (Optional) Add “OpenRegister: Get Financials” using the Company ID from step 3.
5. Continue your flow (e.g., store data, send notification, or enrich a CRM).
To try a ready‑made flow, import the example workflow from the repository’s examples folder linked above.
## Troubleshooting
* 401 Unauthorized: Check that your credentials are set and selected in the node.
* 402 Payment Required: Your account lacks credits for this endpoint. Top up credits.
* 429 Too Many Requests: You have hit a rate limit. Add a Wait node or lower concurrency.
* 5xx Server Error: Retry with a Wait/Retry pattern. If persistent, contact support.
## Links
* Keys: [openregister.de/keys](https://openregister.de/keys)
* API docs home: [docs.openregister.de](https://docs.openregister.de)
* n8n nodes repository: [oregister/n8n-nodes-openregister](https://github.com/oregister/n8n-nodes-openregister)
# SDKs
Source: https://docs.openregister.de/integration/sdks
Official SDKs for the OpenRegister API
We provide official SDKs for TypeScript, Go, and Python to make it easy to integrate with the OpenRegister API. These SDKs are published and maintained by our team.
### Python
* [openregister-sdk](https://pypi.org/project/openregister-sdk/) - Official Python SDK
```bash theme={"dark"}
uv add openregister-sdk
```
```bash theme={"dark"}
pip install openregister-sdk
```
```python theme={"dark"}
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
response = client.search.find_companies()
print(response.results)
```
### TypeScript/JavaScript
* [openregister](https://www.npmjs.com/package/openregister) - Official TypeScript/JavaScript SDK
```bash theme={"dark"}
npm install openregister
```
```bash theme={"dark"}
pnpm add openregister
```
```bash theme={"dark"}
bun add openregister
```
```typescript theme={"dark"}
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const response = await client.search.findCompanies();
console.log(response.results);
```
### Go
* [github.com/oregister/openregister-go](https://github.com/oregister/openregister-go) - Official Go SDK
```bash theme={"dark"}
go get github.com/oregister/openregister-go
```
```go theme={"dark"}
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
response, err := client.Search.FindCompanies(context.TODO(), openregister.SearchFindCompaniesParams{})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Results)
}
```
# Zapier
Source: https://docs.openregister.de/integration/zapier
Use the OpenRegister API in your Zapier workflows with official actions
## Overview
Zapier lets you connect apps and automate workflows without code. The OpenRegister Zapier integration provides actions to search companies and fetch company data (details, owners, holdings, financials, and documents) so you can enrich, route, and process data inside your Zaps.
The OpenRegister integration is **publicly available** to all Zapier users and can be found directly in the Zapier app directory.
* Zapier Integration: [zapier.com/apps/openregister/integrations](https://zapier.com/apps/openregister/integrations)
## Prerequisites
* An OpenRegister API key — get one in the [OpenRegister Keys](https://openregister.de/keys)
* A Zapier account (free or paid)
## Authentication
OpenRegister uses API key authentication. Create a connection when adding your first OpenRegister action:
1. In a Zap, add an "OpenRegister" action.
2. When prompted to "Choose account", click "Connect a new account".
3. Paste your API key into the API Key field and confirm.
4. The connection will be reused across OpenRegister steps.
If you need an API key, see the [Authentication guide](/authentication).
## Available actions
Actions map to common OpenRegister API endpoints. Typical actions include:
* Company search (simple)
* Get company information
* Get company owners
* Get company holdings
* Get company financials
Each action's inputs and outputs are documented in Zapier and align with the responses described in this API documentation.
## Example: Search and enrich a company
This example searches a company name, then fetches details and financials.
1. Trigger: choose any trigger (e.g., Schedule → Every day).
2. Action: OpenRegister → Search Companies. Set "Query" (e.g., "Miles Mobility").
3. Action: OpenRegister → Get Company. Set "Company ID" from step 2's first result.
4. (Optional) Action: OpenRegister → Get Financials. Set "Company ID" from step 3.
5. Continue your Zap (e.g., filter, store to Airtable/Sheets/DB, send a notification, enrich a CRM).
## Troubleshooting
* 401 Unauthorized: Reconnect the OpenRegister account and verify the API key.
* 402 Payment Required: Your account lacks credits for this endpoint. Top up credits.
* 429 Too Many Requests: You hit a rate limit. Add a delay or reduce concurrency.
* 5xx Server Error: Retry with Zapier's built‑in retry/delay. If persistent, contact support.
## Links
* Keys: [openregister.de/keys](https://openregister.de/keys)
* Zapier Integration: [zapier.com/apps/openregister/integrations](https://zapier.com/apps/openregister/integrations)
* API docs home: [docs.openregister.de](https://docs.openregister.de)
# Introduction
Source: https://docs.openregister.de/introduction
Getting started with the OpenRegister API
## Welcome to OpenRegister
Get instant access to data on 4+ million German companies from official sources. Search for companies, check ownership structures, view financials, and retrieve official documents - all through a simple API.
## Getting Started
Ready to start? Check out our [Quickstart Guide](/quickstart) to get up and running in minutes.
1. [Sign up](https://openregister.de) and grab your API key (no credit card required)
2. Start with 500 free credits per month
3. Follow the [Quickstart](/quickstart) to integrate
## What You Can Do
**Company Information** - Names, registration details, management teams, addresses, and contact info
**Find Companies** - Search by name, website, or location. Filter by industry, size, and legal form
**Ownership** - See who owns what, track beneficial owners, explore corporate structures
**Financials** - Balance sheets, revenue, and key metrics from published reports
**Documents** - Official register documents directly from the source
## Popular Use Cases
Companies use OpenRegister for **compliance and KYC**, **sales intelligence**, **due diligence**, **market research**, and **legal services**. If you work with German companies, we probably have the data you need.
## Need Help?
Questions? Want to discuss your use case? Just reach out at [founders@openregister.de](mailto:founders@openregister.de). We're here to help you succeed.
## Data Sources
Access three comprehensive data sources through our API:
Official register data for 4+ million companies - management, ownership, registration details, and documents
Financial statements and reports - balance sheets, revenue, and key metrics published by companies
Real-world contact details - emails, phone numbers, and social media profiles from company websites
# Pricing
Source: https://docs.openregister.de/pricing
Pricing for the OpenRegister API
## Credit-Based Pricing
The OpenRegister API uses a credit-based pricing model. Each API call consumes a certain number of credits depending on the endpoint and parameters used. This provides transparent, predictable costs that scale with your usage.
## Credit Costs by Endpoint
| Endpoint Type | Base Cost | With Realtime |
| ---------------------------------------------------------------------------------- | ---------- | ------------- |
| [Autocomplete Search](/endpoint/autocomplete-company) | 1 credit | N/A |
| [Advanced Filter Search](/endpoint/filter-company) (Company/Person) | 10 credits | N/A |
| [Company Details](/endpoint/company) | 10 credits | 20 credits |
| [Company Owners](/endpoint/company-owners) | 10 credits | 20 credits |
| [Company Historical Owners](/endpoint/company-historical-owners) | 25 credits | N/A |
| [Company Holdings](/endpoint/company-holdings) | 10 credits | N/A |
| [Company Financials](/endpoint/company-financials) | 10 credits | N/A |
| [Company UBO](/endpoint/company-ubo) | 25 credits | N/A |
| [Person Details](/endpoint/person) | 10 credits | N/A |
| [Person Holdings](/endpoint/person-holdings) | 10 credits | N/A |
| [Documents](/endpoint/document-realtime) | 10 credits | N/A |
| [Create Monitor](/endpoint/monitor-create) (weekly) | 25 credits | N/A |
| [Create Monitor](/endpoint/monitor-create) (daily) | 50 credits | N/A |
| [List Monitors](/endpoint/monitor-list) | 0 credits | N/A |
| [Delete Monitor](/endpoint/monitor-delete) | 0 credits | N/A |
| Active weekly monitor (monthly) | 25 credits | N/A |
| Active daily monitor (monthly) | 50 credits | N/A |
| [Store Transparenzregister credentials](/endpoint/transparenzregister-credentials) | 0 credits | N/A |
| [Order Transparenzregister extract](/endpoint/transparenzregister-extract-create) | 25 credits | N/A |
| [Get Transparenzregister extract](/endpoint/transparenzregister-extract-get) | 0 credits | N/A |
### Monitoring
[Monitoring](/guide/monitoring) is available on Pro Plan and above. Each active monitor costs 25 credits per month with the default weekly update frequency, or 50 credits per month for company monitors created with `update_frequency: daily`. See the [Create Monitor](/endpoint/monitor-create) endpoint for details.
### Realtime Parameter
For select endpoints (Company Details and Company Owners), you can add `realtime=true` to fetch data directly from the Handelsregister in real-time. This ensures you get the most current information available and costs an additional 10 credits.
### Transparenzregister
[Transparenzregister](/api/transparenzregister-api) access is available on paid API plans only. Ordering an extract costs 25 credits; polling the result and downloading documents are free. Sandbox extracts (`X-Credential-Name: sandbox`) cost 0 credits and do not count toward any limits.
Default limits per account:
| Limit | Default |
| --------------------------------------- | ------- |
| Stored credential sets | 1 |
| Production extracts per rolling 30 days | 30 |
Sandbox traffic does not count toward the extract quota. [Email us](mailto:founders@openregister.de) if you need higher limits.
## Pricing Plans
### Free Plan
* **500 credits per month** included
* Credits are consumed per request based on the credit costs above
* Perfect for testing and small-scale integrations
* No credit card required
### Pro Plan
* **5,000 credits per month** included
* Additional credits at **€0.01 per credit**
* [Sign up](https://openregister.de/pricing)
### Business Plan
* **30,000 credits per month** included
* Additional credits at **€0.01 per credit**
* [Sign up](https://openregister.de/api)
### Volume Discounts
For high-volume usage, we offer custom pricing with volume discounts. If you need more than 50,000 credits per month, contact us at [founders@openregister.de](mailto:founders@openregister.de) to discuss pricing tailored to your needs.
## Integration Support
We want to help you succeed with your integration. If you're building a production integration and need additional credits for testing and development, we're happy to support you.
**Reach out to us at [founders@openregister.de](mailto:founders@openregister.de)** and let us know:
* What you're building
* Your expected usage patterns
We'll work with you to ensure you have the resources needed to build and test your integration properly.
## Tracking Your Usage
Monitor your credit consumption and view detailed usage statistics in real-time through your [API Dashboard](https://openregister.de/keys).
# Quickstart
Source: https://docs.openregister.de/quickstart
Get started with the OpenRegister API in minutes
OpenRegister provides multiple integration options to fit your technical setup and use case. Whether you're building a custom application, automating workflows, or adding AI capabilities, we have you covered.
## Set Up with an AI Agent
The fastest way to integrate: paste this prompt into Claude Code, Cursor, or any coding agent, and it will handle the setup for you — API key configuration, SDK installation, and a verified first request.
```text theme={"dark"}
Add OpenRegister to my app: openregister.de/skill.md
```
## Choose Your Integration
Official libraries for Python, TypeScript/JavaScript, and Go
Verified node for workflow automation without code
Pre-built actions to connect with 6,000+ apps
Enable AI assistants to query German company data
## Choosing the Right Integration
### For Developers
**Use our SDKs** if you're building a custom application and want:
* Full type safety and autocompletion
* Native language integration
* Complete control over API calls
Available in **Python**, **TypeScript/JavaScript**, and **Go**.
[View SDK Documentation →](/integration/sdks)
### For No-Code Automation
**Use n8n or Zapier** if you want to:
* Automate workflows without writing code
* Connect OpenRegister with other tools (CRMs, databases, spreadsheets)
* Build data enrichment pipelines
Both platforms offer visual workflow builders with pre-built OpenRegister actions.
[n8n Documentation →](/integration/n8n) | [Zapier Documentation →](/integration/zapier)
### For AI Assistants
**Use the MCP Server** if you want to:
* Enable AI assistants like Claude to query company data
* Build AI-powered tools with access to German company information
* Integrate with Model Context Protocol-compatible clients
[MCP Documentation →](/integration/mcp)
### Direct REST API
**Use the REST API directly** if you:
* Need maximum flexibility
* Work in a language without an official SDK
* Prefer making raw HTTP requests
All SDKs and integrations are built on top of our REST API.
[API Reference →](/api-reference)
## Authentication
All integration methods require an API key. Get yours in under a minute:
1. Create an account at [openregister.de](https://openregister.de)
2. Go to [API Keys](https://openregister.de/keys)
3. Generate your key
The free plan includes **500 credits per month** - perfect for testing.
[Authentication Guide →](/authentication)
## Need Help?
* Check our [API Reference](/endpoint/company) for endpoint details
* Review [pricing and credit costs](/pricing)
* Contact us at [founders@openregister.de](mailto:founders@openregister.de)
# Bundesanzeiger
Source: https://docs.openregister.de/sources/bundesanzeiger
The OpenRegister API provides comprehensive access to financial data from the German Bundesanzeiger.
The Bundesanzeiger (Federal Gazette) is the official publication platform where German companies publish their annual financial statements when legally required. Our API provides structured access to this financial data, making it easy to analyze company financials and track performance over time.
## What You Get
* **Complete balance sheets** - Detailed asset and liability breakdowns
* **Income statements** - Revenue, expenses, and profitability data
* **Key financial indicators** - Balance sheet total, revenue, net income, equity, cash, employees, and more
* **Multi-year data** - Track trends and compare financial performance over time
* **Structured format** - JSON data instead of PDF documents for easy automated analysis
Coverage includes **hundreds of thousands of German companies** that publish their financials. Not all companies are required to publish financials - publication requirements depend on company size and legal form. Generally, medium to large companies must publish detailed statements.
## Use Cases
**Credit Assessment** - Banks, suppliers, and financial institutions analyze financial health, liquidity ratios, and debt levels to make credit decisions and set credit limits.
**Investment Research** - Investors and analysts identify financially strong companies, analyze profitability trends, and compare companies within industries.
**Market Analysis** - Consultants and researchers benchmark companies against peers, identify industry trends, and segment markets by financial characteristics like revenue or employee ranges.
## API Endpoints
Access key financial indicators
Access detailed financial reports including balance sheet & income statement
## Update Frequency
* **Source**: bundesanzeiger.de (official Federal Gazette)
* **Updates**: Daily
* Financial statements are added as companies publish them in the Bundesanzeiger
# Handelsregister
Source: https://docs.openregister.de/sources/handelsregister
The OpenRegister API provides comprehensive access to data from the German Handelsregister.
The German Handelsregister (Commercial Register) is the official public register maintained by local courts for all commercial entities in Germany. Our API provides programmatic access to this register data, allowing you to search, retrieve, and monitor company information at scale.
## What You Get
* **Company registration details** - Register number, court, legal form, and registration dates
* **Management information** - All legal representatives (Geschäftsführer, Vorstände, etc.)
* **Ownership structures** - Complete shareholder information for applicable legal forms
* **Historical changes** - Track how companies have evolved over time
* **Official documents** - Company extracts, shareholder lists, and articles of association
* **Real-time data** - Request the most current information directly from the register
Access to **over 4 million registered German companies** across all 16 federal states and all register courts.
## Use Cases
**Legal & Compliance** - Law firms, notaries, and compliance officers verify company information, retrieve official documents, and perform due diligence checks for client onboarding and transactions.
**Business Intelligence** - Sales teams and business developers identify prospects, verify business partners, and research market segments using advanced company filters and ownership data.
**Financial Services** - Banks and financial institutions automate KYC processes, assess creditworthiness using register data, and monitor corporate structures for risk management.
## API Endpoints
Search and filter companies by name, location, legal form, registration date, and more
Retrieve comprehensive company information including management, registration details, and history
Access complete ownership structures with shareholder names, shares, and participation percentages
Discover all investments and subsidiaries held by a company
Request and download official documents directly from the register on demand
Identify the natural persons who ultimately own or control the company
## Update Frequency
* **Source**: handelsregister.de (official German Commercial Register)
* **Regular updates**: At least once per month
* **Newly founded companies**: Added within **24 hours** of registration
## Supported Legal Forms & Register Types
Our API supports all German legal entities:
* **GmbH** ("gmbh") - Limited liability company
* **gGmbH** ("ggmbh") - Non-profit GmbH
* **KG** ("kg") - Limited partnership
* **KGaA** ("kgaa") - Partnership limited by shares
* **GbR** ("gbr") - Civil law partnership
* **eG** ("eg") - Registered cooperative
* **OHG** ("ohg") - General partnership
* **e.K.** ("ek") - Registered merchant
* **SE** ("se") - European company
* **SCE** ("sce") - European cooperative
* **AG** ("ag") - Stock corporation
* **LLP** ("llp") - Limited liability partnership
* **EWIV** ("ewiv") - European economic interest grouping
* **Municipal** ("municipal")
* **Foreign** ("foreign")
* **Unknown** ("unknown")
* **HRA** (Handelsregister Abteilung A) - Partnerships
* **HRB** (Handelsregister Abteilung B) - Corporations
* **GsR** (Gesellschaftsregister) - Registered civil law partnerships
* **GnR** (Genossenschaftsregister) - Cooperatives
* **PR** (Partnerschaftsregister) - Professional partnerships
* **VR** (Vereinsregister) - Associations
# Insolvenzregister
Source: https://docs.openregister.de/sources/insolvenzregister
The OpenRegister API provides structured access to all German insolvency proceedings, sourced from the official insolvency announcements.
German insolvency courts (Insolvenzgerichte) are legally required to publish every decision in insolvency proceedings on the official portal neu.insolvenzbekanntmachungen.de. Our API turns these raw announcements (Insolvenzbekanntmachungen) into structured, trackable insolvency proceedings: search across all cases, retrieve complete event histories, and resolve proceedings directly to companies in OpenRegister.
## What You Get
* **Complete proceedings** - One record per court case (court and case number, Aktenzeichen), covering all published insolvency proceedings of German companies
* **Current status** - Where the case stands (`preliminary`, `opened`, `rejected_no_assets`, `lifted`, and more), derived from the full event history
* **Structured event timeline** - Every published announcement as a typed event, from the first security measures through opening, distributions, and closure
* **Company links** - Proceedings resolved to OpenRegister companies (`company_id`) for direct lookup of the debtor company
* **Administration data** - Administrator name and address, plus the administration kind: external administration, self administration (Eigenverwaltung), or protective shield (Schutzschirmverfahren)
* **Key dates and figures** - Opening and closing dates, claims filing deadlines, distribution amounts, and insolvency grounds
## Use Cases
**Risk Monitoring** - Banks, insurers, and credit teams screen customers and suppliers for open insolvency proceedings before extending credit, and monitor their portfolio for new filings via webhooks.
**Restructuring & Distressed Assets** - Investors and advisors identify newly opened proceedings by region, court, or date to source restructuring and acquisition opportunities early.
**Claims Management & Legal** - Law firms and creditors track claims filing deadlines, follow individual cases event by event, and reconstruct the full insolvency history of a counterparty.
## API Endpoints
Search all proceedings with free text and filters for status, court, dates, debtor attributes, and more
Retrieve a single proceeding with its complete event history
Company profiles include all insolvency proceedings linked to the company
Receive webhook notifications when new insolvency events are published for companies you watch
See the [filtering guide](/filtering#insolvency-search-fields) for the full list of insolvency search filters.
## Update Frequency
* **Source**: neu.insolvenzbekanntmachungen.de (official publication portal of the German insolvency courts)
* **New announcements**: Imported daily across all publication categories
## Proceeding Lifecycle & Classifications
Every case starts with an insolvency application (Antrag), filed by the debtor itself or by a creditor. From there:
* **Preliminary phase** - Before deciding on the application, the court may order security measures such as appointing a preliminary administrator (vorläufiger Insolvenzverwalter)
* **Opening** - The proceeding is opened if the estate at least covers the costs of the proceeding
* **Rejection** - Otherwise the application is rejected for insufficiency of assets (Abweisung mangels Masse, § 26 InsO); a large share of corporate applications end here
* **Closure** - An opened proceeding normally ends with its lifting (Aufhebung) after the final distribution, or earlier by discontinuation (Einstellung)
* **Insolvency plan** - Alternatively a confirmed insolvency plan (Insolvenzplan) lets the company survive restructured, often under court-ordered plan supervision
* **Administration kind** - `external_administration` (a court-appointed Insolvenzverwalter takes over the estate), `self_administration` (Eigenverwaltung, § 270 InsO), or `protective_shield` (Schutzschirmverfahren, § 270d InsO)
* **Insolvency grounds** - `illiquidity` (Zahlungsunfähigkeit, § 17 InsO), `imminent_illiquidity` (drohende Zahlungsunfähigkeit, § 18 InsO), or `over_indebtedness` (Überschuldung, § 19 InsO)
# Transparenzregister
Source: https://docs.openregister.de/sources/transparenzregister
The OpenRegister API provides structured access to beneficial ownership records from the German Transparenzregister.
The German Transparenzregister is the official register for beneficial ownership information in Germany. OpenRegister gives you simple API access to request extracts and receive structured UBO data plus official source documents.
OpenRegister is officially certified by **Bundesanzeiger Verlag GmbH**, the publisher of the Transparenzregister API. Access to live data still requires **berechtigtes Interesse** (legitimate interest) under the *Geldwäschegesetz* (GwG).
## What You Get
* **Structured UBO records** — Get full name, date of birth, city, country, and percentage hints where available in the register text.
* **Official source documents** — Download original Transparenzregister artifacts (PDF, JSON, optional SVG) through `documents[]`.
* **Sandbox mode** — Test the full integration flow without live credentials and without credit usage.
* **Credential isolation** — Store multiple credential sets under different `name` values (default `default`) for separate clients or environments.
## Getting Started
To use live Transparenzregister data, you need your own account and credentials.
1. **Register with the Transparenzregister** — Create an account at [transparenzregister.de](https://www.transparenzregister.de) and request API access. The Transparenzregister will verify your legitimate interest before granting access.
2. **Store your credentials** — Once you have credentials, store them via the [Store Credentials](/endpoint/transparenzregister-credentials) endpoint. You can store multiple credential sets under different `name` values (e.g. one per client account).
After that, production extract requests use your stored credentials automatically (unless you choose another credential via `X-Credential-Name`).
You can test the integration without live credentials by sending **`X-Credential-Name: sandbox`** on [Order extract](/endpoint/transparenzregister-extract-create). This uses the Transparenzregister test environment and costs **0 credits**.
## Use Cases
**AML & KYC** — Retrieve structured beneficial ownership records as part of customer onboarding, periodic review, and risk-based due diligence processes.
**Compliance Operations** — Centralize Transparenzregister retrieval across teams and clients in a single API flow. Track every extract by `extract_id` and audit outcomes programmatically.
**Due Diligence** — Combine Transparenzregister UBO data with Handelsregister company details and Bundesanzeiger financials for complete entity profiles.
## API Endpoints
Save Transparenzregister credentials with an optional name
Create a new Transparenzregister extract and get an extract id
Poll by extract id and retrieve structured UBO data and source documents when completed
## Update Frequency
* **Source**: Transparenzregister official API
* **Updates**: On-demand per extract submission
* **Processing**: Async workflow; poll [Get extract](/endpoint/transparenzregister-extract-get) until `status` is `completed` or `failed`
# Web Data
Source: https://docs.openregister.de/sources/web-data
The OpenRegister API provides access to contact information and social media data extracted from company websites.
OpenRegister crawls and analyzes company websites to extract publicly available contact information and social media profiles. Our API enriches official register data with real-world contact details and online presence, bridging the gap between official registrations and current business operations.
## What You Get
* **Contact information** - Email addresses and phone numbers
* **Tax identifiers** - VAT ID and Tax ID from company websites
* **Social media profiles** - LinkedIn, Instagram, GitHub, Twitter, Facebook, YouTube, Xing, TikTok
* **Website verification** - Link websites to official company entities
* **Source tracking** - See where each piece of information was found
This data is particularly valuable for sales, marketing, and due diligence when you need current contact details beyond what's in official registers.
## Use Cases
**Sales & Marketing** - Enrich CRM data with contact information and social media profiles for targeted outreach campaigns. Build prospect lists with verified email addresses and phone numbers.
**Due Diligence** - Verify company legitimacy by matching websites to official register entries and checking online presence. Identify inconsistencies between registered information and current web presence.
**Lead Enrichment** - Start with a website URL and discover the company's full profile including ownership structures, financial reports, and contact details. Perfect for lead scoring and qualification workflows.
**Competitive Intelligence** - Track competitors' social media presence and online activities. Monitor changes in contact information and web presence over time.
## API Endpoints
Reverse lookup to find a company using its website URL
Get company information including contact details and social media profiles
## Update Frequency
* **Source**: Company websites and public web data
* **Updates**: Monthly crawls
* Data reflects current online presence and contact information