--- title: "Germany" url: "https://developer.incode.com/general-reference/germany/" section: "general-reference" group: "eKYB Reference / eKYB Prefill Coverage" version: "v1.1" status: "live" --- # Germany eKYB Prefill in Germany leverages Germany's source of truth to automatically retrieve and populate business information based on a company's commercial register number or VAT number, including the business name, registered address, entity type, registration status, directors, shareholders, and additional financial and corporate data, without requiring manual input from the user. ## Source | Country | Source | Description | | --- | --- | --- | | Germany | `DE_KYB_PREFILL` | Returns matching German business details from Germany's source of truth for pre-fill. | ## Direct API approach For general integration notes and shared response semantics, see the [eKYB Prefill API Reference](/general-reference/ekyb-prefill-api-reference/). All module configurations and user data can be forwarded directly in the request for performing a Prefill lookup. This overrides existing configuration and data collected about the user. ### Endpoint `POST /omni/externalVerification/ekyb-prefill` ### Request parameters | Parameter | Required | Description | | --- | --- | --- | | plugins | Mandatory | String array. Must be `["ekyb-prefill"]`. Specifies the Prefill flow. | | source | Mandatory | String. Must be `DE_KYB_PREFILL`. Identifies the Prefill source. | | country | Mandatory | String. Two-letter Alpha-2 country code. Must be `DE`. | | taxId | Mandatory | String. German commercial register number or VAT number. See Tax ID formats for details. | | businessName | Optional | String. Registered name of the business. When provided, adds `nameMatch` to the response. | | address | Optional | String. Business address as a freeform string. When provided, adds `addressMatch` to the response. | ### Tax ID formats The `taxId` field accepts two German business identifier types. Routing between them is determined automatically by the format of the submitted value. | ID Type | Format | Example | | --- | --- | --- | | **Handelsregisternummer** (Commercial register number) | `HRB` or `HRA` followed by digits | `HRB 209661` | | **USt-IdNr** (VAT number) | `DE` + 9 numeric digits | `DE814194672` | These formats do not overlap, so routing is unambiguous. Inputs that do not match either format return a 400 error. ### Sample request ```json { "plugins": ["ekyb-prefill"], "source": "DE_KYB_PREFILL", "country": "DE", "taxId": "HRB 123456", "businessName": "SAGDO GmbH", "address": "Lindenstraße 24, 21465 Reinbek" } ``` ### Heading ### Sample response The Prefill response returns business data retrieved directly from the source of truth. Fields are returned as-is from the source. `nameMatch` and `addressMatch` are only present when `businessName` or `address` were submitted in the request. `vatNo` is only present when the VAT number is available on file for the company. ```json { "kyb-prefill": [ { "tin": "HRB 123456", "vatNo": "DE123456789", "name": "SAGDO GmbH", "nameMatch": "Verified", "address": "Lindenstraße 24, 21465 Reinbek", "city": "Reinbek", "postalCode": "21465", "entityType": "Private limited company", "registrationStatus": "Active", "registrationDate": "2005-12-16T00:00:00Z", "creditRating": "A", "creditRatingDescription": "Very Low Risk", "industryDesc": "Manufacture of sports goods", "activityDesc": "Manufacture of sports goods", "turnover": "2 million - 5 million", "employeeCount": "3-5", "websites": ["sagdo.de"], "shareholders": [ { "name": ": "Nordlicht Capital Investment GmbH", "percentSharesHeld": 100 } ], "ultimateParent": { "name": "BERGMANN BETEILIGUNGSGESELLSCHAFT MBH", "country": "DE" }, "immediateParent": { "name": "BERGMANN BETEILIGUNGSGESELLSCHAFT MBH", "country": "DE" } } ] } ``` ### Response fields | Key | Value | Description | | --- | --- | --- | | tin | Commercial register number | The Handelsregisternummer (HRB/HRA number) as confirmed by the source of truth. | | vatNo | VAT number | The USt-IdNr as returned from the source of truth (for example, `DE123456789`). Only present when the VAT number is available on file — not every company will have this field even if a VAT number exists. | | name | Business name | The registered legal name of the business as returned from the source of truth. | | nameMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `businessName` against the name on file. Only present when `businessName` was submitted in the request. See Name and address match values for details. | | address | Registered address | The primary registered address of the business as returned from the source of truth. | | addressMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `address` against the registered address on file. Only present when `address` was submitted in the request. See Name and address match values for details. | | city | City | The city of the registered address as returned from the source of truth. | | postalCode | Postal code | The postal code of the registered address as returned from the source of truth. | | entityType | Entity type | The legal form of the business as returned from the source of truth (for example, `Private limited company`). Defaults to `Unknown` when not available. | | registrationStatus | Registration status | The current company status as returned from the source of truth (for example, `Active`). Defaults to `Unknown` when not available. | | registrationDate | Date | The date the company was registered, as returned from the source of truth. May not be present for all companies. | | creditRating | Credit rating value | The standardized credit rating value (for example, `A`). Defaults to `Unknown` when not available. | | creditRatingDescription | Credit rating description | A human-readable description of the credit rating (for example, `Very Low Risk`). | | industryDesc | Industry description | The primary activity description as returned from the source of truth (for example, `Manufacture of sports goods`). | | activityDesc | Activity description | The principal activity description as returned from the source of truth. For Germany, this is typically identical to `industryDesc`. | | turnover | String | The turnover range as returned from the source of truth (for example, `"2 million - 5 million"`). Germany provides range values only — no exact figure is available. This field is always a string, not a numeric object. | | employeeCount | String | The latest employee count as returned from the source of truth. May be an exact number (for example, `"5"`) or a range (for example, `"3-5"`) depending on the company. Always returned as a string. May not be present for all companies. | | otherAddresses | Array of `{type, otherAddress}` | Additional addresses on file, other than the primary registered address. May not be present for all companies. | | websites | Array of strings | Website URLs associated with the business as returned from the source of truth. May not be present for all companies. | | shareholders | Array of `{name, percentSharesHeld}` | Shareholders associated with the business as returned from the source of truth. May not be present for all companies. | | directors | Array of `{name, positionName}` | Current directors and officers as returned from the source of truth. `positionName` reflects the primary position title on file. May not be present for all companies. | | ultimateParent | `{name, country, registrationNumber}` | Ultimate parent company, if available. Absent when the entity is not a subsidiary. | | immediateParent | `{name, country, registrationNumber}` | Immediate parent company, if available. Absent when the entity is not a subsidiary. | ### Name and address match values | Status | Description | | --- | --- | | Verified | Exact match found against registry data. | | Approximate Match | Similar match found; may reflect minor differences in naming or address formatting. | | Unverified | No match found in registry data. | ### Registration status values | Status | Description | | --- | --- | | Active | The company is currently active and registered. | | Inactive | The company registration is dissolved, struck off, or no longer active. | | Unknown | The registration status could not be determined. | ## Error responses For standard HTTP response codes, see the API Error Response page. Germany Prefill returns the following country-specific 400 errors. `taxId` is missing, empty, or does not match the `HRB`/`HRA` + digits or `DE` + 9 digits format: ```json { "timestamp": 1782851408892, "status": 400, "error": "Bad Request", "message": "taxId must be a valid German commercial register number (HRB/HRA followed by digits) or VAT number (DE followed by 9 digits)", "path": "/omni/externalVerification/ekyb-prefill" } ``` Any mandatory field (`plugins`, `source`, `country`, or `taxId`) is missing: ```json { "timestamp": 1782851468367, "status": 400, "error": "Bad Request", "message": "must not be blank", "path": "/omni/externalVerification/ekyb-prefill" } ``` No business match is found for the submitted `taxId`: ```json { "timestamp": 1782851583695, "status": 200, "message": "No business found matching the provided tax ID.", "path": "/omni/externalVerification/ekyb-prefill" } ``` ## Single Session Dashboard results Prefill results are available on the Business tab in [Single Session view](/dashboard-platform-administration/single-session-view/).