# Compliance (/compliance)
# Introduction to Beglaubigt.de API (/)
## About Beglaubigt.de [#about-beglaubigtde]
The Beglaubigt API enables seamless integration between your application and our notarization and incorporation services. With Beglaubigt.de, businesses can submit documents, manage signers, and automate notarization workflows, or incorporate companies in Germany.
If you haven't done yet, please sign up under [https://app.beglaubigt.de/signup](https://app.beglaubigt.de/signup)
Our API is RESTful, using predictable HTTP verbs and URLs, making integration straightforward and efficient. By integrating with Beglaubigt.de, you can provide your customers with a streamlined, secure, and legally compliant digital notarization experience.
> 🔨 **Note:** The API is actively evolving to introduce new features and capabilities. Please ensure you keep track of updates, as breaking changes may occur. For support, reach out to us at [info@beglaubigt.de](mailto:info@beglaubigt.de).
# Appointment Completed (/events/appointment.completed)
### Understanding the Event [#understanding-the-event]
The `appointment.completed` event is automatically triggered when the notary appointment date has passed.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `appointment.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The notary appointment date has passed.`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The legal name of the company.\
**Example**: `Acme Holdings GmbH`
The type of company incorporated.\
**Possible values**: `gmbh` or `ug`
The total share capital of the company in EUR.\
**Example**: `25000`
The status of the incorporation.\
**Value**: `appointment-confirmed`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Details about the notarization process.
The method of notarization.\
**Possible values**: `offline` or `online`
Requests expedited notarization.
The client's preferred location for notarization, specified as a city name in either German or English. **Example**: `Munich`
The client's preferred timeframe for notarization, expressed as the number of days from the request date.
**Possible values**: `7`, `14`, `30`
Notarization date in `YYYY-MM-DD` format.\
**Example**: `2025-04-16`
Notarization date in `HH:mm` format.\
**Example**: `14:30`
The current status of the notarization appointment.
**Possible values**: `pending` or `confirmed`
Notary responsible for the notarization.
The name of the notary’s office.\
**Example**: `Notariat Schiller & Partner`
The full name of the notary.\
**Example**: `Dr. Anna Becker`
The email address of the notary.\
**Example**: `dr.becker@notariat-schiller.de`
The contact phone number of the notary.\
**Example**: `+49 89 12345678`
The full address of the notary's office, formatted as `street name and number, postal code, city`.\
**Example**: `Schillerstraße 15, 10117, Berlin`
Your custom reference string provided during incorporation creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "appointment.completed",
"message": "The notary appointment date has passed.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Acme Holdings GmbH",
"type": "gmbh",
"capital": 12500,
"status": "appointment-completed",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"notarization": {
"type": "online",
"express": false,
"preferred_location": "Berlin",
"preferred_timeframe": 7,
"date": "2025-05-16",
"time": "14:30",
"appointment_status": "confirmed",
"notary": {
"office": "Notariat Schiller & Partner",
"name": "Dr. Anna Becker",
"email": "dr.becker@notariat-schiller.de",
"phone": "+49 89 12345678",
"address": "Schillerstraße 15, 10117, Berlin"
}
},
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Appointment Confirmed (/events/appointment.confirmed)
### Understanding the Event [#understanding-the-event]
The `appointment.confirmed` event is automatically triggered when the date for the notary appointment is confirmed.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `appointment.confirmed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The notary appointment has been confirmed.`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The legal name of the company.\
**Example**: `Acme Holdings GmbH`
The type of company incorporated.\
**Possible values**: `gmbh` or `ug`
The total share capital of the company in EUR.\
**Example**: `25000`
The status of the incorporation.\
**Value**: `appointment-confirmed`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Details about the notarization process.
The method of notarization.\
**Possible values**: `offline` or `online`
Requests expedited notarization.
The client's preferred location for notarization, specified as a city name in either German or English. **Example**: `Munich`
The client's preferred timeframe for notarization, expressed as the number of days from the request date.
**Possible values**: `7`, `14`, `30`
Notarization date in `YYYY-MM-DD` format.\
**Example**: `2025-04-16`
Notarization date in `HH:mm` format.\
**Example**: `14:30`
The current status of the notarization appointment.
**Possible values**: `pending` or `confirmed`
Notary responsible for the notarization.
The name of the notary’s office.\
**Example**: `Notariat Schiller & Partner`
The full name of the notary.\
**Example**: `Dr. Anna Becker`
The email address of the notary.\
**Example**: `dr.becker@notariat-schiller.de`
The contact phone number of the notary.\
**Example**: `+49 89 12345678`
The full address of the notary's office, formatted as `street name and number, postal code, city`.\
**Example**: `Schillerstraße 15, 10117, Berlin`
Your custom reference string provided during incorporation creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "appointment.confirmed",
"message": "The notary appointment has been confirmed.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Acme Holdings GmbH",
"type": "gmbh",
"capital": 12500,
"status": "appointment-confirmed",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"notarization": {
"type": "online",
"express": false,
"preferred_location": "Berlin",
"preferred_timeframe": 7,
"date": "2025-05-16",
"time": "14:30",
"appointment_status": "confirmed",
"notary": {
"office": "Notariat Schiller & Partner",
"name": "Dr. Anna Becker",
"email": "dr.becker@notariat-schiller.de",
"phone": "+49 89 12345678",
"address": "Schillerstraße 15, 10117, Berlin"
}
},
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Incorporation Blocked (/events/incorporation.blocked)
### Understanding the Event [#understanding-the-event]
The `incorporation.blocked` event is automatically triggered when an incorporation data has been verified and blocked by our internal team.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `blocked`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The incorporation has been blocked`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the incorporation.\
**Value**: `blocked`
The reason provided by our team for blocking the incorporation.\
**Example**: `The shareholder's identity document is invalid.`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during incorporation creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "incorporation.blocked",
"message": "The incorporation has been blocked.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "blocked",
"reason": "The shareholder's identity document is invalid.",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Incorporation Completed (/events/incorporation.completed)
### Understanding the Event [#understanding-the-event]
The `incorporation.completed` event is triggered automatically when an incorporation data has been verified and confirmed by our internal team.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `incorporation.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The incorporation has been completed.`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The legal name of the company.\
**Example**: `Beglaubigt.de GmbH`
The purpose or business objective of the company.\
**Example**: `Digital Notarization Services for Germany and Europe`
The total share capital of the company in EUR.\
**Example**: `25000`
The address of the company.
The street name and number of the company.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the company.\
**Example**: `80336`
The city of the company.\
**Example**: `Munich`
The state of the company.\
**Example**: `Bayern`
The country of the company, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The business address of the company.
The street name and number of the company.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the company.\
**Example**: `80336`
The city of the company.\
**Example**: `Munich`
The state of the company.\
**Example**: `Bayern`
The country of the company, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The status of the incorporation.\
**Values**: `completed`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
An array of directors managing the company.
First name of the director.\
**Example**: `Maria`
Last name of the director.\
**Example**: `Weber`
Email address of the director.\
**Example**: `maria.weber@example.com`
The phone number of the director.\
**Example**: `+491234567890`
Date of birth of the director in `YYYY-MM-DD` format.\
**Example**: `1978-03-15`
The nationality of the director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `German`
Address of the director.
The street name and number of the director.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the director.\
**Example**: `80336`
The city of the director.\
**Example**: `Munich`
The state of the director\
**Example**: `Bayern`
The country of the director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The director’s signing authority.\
**Possible values**: `sole` or `joint`
A collection of documents related to the company.
The articles of association for the company.
The unique identifier for the document in a UUID format.\
**Example**: `07347a09-7fa2-434f-a5f1-ec897f16d4b9`
The type of document as specified in the request.\
**Possible values**: `musterprotokoll` , `individual`, `gesellschafterliste`, `certificate-of-incorporation` or `deposit-confirmation`
Indicates the current processing state of the document.\
**Possible values**: `submitted`, `in-review` or `reviewed`
An object containing arrays of individual and entity shareholders, including their details, addresses, and shareholding information.
An array of individual shareholders.
The first name of the individual shareholder.\
**Example**: `Max`
The middle name of the individual shareholder.\
**Example**: `Alexander`
The last name of the individual shareholder.\
**Example**: `Mustermann`
The email address of the individual shareholder.\
**Example**: `max.mustermann@example.com`
The phone number of the individual shareholder.\
**Example**: `+491234567890`
The date of birth of the individual shareholder. Format: `YYYY-MM-DD`.\
**Example**: `1985-10-05`
The nationality of the individual shareholder.\
**Example**: `German`
The address of the individual shareholder.
The street name and number of the individual shareholder.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the individual shareholder.\
**Example**: `80336`
The city of the individual shareholder.\
**Example**: `Munich`
The state of the individual shareholder.\
**Example**: `Bayern`
The country of the individual shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The number of shares owned by the shareholder.\
**Example**: `2500`
The percentage of shares owned by the shareholder.\
**Example**: `25`
An array of entity shareholders.
The name of the entity shareholder.\
**Example**: `Max`
The registration number of the entity shareholder.\
**Example**: `Alexander`
The address of the entity shareholder.
The street name and number of the entity shareholder.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the entity shareholder.\
**Example**: `80336`
The city of the entity shareholder.\
**Example**: `Munich`
The state of the entity shreholder.\
**Example**: `Bayern`
The country of the entity shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The directors of the entity shareholder.
The first name of the entity's director.\
**Example**: `John`
The last name of the entity's director.\
**Example**: `Doe`
Date of birth of the entity director in `YYYY-MM-DD` format.\
**Example**: `1978-03-15`
The nationality of the entity's director, specified using **ISO 3166-1 alpha-2** country codes.\
**Example**: `de`
The email of the entity's director.\
**Example**: `john.doe@exemple.com`
The phone number of the entity director.\
**Example**: `+491234567890`
Address of the entity director.
The street name and number of the entity director.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the entity director.\
**Example**: `80336`
The city of the entity director.\
**Example**: `Munich`
The state of the entity director.\
**Example**: `Bayern`
The country of the entity director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The number of shares owned by the shareholder.\
**Example**: `2500`
The percentage of shares owned by the shareholder.\
**Example**: `25`
Details about the notarization process.
The method of notarization.\
**Possible values**: `offline` or `online`
Requests expedited notarization.
The client's preferred timeframe for notarization, expressed as the number of days from the request date.
**Possible values**: `7`, `14`, `30`
Notarization date in `YYYY-MM-DD` format.\
**Example**: `2025-04-16`
Notarization date in `HH:mm` format.\
**Example**: `14:30`
The current status of the notarization appointment.
**Possible values**: `pending` or `confirmed`
Notary responsible for the notarization.
The name of the notary’s office.\
**Example**: `Notariat Schiller & Partner`
The full name of the notary.\
**Example**: `Dr. Anna Becker`
The email address of the notary.\
**Example**: `dr.becker@notariat-schiller.de`
The contact phone number of the notary.\
**Example**: `+49 89 12345678`
The full address of the notary's office, formatted as `street name and number, postal code, city`.\
**Example**: `Schillerstraße 15, 10117, Berlin`
Your custom reference string provided during incorporation creation.\
**Example**: `REF-2025-001`
The preferred language of the client, specified using **ISO 639-1** language codes.\
**Possible values**: `en`, `de`, `es`, `fr` or `it`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "bbcc7dfd-e501-4c7e-a94c-296af04044e2",
"event": "incorporation.completed",
"message": "The incorporation has been completed.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Acme Holdings GmbH",
"type": "gmbh",
"purpose": "Durchführung von digitalen Notarisierungsverfahren mit Schwerpunkt auf Deutschland und dem europäischen Raum.",
"capital": 12500,
"address": {
"street": "Maximilianstraße 15",
"street_second_line": "Apartment 3B",
"zip": "80539",
"city": "Munich",
"state": "Bayern",
"country": "de"
},
"business_address": {
"street": "Goethestraße 18",
"street_second_line": "2. Etage, Büro 5B",
"zip": "50667",
"city": "Cologne",
"state": "Nordrhein-Westfalen",
"country": "de"
},
"status": "completed",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"directors": [
{
"first_name": "Maria",
"last_name": "Weber",
"email": "maria@weber.de",
"phone": "+491234567890",
"dob": "1978-03-15",
"nationality": "de",
"address": {
"street": "Rathenauplatz 7",
"street_second_line": "1. Stock, Raum 3A",
"zip": "90489",
"city": "Nuremberg",
"state": "Bayern",
"country": "de"
},
"authority": "sole"
}
],
"documents": {
"articles_of_association": [
{
"name": "sample.pdf",
"type": "individual",
"status": "submitted"
}
]
},
"shareholders": {
"individuals": [
{
"first_name": "John",
"middle_name": "Michael",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+491234567890",
"dob": "1985-07-10",
"nationality": "de",
"address": {
"street": "Lindenallee 12",
"street_second_line": "EG, Büro 1",
"zip": "60594",
"city": "Frankfurt am Main",
"state": "Hessen",
"country": "de"
},
"shares": 12500,
"share_percentage": 50
}
],
"entities": [
{
"name": "Acme Ventures GmbH",
"registration_number": "HRB123456",
"address": {
"street": "Kaiserstraße 21",
"street_second_line": "4. OG, Zimmer 402",
"zip": "60311",
"city": "Frankfurt",
"state": "Hessen",
"country": "de"
},
"directors": [
{
"first_name": "Stefan",
"last_name": "Müller",
"dob": "1985-06-15",
"nationality": "de",
"email": "stefan.mueller@example.com",
"phone": "+49 151 98765432",
"address": {
"street": "Bahnhofstraße 10",
"street_second_line": "Gebäude B, 2. Etage, Raum 204",
"zip": "10115",
"city": "Berlin",
"state": "Berlin",
"country": "de"
}
}
],
"shares": 5000,
"share_percentage": 5
}
]
},
"notarization": {
"type": "online",
"express": false,
"preferred_timeframe": 7,
"date": "2025-05-16",
"time": "14:30",
"appointment_status": "confirmed",
"notary": {
"office": "Notariat Schiller & Partner",
"name": "Dr. Anna Becker",
"email": "dr.becker@notariat-schiller.de",
"phone": "+49 89 12345678",
"address": "Schillerstraße 15, 10117, Berlin"
}
},
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"created_at": "2025-04-12T08:00:00.0000+00:00"
}
```
# Incorporation Initiated (/events/incorporation.initiated)
### Understanding the Event [#understanding-the-event]
The `incorporation.initiated` event is automatically triggered once the initial incorporation details — name, legal form, and purpose — are provided and a UUID has been assigned to the case.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `incorporation.initiated`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The incorporation has been initiated.`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the incorporation.\
**Value**: `initiated`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during incorporation creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "incorporation.initiated",
"message": "The incorporation has been initiated.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Incorporation Submitted (/events/incorporation.submitted)
### Understanding the Event [#understanding-the-event]
The `incorporation.submitted` event is automatically triggered when the client completes the incorporation process or when an incorporation is submitted via the API.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `incorporation.submitted`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The incorporation has been submitted.`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the incorporation.\
**Values**: `submitted`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during incorporation creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "incorporation.submitted",
"message": "The incorporation has been submitted.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "submitted",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Notarization Completed (/events/notarization.completed)
### Understanding the Event [#understanding-the-event]
The `notarization.completed` event is triggered automatically when a notarization process has been successfully completed and the notarized document is available for download.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.
**Value**: `notarization.completed`
Provides a human-readable message indicating the result of the webhook event.
**Value**: `A document has been notarized.`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.
**Example**: `2024-12-01T07:19:30.443Z`
The type of service this webhook relates to.
**Value**: `notarization`
The unique identifier for the created notarization case in a **UUID** format.
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The unique identifier for the original document in a **UUID** format.
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The unique identifier for the original document in a **UUID** format.
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The URL of the notarized document associated with the case in a **PDF** format. The URL is available for **24 hours** after reception of the webhook HTTP request.
**Example**: `https://app.beglaubigt.de/download?bucket=notarized_documents&id=789e4567-e89b-12d3-a456-426614174002&token=h4J...f7P`
Your custom reference string provided during notarization creation.
**Example**: `REF-2025-001`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "notarization.completed",
"message": "A document has been notarized.",
"timestamp": "2024-10-18T12:00:00Z",
"service": "notarization",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"original_document_id": "456e1234-e89b-12d3-a456-426614174001",
"notarized_document_id": "789e4567-e89b-12d3-a456-426614174002",
"notarized_document_url": "https://app.beglaubigt.de/download?bucket=notarized_documents&id=789e4567-e89b-12d3-a456-426614174002&token=h4J...f7P",
"client_reference": "REF-2025-001"
}
```
# Registration Blocked (/events/registration.blocked)
### Understanding the Event [#understanding-the-event]
The `registration.blocked` event is automatically triggered when a registration's data has been verified and blocked by our internal team.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `registration.blocked`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The registration has been blocked`
The unique identifier for the registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the registration\
**Value**: `blocked`
The package selected by the customer.\
**Possible values**: `self` or `assisted`
The URL of the registration\
**Example**: `https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during registration creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "registration.blocked",
"message": "The registration has been blocked.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"package": "assisted",
"blocked_reason": "Invalid registration number.",
"url": "https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Registration Completed (/events/registration.completed)
### Understanding the Event [#understanding-the-event]
The `registration.submitted` event is triggered automatically when registration's data has been verified and confirmed by our internal team.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `registration.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The registration has been completed`
The unique identifier for the registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the registration\
**Value**: `completed`
The package selected by the customer.\
**Possible values**: `self` or `assisted`
The URL of the registration\
**Example**: `https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during registration creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "registration.completed",
"message": "The registration has been completed.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"package": "assisted",
"url": "https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Registration Form Rendered (/events/registration.form-rendered)
### Understanding the Event [#understanding-the-event]
The `registration.form-rendered` event is automatically triggered when the registration form has been rendered.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `registration.form-rendered`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The registration form has been rendered.`
The unique identifier for the registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the registration\
**Value**: `submitted`
The package selected by the customer.\
**Possible values**: `self` or `assisted`
The URL of the registration\
**Example**: `https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during registration creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "registration.form-rendered",
"message": "The registration form has been rendered.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "submitted",
"package": "assisted",
"url": "https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Registration Initiated (/events/registration.initiated)
### Understanding the Event [#understanding-the-event]
The `registration.initiated` event is automatically triggered once the reason for the reigstration is provided and a UUID has been assigned to the case.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `registration.initiated`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The registration has been initiated.`
The unique identifier for the registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the registration\
**Value**: `initiated`
The URL of the registration\
**Example**: `https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during registration creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "registration.initiated",
"message": "The registration has been initiated.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"url": "https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Registration Submitted (/events/registration.submitted)
### Understanding the Event [#understanding-the-event]
The `registration.submitted` event is automatically triggered when the client completes the registration process.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `registration.submitted`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The registration has been submitted.`
The unique identifier for the registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the registration\
**Value**: `submitted`
The package selected by the customer.\
**Possible values**: `self` or `assisted`
The URL of the registration\
**Example**: `https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided during registration creation.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "registration.submitted",
"message": "The registration has been submitted.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"package": "assisted",
"url": "https://app.beglaubigt.de/register/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Signatures Completed (/events/signatures.completed)
### Understanding the Event [#understanding-the-event]
The `signatures.completed` event is triggered automatically when all required signatures for a document have been successfully completed.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `signatures.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The document has been signed by all signers.`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
The type of service this webhook relates to.\
**Possible values**: `signature` or `notarization`
The unique identifier for the case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The unique identifier for the document in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
Indicates the current status of the document.\
**Possible values**: `draft`, `signatures-requested`, `waiting-for-verifications`, `notarization-started` or `completed`
List of signers included in this case.
The first name of the signer.\
**Example**: `John`
The last name of the signer.\
**Example**: `Doe`
The email address of the signer.\
**Example**: `john.doe@mail.com`
The timestamp of the signature, formatted as an **ISO 8601** string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
Your custom reference string provided during case creation.\
**Example**: `REF-2025-001`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "signatures.completed",
"message": "The document has been signed by all signers.",
"timestamp": "2024-10-18T12:00:00Z",
"service": "signature",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"document_id": "456e1234-e89b-12d3-a456-426614174001",
"document_status": "signatures-completed",
"signers": [
{
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"signed_at": "2024-12-01T07:19:30.443Z"
}
],
"client_reference": "REF-2025-001"
}
```
# Signatures Requested (/events/signatures.requested)
### Understanding the Event [#understanding-the-event]
The `signatures.requested` event is triggered automatically when a document requires signatures for completion.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `signatures.requested`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The requests for document signatures have been sent.`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
The type of service this webhook relates to.\
**Possible values**: `signature` or `notarization`
The unique identifier for the case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The unique identifier for the document in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
Indicates the current status of the document.\
**Possible values**: `draft`, `signatures-requested`, `waiting-for-verifications`, `notarization-started` or `completed`
List of signers included in this case.
The first name of the signer.\
**Example**: `John`
The last name of the signer.\
**Example**: `Doe`
The email address of the signer.\
**Example**: `john.doe@mail.com`
A unique invitation link containing an identification token. The link prompts the signer to complete the required actions, such as signing or verifying documents, based on the case's requirements.\\
**Example**: `https://app.beglaubigt.de/sign/123e4567-e89b-12d3-a456-426614174000?token=123e4567-e89b-12d3-a456-426614174001`
Your custom reference string provided during case creation.\
**Example**: `REF-2025-001`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "signatures.requested",
"message": "The requests for document signatures have been sent.",
"timestamp": "2024-10-18T12:00:00Z",
"service": "signature",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"document_id": "456e1234-e89b-12d3-a456-426614174001",
"document_status": "signatures-requested",
"signers": [
{
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"url": "https://app.beglaubigt.de/sign/123e4567-e89b-12d3-a456-426614174000?token=123e4567-e89b-12d3-a456-426614174003"
}
],
"client_reference": "REF-2025-001"
}
```
# Sole Proprietor Completed (/events/sole-proprietor.completed)
### Understanding the Event [#understanding-the-event]
The `sole-proprietor.completed` event is automatically triggered once our team has finished processing the sole proprietor registration and the case is closed.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `sole-proprietor.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The sole proprietor registration has been completed.`
The unique identifier for the sole proprietor registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the sole proprietor registration.\
**Value**: `completed`
The URL of the sole proprietor registration.\
**Example**: `https://app.beglaubigt.de/sole-proprietor/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided when the sole proprietor registration was created.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "sole-proprietor.completed",
"message": "The sole proprietor registration has been completed.",
"sole_proprietor_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"url": "https://app.beglaubigt.de/sole-proprietor/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Sole Proprietor Initiated (/events/sole-proprietor.initiated)
### Understanding the Event [#understanding-the-event]
The `sole-proprietor.initiated` event is automatically triggered once a sole proprietor registration is created and a UUID has been assigned to the case.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `sole-proprietor.initiated`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The sole proprietor registration has been initiated.`
The unique identifier for the sole proprietor registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the sole proprietor registration.\
**Value**: `initiated`
The URL of the sole proprietor registration.\
**Example**: `https://app.beglaubigt.de/sole-proprietor/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided when the sole proprietor registration was created.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "sole-proprietor.initiated",
"message": "The sole proprietor registration has been initiated.",
"sole_proprietor_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"url": "https://app.beglaubigt.de/sole-proprietor/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Sole Proprietor Submitted (/events/sole-proprietor.submitted)
### Understanding the Event [#understanding-the-event]
The `sole-proprietor.submitted` event is automatically triggered once the client has completed the questionnaire and paid, which hands the case over to our team for processing.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `sole-proprietor.submitted`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The sole proprietor registration has been submitted.`
The unique identifier for the sole proprietor registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the sole proprietor registration.\
**Value**: `submitted`
The URL of the sole proprietor registration.\
**Example**: `https://app.beglaubigt.de/sole-proprietor/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided when the sole proprietor registration was created.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "sole-proprietor.submitted",
"message": "The sole proprietor registration has been submitted.",
"sole_proprietor_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "submitted",
"url": "https://app.beglaubigt.de/sole-proprietor/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Tax Registration Blocked (/events/tax-registration.blocked)
### Understanding the Event [#understanding-the-event]
The `tax-registration.blocked` event is automatically triggered when a tax registration cannot proceed, either because a submission to ELSTER failed or because our internal team blocked the case. The `reason` field explains what stopped it. One of our case managers then reviews the case and follows up, so no action is required on your side.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `tax-registration.blocked`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The tax registration has been blocked. Our team will review the case and follow up.`
The unique identifier for the tax registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the tax registration.\
**Value**: `blocked`
The package selected for the tax registration.\
**Possible values**: `self` or `guided`
The reason the tax registration was blocked.\
**Example**: `The business address could not be matched to a tax office.`
The URL of the tax registration.\
**Example**: `https://app.beglaubigt.de/register/tax/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided when the tax registration was created.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "tax-registration.blocked",
"message": "The tax registration has been blocked. Our team will review the case and follow up.",
"tax_registration_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "blocked",
"package_type": "guided",
"reason": "The business address could not be matched to a tax office.",
"url": "https://app.beglaubigt.de/register/tax/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Tax Registration Completed (/events/tax-registration.completed)
### Understanding the Event [#understanding-the-event]
The `tax-registration.completed` event is automatically triggered once the tax registration has been submitted to ELSTER and the case is closed.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `tax-registration.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The tax registration has been completed.`
The unique identifier for the tax registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the tax registration.\
**Value**: `completed`
The package selected for the tax registration.\
**Possible values**: `self` or `guided`
The URL of the tax registration.\
**Example**: `https://app.beglaubigt.de/register/tax/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided when the tax registration was created.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "tax-registration.completed",
"message": "The tax registration has been completed.",
"tax_registration_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"package_type": "guided",
"url": "https://app.beglaubigt.de/register/tax/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Tax Registration Initiated (/events/tax-registration.initiated)
### Understanding the Event [#understanding-the-event]
The `tax-registration.initiated` event is automatically triggered once a tax registration case is created and a UUID has been assigned to it.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `tax-registration.initiated`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `The tax registration has been initiated.`
The unique identifier for the tax registration in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The status of the tax registration.\
**Value**: `initiated`
The URL of the tax registration.\
**Example**: `https://app.beglaubigt.de/register/tax/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
Your custom reference string provided when the tax registration was created.\
**Example**: `REF-2025-001`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2025-06-01T08:00:00.443Z`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "tax-registration.initiated",
"message": "The tax registration has been initiated.",
"tax_registration_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "initiated",
"url": "https://app.beglaubigt.de/register/tax/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"client_reference": "REF-2025-001",
"timestamp": "2025-10-18T12:00:00Z"
}
```
# Verifications Completed (/events/verifications.completed)
### Understanding the Event [#understanding-the-event]
The `verifications.completed` event is triggered automatically when the identities of all signers have been successfully verified.
### Payload Fields [#payload-fields]
A unique identifier for this webhook in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The name of the event that triggered this webhook.\
**Value**: `verifications.completed`
Provides a human-readable message indicating the result of the webhook event.\
**Value**: `All signers have verified their identity.`
The exact date and time when the webhook was triggered, formatted as an **ISO 8601** string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
The type of service this webhook relates to.\
**Value**: `notarization`
The unique identifier for the case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The unique identifier for the document in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
Indicates the current status of the document.\
**Possible values**: `draft`, `signatures-requested`, `waiting-for-verifications`, `notarization-started` or `completed`
List of signers included in this case.
The first name of the signer.\
**Example**: `John`
The last name of the signer.\
**Example**: `Doe`
The email address of the signer.\
**Example**: `john.doe@mail.com`
The timestamp indicating when the signer verified their identity, formatted as an ISO 8601 string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
Your custom reference string provided during case creation.\
**Example**: `REF-2025-001`
```json theme={null}
{
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "verifications.completed",
"message": "All signers have verified their identity.",
"timestamp": "2024-10-18T12:00:00Z",
"service": "notarization",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"document_id": "456e1234-e89b-12d3-a456-426614174001",
"document_status": "verifications-completed",
"signers": [
{
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"identity_verified_at": "2024-12-01T07:19:30.443Z"
}
],
"client_reference": "REF-2025-001"
}
```
# Get Incorporation (/incorporation/get)
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Path Parameters [#path-parameters]
The unique identifier of the incorporation to retrieve.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
### Response [#response]
Indicates the outcome of the API request.\
**Possible values**: `success` or `error`
Provides a human-readable message detailing the result of the API request.\
**Exemple**: `Incorporation fetched successfully.`
The unique identifier for the incorporation in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The legal name of the company.\
**Example**: `Acme Holdings GmbH`
The type of company incorporated.\
**Possible values**: `gmbh` or `ug`
The purpose or business objective of the company.\
**Example**: `Digital Notarization Services for Germany and Europe`
The type of articles of association used for the incorporation.\
**Possible values**: `musterprotokoll` or `individual`
The total share capital of the company in EUR.\
**Example**: `25000`
The share of the capital that must be present for a shareholders' meeting to be quorate, in percent.\
**Example**: `75`
The majority required to pass an ordinary shareholders' resolution, in percent.\
**Example**: `75`
The majority required to approve significant transactions, in percent.\
**Example**: `100`
How the company is represented by its directors.\
**Possible values**: `joint`, `sole` or `section181`
The majority model used for shareholder decisions.\
**Possible values**: `simple`, `two_thirds` or `unanimous`
The notice period for terminating the company agreement, in months.\
**Example**: `3`
Add-on services the client expressed interest in. Empty when none were selected.\
**Possible values**: `authority-registrations`, `business-liability-insurance`, `trademark-registration`, `bookkeeping`, `tax-advisor-support` or `business-address`\
**Example**: `["authority-registrations", "bookkeeping"]`
The commercial register number (Handelsregisternummer) for incorporations.\
**Example**: `HRB 123456`
The local court (Amtsgericht) where the company is registered.\
**Example**: `Berlin (Charlottenburg)`
Indicates whether the company is already officially entered in the commercial register.\
**Example**: `true`
The address of the company.
The street name and number of the company.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the company.\
**Example**: `80336`
The city of the company.\
**Example**: `Munich`
The state of the company.\
**Example**: `Bayern`
The country of the company, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The business address of the company.
The street name and number of the company.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the company.\
**Example**: `80336`
The city of the company.\
**Example**: `Munich`
The state of the company.\
**Example**: `Bayern`
The country of the company, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The status of the incorporation.
**Possible values**: `initiated`, `submitted`, `contact-with-notary-initiated`, `appointment-confirmed`, `appointment-completed`, `waiting-for-deposit-confirmation`, `completed`, `blocked`, `archive`, `unprocessable`
The URL of the incorporation.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
An array of directors managing the company.
First name of the director.\
**Example**: `Maria`
Last name of the director.\
**Example**: `Weber`
Email address of the director.\
**Example**: `maria.weber@example.com`
The phone number of the director.\
**Example**: `+491234567890`
Date of birth of the director in `YYYY-MM-DD` format.\
**Example**: `1978-03-15`
The nationality of the director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
Address of the director.
The street name and number of the director.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the director.\
**Example**: `80336`
The city of the director.\
**Example**: `Munich`
The state of the director.\
**Example**: `Bayern`
The country of the director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The director’s signing authority.\
**Possible values**: `sole` or `joint`
A collection of documents related to the company.
The articles of association for the company.
The unique identifier for the document in a UUID format.\
**Example**: `07347a09-7fa2-434f-a5f1-ec897f16d4b9`
The file name of the document.\
**Example**: `Gesellschafterliste - Acme Holdings GmbH.pdf`
The type of document as specified in the request.\
**Possible values**: `musterprotokoll` , `individual`, `gesellschafterliste`, `certificate-of-incorporation` or `deposit-confirmation`
Indicates the current processing state of the document.\
**Possible values**: `submitted`, `in-review` or `reviewed`
An object containing arrays of individual and entity shareholders, including their details, addresses, and shareholding information.
An array of individual shareholders.
The first name of the individual shareholder.\
**Example**: `Max`
The middle name of the individual shareholder.\
**Example**: `Alexander`
The last name of the individual shareholder.\
**Example**: `Mustermann`
The email address of the individual shareholder.\
**Example**: `max.mustermann@example.com`
The phone number of the individual shareholder.\
**Example**: `+491234567890`
The date of birth of the individual shareholder. Format: `YYYY-MM-DD`.\
**Example**: `1985-10-05`
The nationality of the individual shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The address of the individual shareholder.
The street name and number of the individual shareholder.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the individual shareholder.\
**Example**: `80336`
The city of the individual shareholder.\
**Example**: `Munich`
The state of the individual shareholder.\
**Example**: `Bayern`
The country of the individual shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The number of shares owned by the shareholder.\
**Example**: `2500`
The percentage of shares owned by the shareholder.\
**Example**: `25`
An array of entity shareholders.
The name of the entity shareholder.\
**Example**: `Max`
The registration number of the entity shareholder.\
**Example**: `Alexander`
The address of the entity shareholder.
The street name and number of the entity shareholder.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the entity shareholder.\
**Example**: `80336`
The city of the entity shareholder.\
**Example**: `Munich`
The state of the entity shareholder.\
**Example**: `Bayern`
The country of the entity shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The directors of the entity shareholder.
The first name of the entity's director.\
**Example**: `John`
The last name of the entity's director.\
**Example**: `Doe`
Date of birth of the entity director in `YYYY-MM-DD` format.\
**Example**: `1978-03-15`
The nationality of the entity's director, specified using **ISO 3166-1 alpha-2** country codes.\
**Example**: `de`
The email of the entity's director.\
**Example**: `john.doe@exemple.com`
The phone number of the entity director.\
**Example**: `+491234567890`
Address of the entity director.
The street name and number of the entity director.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the entity director.\
**Example**: `80336`
The city of the entity director.\
**Example**: `Munich`
The state of the entity director.\
**Example**: `Bayern`
The country of the entity director, specified using ISO 3166-1 alpha-2 country code.\
**Example**: `de`
The number of shares owned by the shareholder.\
**Example**: `2500`
The percentage of shares owned by the shareholder.\
**Example**: `25`
Details about the notarization process.
The method of notarization.\
**Possible values**: `offline` or `online`
Requests expedited notarization.
The client's preferred timeframe for notarization, expressed as the number of days from the request date.
**Possible values**: `7`, `14`, `30`
Notarization date in `YYYY-MM-DD` format.\
**Example**: `2025-04-16`
The current status of the notarization appointment.
**Possible values**: `pending` or `confirmed`
Notary responsible for the notarization.
The name of the notary’s office.\
**Example**: `Notariat Schiller & Partner`
The full name of the notary.\
**Example**: `Dr. Anna Becker`
The email address of the notary.\
**Example**: `dr.becker@notariat-schiller.de`
The contact phone number of the notary.\
**Example**: `+49 89 12345678`
The full address of the notary's office, formatted as `street name and number, postal code, city`.\
**Example**: `Schillerstraße 15, 10117, Berlin`
A custom client reference string for tracking purposes.\
**Example**: `REF-2025-001`
The preferred language of the client, specified using **ISO 639-1** language codes.\
**Possible values**: `en`, `de`, `es`, `fr` or `it`
The timestamp at which the incorporation was created, formatted as an ISO 8601 string (UTC).\
**Example**: `2025-06-15T08:00:00.000Z`
```json theme={null}
{
"response": {
"result": "success",
"message": "Incorporation fetched successfully.",
"incorporation_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Acme Holdings GmbH",
"legal_form": "gmbh",
"purpose": "Durchführung von digitalen Notarisierungsverfahren mit Schwerpunkt auf Deutschland und dem europäischen Raum.",
"agreement_type": "individual",
"capital": 25000,
"shareholders_meeting_quorum": 75,
"shareholders_resolution_majority": 75,
"significant_transactions_majority": 100,
"representation_type": "sole",
"majority_type": "two_thirds",
"notice_period_months": 3,
"additional_services": ["authority-registrations", "bookkeeping"],
"address": {
"street": "Maximilianstraße 15",
"street_second_line": "Apartment 3B",
"zip": "80539",
"city": "Munich",
"state": "Bayern",
"country": "de"
},
"business_address": {
"street": "Goethestraße 18",
"street_second_line": "2. Etage, Büro 5B",
"zip": "50667",
"city": "Cologne",
"state": "Nordrhein-Westfalen",
"country": "de"
},
"status": "submitted",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"directors": [
{
"first_name": "Maria",
"last_name": "Weber",
"email": "maria@weber.de",
"phone": "+491234567890",
"dob": "1978-03-15",
"nationality": "de",
"address": {
"street": "Rathenauplatz 7",
"street_second_line": "1. Stock, Raum 3A",
"zip": "90489",
"city": "Nuremberg",
"state": "Bayern",
"country": "de"
},
"authority": "sole"
}
],
"documents": {
"articles_of_association": [
{
"id": "07347a09-7fa2-434f-a5f1-ec897f16d4b9",
"name": "Gesellschafterliste - Acme Holdings GmbH.pdf",
"type": "gesellschafterliste",
"status": "submitted"
},
{
"id": "5c2f1b84-9e77-4f2a-bd51-3a9e6c0d1f42",
"name": "Gesellschaftsvertrag - Acme Holdings GmbH.pdf",
"type": "individual",
"status": "submitted"
}
]
},
"shareholders": {
"individuals": [
{
"first_name": "John",
"middle_name": "Michael",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+491234567890",
"dob": "1985-07-10",
"nationality": "de",
"address": {
"street": "Lindenallee 12",
"street_second_line": "EG, Büro 1",
"zip": "60594",
"city": "Frankfurt am Main",
"state": "Hessen",
"country": "de"
},
"shares": 12500,
"share_percentage": 50
}
],
"entities": [
{
"name": "Acme Ventures GmbH",
"registration_number": "HRB123456",
"address": {
"street": "Kaiserstraße 21",
"street_second_line": "4. OG, Zimmer 402",
"zip": "60311",
"city": "Frankfurt",
"state": "Hessen",
"country": "de"
},
"directors": [
{
"first_name": "Stefan",
"last_name": "Müller",
"dob": "1985-06-15",
"nationality": "de",
"email": "stefan.mueller@example.com",
"phone": "+49 151 98765432",
"address": {
"street": "Bahnhofstraße 10",
"street_second_line": "Gebäude B, 2. Etage, Raum 204",
"zip": "10115",
"city": "Berlin",
"state": "Berlin",
"country": "de"
}
}
],
"shares": 12500,
"share_percentage": 50
}
]
},
"notarization": {
"type": "online",
"express": false,
"preferred_timeframe": 7,
"date": "2025-05-16",
"appointment_status": "confirmed",
"notary": {
"office": "Notariat Schiller & Partner",
"name": "Dr. Anna Becker",
"email": "dr.becker@notariat-schiller.de",
"phone": "+49 89 12345678",
"address": "Schillerstraße 15, 10117, Berlin"
}
},
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"created_at": "2025-04-12T08:00:00.0000+00:00"
}
}
```
# Initiate Incorporation (/incorporation/post)
## Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
## Body [#body]
The legal name of the company.\
**Example**: `Beglaubigt.de GmbH`
The type of company being incorporated.\
**Possible values**: `gmbh` or `ug`
**Note**: *The matching legal-form suffix is appended to `name` automatically — `Beglaubigt.de` becomes `Beglaubigt.de GmbH` (or `Beglaubigt.de UG (haftungsbeschränkt)`). If the suffix is already present it is left untouched.*
The purpose or business objective of the company.\
**Example**: `Digital Notarization Services for Germany and Europe`
The address of the company.
The street name and number of the company.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the company.\
**Example**: `80336`
The city of the company.\
**Example**: `Munich`
The state of the company.\
**Example**: `Bayern`
The country of the company, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The business address of the company.
The street name and number of the company.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the company.\
**Example**: `80336`
The city of the company.\
**Example**: `Munich`
The state of the company.\
**Example**: `Bayern`
The country of the company, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The total share capital of the company in EUR. Must be a whole number (no decimals).\
**Minimum**: `25000` for `gmbh`, `1` for `ug`\
**Example**: `25000`
An object containing arrays of individual and entity shareholders, including their details, addresses, and shareholding information.
**Note**: *At least one shareholder is required — supply `individuals`, `entities`, or both.*
**Note**: *`share_percentage` across all shareholders (individuals **and** entities combined) must total exactly `100`. The nominal share value of each shareholder is derived automatically as `share_percentage / 100 × capital`, so it is not part of the request.*
An array of individual shareholders.
The first name of the individual shareholder.\
**Example**: `Max`
The middle name of the individual shareholder.\
**Example**: `Alexander`
The last name of the individual shareholder.\
**Example**: `Mustermann`
The email address of the individual shareholder.\
**Example**: `max.mustermann@example.com`
The phone number of the individual shareholder.\
**Required for the first individual shareholder**; optional for the others.\
**Example**: `+491234567890`
The date of birth of the individual shareholder. Format: `YYYY-MM-DD`.\
**Example**: `1985-05-10`
The nationality of the individual shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The address of the individual shareholder.
The street name and number of the individual shareholder.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the individual shareholder.\
**Example**: `80336`
The city of the individual shareholder.\
**Example**: `Munich`
The state of the individual shareholder.\
**Example**: `Bayern`
The country of the individual shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The percentage of shares owned by the shareholder.\
**Example**: `50`
Whether this shareholder is also a managing director of the company. When `true`, a matching director is created automatically and you do not need to repeat the person in the `directors` array.\
**Default value:** `false`
An array of entity shareholders.
The name of the entity shareholder.\
**Example**: `Max`
The registration number of the entity shareholder.\
**Example**: `Alexander`
The address of the entity shareholder.
The street name and number of the entity shareholder.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the entity shareholder.\
**Example**: `80336`
The city of the entity shareholder.\
**Example**: `Munich`
The state of the entity shareholder\
**Example**: `Bayern`
The country of the entity shareholder, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The directors of the entity shareholder.
The first name of the entity's director.\
**Example**: `John`
The last name of the entity's director.\
**Example**: `Doe`
Date of birth of the entity director in `YYYY-MM-DD` format.\
**Example**: `1978-03-15`
The nationality of the entity's director, specified using **ISO 3166-1 alpha-2** country codes.\
**Example**: `de`
The email of the entity's director.\
**Example**: `john.doe@exemple.com`
The phone number of the entity director.\
**Example**: `+491234567890`
Address of the entity director.
The street name and number of the entity director.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the entity director.\
**Example**: `80336`
The city of the entity director.\
**Example**: `Munich`
The state of the entity director.\
**Example**: `Bayern`
The country of the entity director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
The percentage of shares owned by the shareholder.\
**Example**: `50`
An array of directors managing the company.
**Note**: *Required unless at least one individual shareholder is flagged with `is_managing_director: true`, in which case that shareholder becomes the director automatically.*
First name of the director.\
**Example**: `Maria`
Last name of the director.\
**Example**: `Weber`
Email address of the director.\
**Example**: `maria.weber@example.com`
The phone number of the director.\
**Example**: `+491234567890`
Date of birth of the director in `YYYY-MM-DD` format.\
**Example**: `1978-03-15`
The nationality of the director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
Address of the director.
The street name and number of the director.\
**Example**: `Schillerstraße 5`
Additional address information, such as apartment number, suite, floor, or building.\
**Example**: `Apartment 4B`
The postal code of the director.\
**Example**: `80336`
The city of the director.\
**Example**: `Munich`
The state of the director.\
**Example**: `Bayern`
The country of the director, specified using **ISO 3166-1 alpha-2** country code.\
**Example**: `de`
A collection of documents related to the company. Leave empty to have the articles of association generated for you.
The articles of association for the company.
Specifies the nature of the articles of association. Use `musterprotokoll` for the standardized template typically used by UGs, or `individual` for bespoke articles tailored to specific needs, commonly used by GmbHs or UGs with unique requirements.\
**Possible values**: `musterprotokoll` or `individual`
Attach your own articles of association. Only available for an `individual` document — leave empty to have it generated for you.\
**Example**: `https://example.com/gesellschaftsvertrag.pdf`
Details about the notarization process.
The method of notarization.\
**Possible values**: `offline` or `online`
Requests expedited notarization.\
**Default value:** `false`
The client's preferred timeframe for notarization, expressed as the number of days from the request date.
**Possible values**: `7`, `14`, `30`
A custom client reference string for tracking purposes.\
**Example**: `REF-2025-001`
The preferred language of the client, specified using **ISO 639-1** language codes.\
**Possible values**: `en`, `de`, `es`, `fr` or `it`\
**Default value:** `de`
Optional add-on services the client is interested in alongside the incorporation. Non-binding — used to route follow-up, it does not change the price.\
**Possible values**: `authority-registrations`, `business-liability-insurance`, `trademark-registration`, `bookkeeping`, `tax-advisor-support` or `business-address`\
**Example**: `["authority-registrations", "bookkeeping"]`
The share of the capital that must be present for a shareholders' meeting to be quorate, in percent.\
**Example**: `75`
The majority required to pass an ordinary shareholders' resolution, in percent.\
**Example**: `75`
The majority required to approve significant transactions, in percent.\
**Example**: `100`
How the company is represented by its directors.\
**Possible values**: `joint`, `sole` or `section181`
The majority model used for shareholder decisions.\
**Possible values**: `simple`, `two_thirds` or `unanimous`
The notice period for terminating the company agreement, in months.\
**Example**: `3`
```json theme={null}
{
"name": "Beglaubigt.de GmbH",
"legal_form": "gmbh",
"purpose": "Durchführung von digitalen Notarisierungsverfahren mit Schwerpunkt auf Deutschland und dem europäischen Raum.",
"address": {
"street": "Maximilianstraße 15",
"street_second_line": "Apartment 3B",
"zip": "80539",
"city": "Munich",
"state": "Bayern",
"country": "de"
},
"business_address": {
"street": "Goethestraße 18",
"street_second_line": "2. Etage, Büro 5B",
"zip": "50667",
"city": "Cologne",
"state": "Nordrhein-Westfalen",
"country": "de"
},
"capital": 25000,
"shareholders": {
"individuals": [
{
"first_name": "John",
"middle_name": "Michael",
"last_name": "Doe",
"email": "john@doe.de",
"phone": "+49 151 12345678",
"dob": "1985-07-10",
"nationality": "de",
"address": {
"street": "Bahnhofstraße 10",
"street_second_line": "Gebäude B, 2. Etage, Raum 204",
"zip": "10115",
"city": "Berlin",
"state": "Berlin",
"country": "de"
},
"share_percentage": 50
}
],
"entities": [
{
"name": "Acme Holdings GmbH",
"registration_number": "HRB123456",
"address": {
"street": "Königsallee 50",
"street_second_line": "Haus C, 3. Stock, Büro 301",
"zip": "40212",
"city": "Düsseldorf",
"state": "Nordrhein-Westfalen",
"country": "de"
},
"directors": [
{
"first_name": "Stefan",
"last_name": "Müller",
"dob": "1985-06-15",
"nationality": "de",
"email": "stefan.mueller@example.com",
"phone": "+49 151 98765432",
"address": {
"street": "Bahnhofstraße 10",
"street_second_line": "Gebäude B, 2. Etage, Raum 204",
"zip": "10115",
"city": "Berlin",
"state": "Berlin",
"country": "de"
}
},
{
"first_name": "Laura",
"last_name": "Schneider",
"dob": "1990-03-22",
"nationality": "de",
"email": "laura.schneider@example.com",
"phone": "+49 160 12345678",
"address": {
"street": "Lindenweg 7",
"street_second_line": "3. Stock, Wohnung 12",
"zip": "80331",
"city": "München",
"state": "Bayern",
"country": "de"
}
}
],
"share_percentage": 50
}
]
},
"directors": [
{
"first_name": "Maria",
"last_name": "Weber",
"email": "maria@weber.de",
"phone": "+49 151 12345678",
"dob": "1978-03-15",
"nationality": "de",
"address": {
"street": "Schillerstraße 5",
"street_second_line": "2. OG, Einheit 7A",
"zip": "80336",
"city": "Munich",
"state": "Bayern",
"country": "de"
}
}
],
"documents": {
"articles_of_association": [
{
"type": "musterprotokoll"
}
]
},
"notarization": {
"type": "online",
"express": false,
"preferred_timeframe": 7
},
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"additional_services": ["authority-registrations", "bookkeeping"]
}
```
## Response [#response]
Indicates the outcome of the API request.\
**Possible values**: `success` or `error`
Provides a human-readable message detailing the result of the API request.\
**Example**: `Incorporation created successfully.`
The unique identifier for the created incorporation case in a **UUID** format.\
**Example**: `450506c1-d1a7-46e2-aca6-41a816805595`
The current status of the incorporation request.\
**Possible values**: `initiated`, `submitted`, `contact-with-notary-initiated`, `appointment-confirmed`, `appointment-completed`, `waiting-for-deposit-confirmation`, `completed`, `blocked`, `archive`, `unprocessable`
A unique, case-specific URL for accessing and monitoring the incorporation process.\
**Example**: `https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000`
A collection of documents related to the company.
The articles of association for the company.
The unique identifier for the document in a UUID format.\
**Example**: `07347a09-7fa2-434f-a5f1-ec897f16d4b9`
The file name of the document.\
**Example**: `Gesellschafterliste - Beglaubigt.de GmbH.pdf`
The type of document as specified in the request.\
**Possible values**: `musterprotokoll` , `individual`, `gesellschafterliste`, `certificate-of-incorporation` or `deposit-confirmation`
Indicates the current processing state of the document.\
**Possible values**: `submitted`, `in-review` or `reviewed`
Details about the notarization process.
The method of notarization.\
**Possible values**: `offline` or `online`
Requests expedited notarization.
The client's preferred timeframe for notarization, expressed as the number of days from the request date.
**Possible values**: `7`, `14`, `30`
The current status of the notarization appointment.
**Possible values**: `pending` or `confirmed`
The custom client reference string provided in the request.\
**Example**: `REF-2024-001`
The preferred language of the client, specified using **ISO 639-1** language codes.\
**Possible values**: `en`, `de`, `es`, `fr` or `it`
The exact date and time when the response was generated, formatted as an **ISO 8601** string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
```json theme={null}
{
"response": {
"result": "success",
"message": "Incorporation created successfully.",
"incorporation_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "submitted",
"url": "https://app.beglaubigt.de/incorporate/acme-holding-gmbh/123e4567-e89b-12d3-a456-426614174000",
"documents": {
"articles_of_association": [
{
"id": "07347a09-7fa2-434f-a5f1-ec897f16d4b9",
"name": "sample.pdf",
"type": "individual",
"status": "submitted"
}
]
},
"notarization": {
"type": "online",
"express": true,
"preferred_timeframe": 7,
"appointment_status": "pending"
},
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"timestamp": "2025-12-01T07:19:30.443Z"
}
}
```
# Delivery and retries (/guides/delivery-and-retries)
## Webhook delivery & retries [#webhook-delivery--retries]
When your server receives a webhook, it's like getting a handshake from Beglaubigt. To confirm you received it:
* Your endpoint should respond with **HTTP status code 200 OK**.
## Best practices [#best-practices]
Handle Beglaubigt webhooks like a pro by following these best practices:
* **Make handlers idempotent**: Ensure receiving the same webhook multiple times doesn't cause unintended effects.
* **Validate webhook signatures**: Verify the event's authenticity to ensure it originates from Beglaubigt.
* **Respond quickly**: Acknowledge receipt promptly to prevent retries.
## Need help? [#need-help]
If you have any questions or need assistance, feel free to contact us at [info@beglaubigt.de](mailto:info@beglaubigt.de).
# Introduction (/guides)
Webhooks are like having a helpful assistant who proactively notifies your application when important notarization events occur. Instead of repeatedly asking, “Has the notarization been completed?”, webhooks automatically tap your application on the shoulder when it happens.
### Why use webhooks? [#why-use-webhooks]
* **Real-time updates**: Get instant notifications when notarization events are completed.
* **Automation friendly**: Perfect for integrating notarization workflows seamlessly.
* **Efficient**: No need to constantly poll the API for updates.
* **Reliable**: Never miss an important event, even if your system is temporarily down.
### Getting started [#getting-started]
To start receiving webhooks from Beglaubigt, follow these steps:
1. Set up a publicly accessible HTTPS endpoint on your server.
2. Register your webhook URL with Beglaubigt (via your dashboard under `/webhooks`).
3. Implement a handler to process the `notarization.completed` event.
### Webhook payload example [#webhook-payload-example]
Here’s an example of the webhook payload you’ll receive for a completed notarization:
```json
{
"webhook_id": "webhook_abcdef123456",
"event": "notarization.completed",
"message": "A document has been notarized.",
"timestamp": "2024-10-18T12:00:00Z",
"case": "notarization",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"original_document_id": "456e1234-e89b-12d3-a456-426614174001",
"notarized_document_id": "789e4567-e89b-12d3-a456-426614174002",
"notarized_document_url": "https://app.beglaubigt.de/download?bucket=notarized_documents&id=789e4567-e89b-12d3-a456-426614174002&token=b6V...km3",
"client_reference": "REF-2025-001"
}
```
See [Delivery and retries](/guides/delivery-and-retries) for how Beglaubigt delivers events, what acknowledgement we expect, and best practices for handling them safely. For payload authenticity, see [Signature Verification](/guides/signature-verification).
# Signature Verification (/guides/signature-verification)
## Why Use Signature Verification? [#why-use-signature-verification]
Signature verification ensures that webhook HTTP requests originate from Beglaubigt and have not been tampered with. By validating the included digital signature, you can protect your systems from unauthorized or malicious requests.
## How it works? [#how-it-works]
When we send a webhook HTTP request to your endpoint, we include a digital signature in the `X-Signature` header. This signature is generated using the HMAC-SHA256 algorithm and a **secret key that is shared exclusively between Beglaubigt and your system**. The process involves:
1. **Secret Key**: Each webhook you create is associated with a unique secret key, that you can find on the webhooks page: [https://app.beglaubigt.de/api/webhooks](https://app.beglaubigt.de/api/webhooks)
2. **Payload Preparation**: The payload of the webhook is serialized as a JSON string.
3. **Signature Generation**: Using the secret key, we compute the HMAC-SHA256 digest of the payload.
4. **Signature Inclusion**: The resulting digest (hexadecimal-encoded) is included in the `X-Signature` header of the webhook HTTP request.
This allows you, the recipient, to independently compute the signature using the same payload and secret key to verify its authenticity.
## Example [#example]
Here’s a practical example using Node.js:
```javascript
const crypto = require('crypto');
// Payload received in the webhook HTTP request
const payload = {
"webhook_id": "123e4567-e89b-12d3-a456-426614174000",
"event": "notarization.completed",
"timestamp": "2024-10-18T12:00:00Z",
"service": "notarization",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"original_document_id": "456e1234-e89b-12d3-a456-426614174001",
"notarized_document_id": "789e4567-e89b-12d3-a456-426614174002",
"notarized_document_url": "https://app.beglaubigt.de/download?bucket=notarized_documents&id=789e4567-e89b-12d3-a456-426614174002&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cmwiOiJub3Rhcml6ZWRfZG9jdW1lbnRzL2E2ZWE4YTc2LWI5MTMtNGMyNy1hYThiLWY3ZWUwOTgxN2UyNy9kb2N1bWVudC5wZGYiLCJpYXQiOjE3MzQxNDM5NDksImV4cCI6MTczNDIzMDM0OX0.vCFf_u80LQ8FCd1vmOA1SihXnUVJIcLpck0txi62Nig"
}
// Your secret key, accessible on the dashboard
const secretKey = '31d1cb83dbce4c2a6b1b4828794e1db6aa49f9e59063c40d754fef8a0626b77b';
// Serialize the payload object into a JSON string
const serializedPayload = JSON.stringify(payload);
// Compute the HMAC-SHA256 digest
const hmac = crypto.createHmac('sha256', secretKey);
hmac.update(serializedPayload);
const digest = hmac.digest('hex');
console.log(`Digest (Signature): ${digest}`);
// Digest (Signature): c3d770fb1fa41726485593ccce86cb7df9b918ec6fd5e5a0d0c08943c55691f2
```
# Get Notarization (/notarization/get)
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Path Parameters [#path-parameters]
The unique identifier of the notarization case to retrieve.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
### Response [#response]
Indicates the outcome of the API request.\
**Possible values**: `success` or `error`
Provides a human-readable message detailing the result of the API request.\
**Exemple**: `Case created successfully.`
The unique identifier for the created notarization case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The current status of the notarization request.\
Possible values: `in-progress` or `completed`
A unique, case-specific URL for accessing and monitoring the current status and details of the notarization process.\
**Example**: `https://app.beglaubigt.de/notarize/123e4567-e89b-12d3-a456-426614174000`
List of documents included in this notarization request.
Indicates the current processing state of the specific document within the notarization case.\
**Possible values**: `draft`, `signatures-requested`, `waiting-for-verifications`, `notarization-started` or `completed`
The unique identifier for the original document associated with the case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The URL of the original document associated with the case in a **PDF** format. The URL is available for **24 hours** after the request.\
**Example**: `https://app.beglaubigt.de/download?bucket=documents&id=123e4567-e89b-12d3-a456-426614174000&token=a1H...To5`
The unique identifier for the notarized version of the document associated with the case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174001`
The URL of the notarized document associated with the case in a **PDF** format. The URL is available for **24 hours** after the request.\
**Example**: `https://app.beglaubigt.de/download?bucket=notarized_documents&id=123e4567-e89b-12d3-a456-426614174001&token=h4J...f7P`
List of signers included in this notarization request.
The first name of the signer.
The last name of the signer.
The email address of the signer.
A unique invitation link containing an identification token. The link prompts the signer to complete the required actions, such as signing or verifying documents, based on the notarization requirements.\\
**Example**: `https://app.beglaubigt.de/notarize/123e4567-e89b-12d3-a456-426614174000?token=123e4567-e89b-12d3-a456-426614174001`
The custom client reference string provided when creating the case though the API POST request.\\
**Example**: `REF-2024-001`
```
--request GET 'https://api.beglaubigt.de/v1/notarization/123e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer '
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Case fetched successfully.",
"case_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "in-progress",
"url": "https://app.beglaubigt.de/notarize/123e4567-e89b-12d3-a456-426614174000",
"documents": [
{
"status": "completed",
"original_document_id": "123e4567-e89b-12d3-a456-426614174001",
"original_document_url": "https://app.beglaubigt.de/download?bucket=documents&id=123e4567-e89b-12d3-a456-426614174001&token=b4n...omL",
"notarized_document_id": "123e4567-e89b-12d3-a456-426614174002",
"notarized_document_url": "https://app.beglaubigt.de/download?bucket=notarized_documents&id=123e4567-e89b-12d3-a456-426614174002&token=u5K...m1C"
}
],
"signers": [
{
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"url": "https://app.beglaubigt.de/notarize/123e4567-e89b-12d3-a456-426614174000?token=123e4567-e89b-12d3-a456-426614174003"
}
],
"client_reference": "REF-2024-001"
}
}
```
# Create Notarization (/notarization/post)
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Body [#body]
The jurisdiction in which the notarization will be executed.\
**Example**: `US`
The state or region within the jurisdiction.\
**Example**: `CA`
An array of documents to be notarized containing document details and signer information.
The type of document.\
**Example**: `Power of Attorney`
File details for the document.
Type of file reference.\
**Note**: Must be `url`
URL to the document file
Whether the document requires signatures before notarization.
Signature and location/date fields will be automatically identified across the entire document using AI-powered detection.
**Note**: *This feature is in beta.*
Array of signers for this document.
Email address of the signer.
First name of the signer.
Last name of the signer.
Middle name of the signer.
Date of birth of the signer in `YYYY-MM-DD` format.
Phone number of the signer.
Label information for signature positioning or other metadata.
Type of label: `signature` or `location-and-date`
`signature` : Prompts the user to sign and displays their signature.
`location-and-date` : Detects the signer’s location and records the date upon signature.
Page number for the label placement.
**Note**: *Required if autodetection is disabled.*
X coordinate for label placement.
**Note**: *Required if autodetection is disabled.*
Y coordinate for label placement.
**Note**: *Required if autodetection is disabled.*
Width of the label area.
**Note**: *Required if autodetection is disabled.*
Height of the label area.
**Note**: *Required if autodetection is disabled.*
The label field will be automatically identified using AI-powered detection. You can specify the page to improve accuracy.
**Note**: *This feature is in beta.*
Specifies the environment for the KYC API.\
**Possible values:** `sandbox`, `production`
A custom client reference string for tracking purposes.\
**Example**: `REF-2024-001`
This determines the language in which emails will be sent to the client.\
**Possible values:** `en`, `de`, `es`, `fr` or `it`
### Response [#response]
Indicates the outcome of the API request.\
**Possible values**: `success` or `error`
Provides a human-readable message detailing the result of the API request.\
**Exemple**: `Case created successfully.`
The unique identifier for the created case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The current status of the notarization request.\
**Possible values:** `in-progress` or `completed`
A unique, case-specific URL for accessing and monitoring the current status and details of the notarization process.\
**Example**: `https://app.platus.com/notarize/123e4567-e89b-12d3-a456-426614174000`
List of documents included in this notarization request.
The unique identifier for the created notarization case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The type of document as specified in the request.
Indicates the current processing state of the specific document within the notarization case.\
**Possible values**: `draft`, `signatures-requested`, `waiting-for-verifications`, `notarization-started` or `completed`
List of signers included in this notarization request.
The first name of the signer as provided during the notarization process.
The last name of the signer as provided during the notarization process.
The email address of the signer as provided during the notarization process.
A unique invitation link containing an identification token. The link prompts the signer to complete the required actions, such as signing or verifying documents, based on the notarization requirements.\
**Example**: `https://app.beglaubigt.de/notarize/123e4567-e89b-12d3-a456-426614174000?token=123e4567-e89b-12d3-a456-426614174001`
The exact date and time when the response was generated, formatted as an **ISO 8601** string in UTC.\
**Example**: `2024-12-01T07:19:30.443Z`
```json theme={null}
{
"jurisdiction": "US",
"state": "CA",
"documents": [
{
"document_type": "Power of Attorney",
"document_file": {
"type": "url",
"url": "https://app.beglaubigt.de/Power-of-Attorney.pdf"
},
"require_signatures": true,
"autodetection": false,
"signers": [
{
"email": "john@example.com",
"first_name": "John",
"middle_name": "Andreas",
"last_name": "Doe",
"dob": "1985-07-10",
"phone": "+49123456789",
"labels": [
{
"type": "signature",
"autodetection": true
},
{
"type": "location-and-date",
"page": 3,
"x_position": 396,
"y_position": 553,
"width": 270,
"height": 54,
"autodetection": false
}
]
}
]
}
],
"persona_environment": "production",
"client_reference": "REF-2024-001",
"client_preferred_language": "de"
}
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Case created successfully.",
"case_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "in-progress",
"url": "https://app.beglaubigt.de/notarize/450506c1-d1a7-46e2-aca6-41a816805595",
"documents": [
{
"id": "07347a09-7fa2-434f-a5f1-ec897f16d4b9",
"type": "Power of Attorney",
"status": "signatures-requested"
}
],
"signers": [
{
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"url": "https://app.beglaubigt.de/notarize/450506c1-d1a7-46e2-aca6-41a816805595?token=8963cd77-b5f9-4280-986d-6137e9fea106"
}
],
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"timestamp": "2025-12-01T07:19:30.443Z"
}
}
```
# Get Tax Registration (/tax-registration/get)
`GET https://api.beglaubigt.de/v1/tax-registration/:id`
Retrieve a tax registration created via [POST /v1/tax-registration](/tax-registration/post),
regardless of legal form. The response is the same shape for every family.
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Path Parameters [#path-parameters]
The `tax_registration_id` returned by the POST endpoint, in **UUID** format.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
### Response [#response]
Indicates the outcome of the API request.\
**Possible values:** `success` or `error`
Human-readable message describing the result.
The unique identifier of the tax registration in **UUID** format.
Current status, taken from the tax registration's XML draft. `draft` until an XML has been generated.\
**Possible values:** `draft`, `validated`, `submitted`, `accepted`, `rejected` or `error`
ELSTER transfer ticket, present once the registration has been submitted.
A signed URL to download the generated ELSTER XML, present once an XML draft exists. Valid for
**24 hours** after the request.
The custom reference string provided when creating the registration through the POST request.\
**Example:** `REF-2025-001`
Timestamp when the tax registration was created, as an **ISO 8601** string.
```
--request GET 'https://api.beglaubigt.de/v1/tax-registration/450506c1-d1a7-46e2-aca6-41a816805595' \
--header 'Authorization: Bearer '
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Tax registration XML document retrieved successfully.",
"tax_registration_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "validated",
"download_url": "https://app.beglaubigt.de/download?bucket=tax-questionnaire-submissions-xml&id=450506c1-d1a7-46e2-aca6-41a816805595&token=a1H...To5",
"client_reference": "REF-2025-001",
"created_at": "2025-02-01T07:19:30.443Z"
}
}
```
# Get Trade Registration (/trade-registration/get)
`GET https://api.beglaubigt.de/v1/trade-registration/:id`
Retrieve a trade registration created via [POST /v1/trade-registration](/trade-registration/post).
Access is granted to either side of the case: the provider company that created it and the client
company it was created for.
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Path Parameters [#path-parameters]
The `trade_registration_id` returned by the POST endpoint, in **UUID** format.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
### Response [#response]
Indicates the outcome of the request.\
**Possible values:** `success` or `error`
Human-readable message describing the result.\
**Example:** `Trade registration fetched successfully.`
The unique identifier of the trade registration in **UUID** format.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
The unique identifier of the client company the case belongs to, in **UUID** format.\
**Example:** `9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e`
Current status of the case. These are the states to act on, and they mirror the `registration.*`
webhook events. Further internal states can appear while the trade office is processing the case.\
**Possible values:** `initiated`, `form-rendered`, `submitted`, `completed` or `blocked`
The service package the case was created with.\
**Possible values:** `self` or `assisted`
Why the trade was registered.\
**Possible values:** `new-foundation`, `takeover`, `reopening-after-relocation`,
`legal-form-change`, `partner-entry` or `transformation-law`
The date the business begins operating, normalized to `YYYY-MM-DD`.\
**Example:** `2030-12-01`
The kind of establishment that was registered.\
**Possible values:** `main-office`, `branch-office`, `dependent-branch` or `travel-industry`
Whether the trade is the owner's main or secondary occupation.\
**Possible values:** `main-occupation` or `secondary-occupation`
The business name, taken from the client company.\
**Example:** `Musterbau GmbH`
The legal form, taken from the client company.\
**Example:** `gmbh`
The number the business is entered under in a public register, present when it is registered.\
**Example:** `HRB 123456 B`
The categories the activity falls into.\
**Possible values:** `industry`, `trade`, `craft` or `other`
Description of the registered activity, as it appears on the GewA 1.\
**Example:** `Innenausbau und Trockenbauarbeiten`
Address of the establishment. Always a German address, since only a fixed German establishment can
file a GewA 1 (§ 14 GewO).
Street and house number.\
**Example:** `Friedrichstraße 176`
A second address line (c/o, entrance, floor, ...).\
**Example:** `Aufgang C`
German 5-digit postal code.\
**Example:** `10117`
City.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code, always `DE`.\
**Example:** `DE`
Phone number of the business.\
**Example:** `+4930123456`
Email address of the business.\
**Example:** `kontakt@musterbau.de`
Details of the permit the activity requires, present when the activity needs one.
Date the permit was issued.\
**Example:** `2024-01-15`
Authority that issued the permit.\
**Example:** `Bezirksamt Mitte von Berlin`
German 5-digit postal code of the issuing authority.\
**Example:** `10117`
City of the issuing authority.\
**Example:** `Berlin`
Whether a public-sector body holds a stake in the business.\
**Possible values:** `true` or `false`
The employee counts, present when the business has employees.
Number of full-time employees, as a bracket.\
**Possible values:** `0`, `1`, `2`, `3`, `4`, `5`, `6-10`, `11-20`, `21-50` or `50+`
Number of part-time employees, as a bracket.\
**Possible values:** `0`, `1`, `2`, `3`, `4`, `5`, `6-10`, `11-20`, `21-50` or `50+`
Everyone registering the trade, in the order they were created. Each owner carries their own
permit, address and signatures.
First name.\
**Example:** `Anna`
Last name.\
**Example:** `Schmidt`
Birth name, present when it differs from the last name.\
**Example:** `Weber`
Date of birth.\
**Example:** `1986-03-12`
City of birth.\
**Example:** `Leipzig`
Country of birth as an ISO 3166-1 alpha-2 code.\
**Example:** `DE`
Nationality as an ISO 3166-1 alpha-2 code.\
**Example:** `DE`
Gender, as asked on the GewA 1.\
**Possible values:** `male`, `female`, `diverse` or `no-information`
Phone number of the owner.\
**Example:** `+4915100000001`
Email address of the owner.\
**Example:** `anna.schmidt@beispiel.de`
Timestamp of the completed identity verification (KYC), as an **ISO 8601** string. Present
once the owner has verified their identity.\
**Example:** `2025-02-03T09:12:45.000Z`
Details of this owner's residence permit, present when they hold one.
Date the permit was issued.\
**Example:** `2023-02-01`
Authority that issued the permit.\
**Example:** `Ausländerbehörde Berlin`
Whether the residence permit restricts self-employment.\
**Possible values:** `true` or `false`
This owner's residential address, present when they live elsewhere than the establishment.
Street and house number.\
**Example:** `Kastanienallee 12`
A second address line.\
**Example:** `Hinterhaus`
Postal code.\
**Example:** `10435`
City.\
**Example:** `Berlin`
State or region.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code.\
**Example:** `DE`
The trade office (Gewerbeamt) the registration is filed with, present once it has been determined.
Name of the trade office.\
**Example:** `Gewerbeamt Berlin-Mitte`
Postal address of the trade office, as a single line.\
**Example:** `Karl-Marx-Allee 31, 10178 Berlin`
Email address of the trade office.\
**Example:** `gewerbeamt@ba-mitte.berlin.de`
Phone number of the trade office.\
**Example:** `+4930901823456`
Website of the trade office.\
**Example:** `https://www.berlin.de/ba-mitte`
Price of the service in euros.\
**Example:** `89`
The trade office's registration fee in euros, present once it is known.\
**Example:** `26.5`
Whether the case has been paid.\
**Possible values:** `true` or `false`
The documents of the case. The filled GewA 1 form (`trade-licence-application`) exists from
creation; the trade licence (`trade-licence`) is added once the trade office has issued it.
The unique identifier of the document in **UUID** format.\
**Example:** `baa38d14-c224-4894-823a-87536c5e45d4`
The document type.\
**Possible values:** `trade-licence-application` or `trade-licence`
Display name of the document.\
**Example:** `GewA 1 - Gewerbe-Anmeldung`
A signed URL to download the document as a PDF. Valid for **24 hours** after the request.\
**Example:** `https://app.beglaubigt.de/download?bucket=company-documents&id=baa38d14-c224-4894-823a-87536c5e45d4&token=a1H...To5`
Set when the trade registration was spawned by another Beglaubigt product.\
**Possible values:** `gbr` or `null`
The custom reference string provided when creating the registration through the POST request.\
**Example:** `REF-2025-001`
The language used when communicating with the client.\
**Possible values:** `en`, `fr`, `de`, `it` or `es`
Timestamp when the trade registration was created, as an **ISO 8601** string.\
**Example:** `2025-02-01T07:19:30.443Z`
```
--request GET 'https://api.beglaubigt.de/v1/trade-registration/450506c1-d1a7-46e2-aca6-41a816805595' \
--header 'Authorization: Bearer '
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Trade registration fetched successfully.",
"trade_registration_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"company_id": "9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e",
"status": "submitted",
"package": "assisted",
"reason": "new-foundation",
"operational_activity_start_date": "2030-12-01",
"establishment_type": "main-office",
"acquisition_type": "main-occupation",
"name": "Musterbau GmbH",
"legal_form": "gmbh",
"registration_number": "HRB 123456 B",
"business_type": ["craft", "trade"],
"purpose": "Innenausbau und Trockenbauarbeiten",
"registered_office": {
"street": "Friedrichstraße 176",
"street_second_line": "Aufgang C",
"zip": "10117",
"city": "Berlin",
"country": "DE"
},
"phone": "+4930123456",
"email": "kontakt@musterbau.de",
"industrial_license": {
"issue_date": "2024-01-15",
"issuing_authority": "Bezirksamt Mitte von Berlin",
"zip": "10117",
"location": "Berlin"
},
"has_public_sector_participation": false,
"employees": {
"full_time": "6-10",
"part_time": "2"
},
"owners": [
{
"first_name": "Anna",
"last_name": "Schmidt",
"birth_name": "Weber",
"dob": "1986-03-12",
"place_of_birth": "Leipzig",
"country_of_birth": "DE",
"nationality": "DE",
"gender": "female",
"phone": "+4915100000001",
"email": "anna.schmidt@beispiel.de",
"identity_verified_at": "2025-02-03T09:12:45.000Z",
"address": {
"street": "Kastanienallee 12",
"zip": "10435",
"city": "Berlin",
"state": "Berlin",
"country": "DE"
}
},
{
"first_name": "Jonas",
"last_name": "Meier",
"dob": "1984-02-11",
"place_of_birth": "Bremen",
"country_of_birth": "DE",
"nationality": "DE",
"gender": "male",
"phone": "+4915100000004",
"email": "jonas.meier@beispiel.de"
}
],
"trade_office": {
"name": "Gewerbeamt Berlin-Mitte",
"address": "Karl-Marx-Allee 31, 10178 Berlin",
"email": "gewerbeamt@ba-mitte.berlin.de",
"phone": "+4930901823456",
"website": "https://www.berlin.de/ba-mitte"
},
"price": 89,
"city_fee": 26.5,
"is_paid": true,
"documents": [
{
"id": "baa38d14-c224-4894-823a-87536c5e45d4",
"type": "trade-licence-application",
"name": "GewA 1 - Gewerbe-Anmeldung",
"download_url": "https://app.beglaubigt.de/download?bucket=company-documents&id=baa38d14-c224-4894-823a-87536c5e45d4&token=a1H...To5"
}
],
"source_product": null,
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"created_at": "2025-02-01T07:19:30.443Z"
}
}
```
# Create Trade Registration (/trade-registration/post)
`POST https://api.beglaubigt.de/v1/trade-registration`
## Authorization [#authorization]
Include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
## Request [#request]
### Core [#core]
Assign the trade registration to a specific existing company. The company must not already
have a trade registration; if it does, the request returns `409 COMPANY_ALREADY_REGISTERED`.
**Omit it** to have a new client company created and linked automatically.\
**Example:** `9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e`
The service package.\
**Possible values:** `self` or `assisted`
Sets the created company's type: `sandbox` creates a staging company for testing, `production`
creates a live company.\
**Possible values:** `sandbox` or `production`
A custom reference string for your own tracking.\
**Example:** `REF-2025-001`
The language used when communicating with the client.\
**Possible values:** `en`, `fr`, `de`, `it` or `es`
### Registration [#registration]
Why the trade is being registered.\
**Possible values:** `new-foundation`, `takeover`, `reopening-after-relocation`,
`legal-form-change`, `partner-entry` or `transformation-law`
The date the business begins operating. May be in the past, since a Gewerbe is often registered
once trading has already started. Format: `YYYY-MM-DD`.\
**Example:** `2030-12-01`
The kind of establishment being registered.\
**Possible values:** `main-office`, `branch-office`, `dependent-branch` or `travel-industry`
Whether the trade is the owner's main or secondary occupation.\
**Possible values:** `main-occupation` or `secondary-occupation`
### Company [#company]
The business name including the legal-form suffix where one applies. Max 120 characters.\
**Example:** `Musterbau GmbH`
The legal form of the company.\
**Possible values:** `einzelunternehmen`, `ug`, `gmbh`, `gbr`, `einzelkaufmann-ek`, `gmbh-co-kg`,
`kg`, `ohg`, `ug-co-kg`, `ggmbh`, `ag`, `kgaa` or `other`
The number the business is entered under in a public register (Handelsregister,
Genossenschaftsregister or Gesellschaftsregister). **Omit it** when the business is not registered.
Max 30 characters.\
**Example:** `HRB 123456 B`
The categories the activity falls into, at least one.\
**Possible values:** `industry`, `trade`, `craft` or `other`
Description of the business activity. Max 200 characters. Like every free-text field, it has to be
renderable on the GewA 1, so Latin characters only.\
**Example:** `Innenausbau und Trockenbauarbeiten`
Address of the establishment. Only a fixed German establishment can file a GewA 1 (§ 14 GewO), so
the address takes no country and the postal code must be a German 5-digit code.
Street and house number. Max 72 characters.\
**Example:** `Friedrichstraße 176`
A second address line (c/o, entrance, floor, ...). Max 72 characters.\
**Example:** `Aufgang C`
German 5-digit postal code.\
**Example:** `10117`
City. Max 72 characters, no digits.\
**Example:** `Berlin`
Business address for the client company. Only applies when
a new company is created (omit `company_id`); it is rejected if sent together with `company_id`.
Unlike `registered_office`, it can be outside Germany.
Street and house number.\
**Example:** `Torstraße 1`
Postal code.\
**Example:** `10119`
City.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code.\
**Example:** `de`
A second address line (c/o, suite, ...).\
**Example:** `c/o Muster`
State or region.\
**Example:** `Berlin`
Phone number of the business. Digits, spaces and `+ ( ) . / -` only, 6 to 32 characters.\
**Example:** `+4930123456`
Email address of the business.\
**Example:** `kontakt@musterbau.de`
### Licenses & Public Sector [#licenses--public-sector]
Details of the permit or licence the activity requires (Erlaubnispflicht). **Omit it** when the
activity needs none.
Date the permit was issued. Must be in the past. Format: `YYYY-MM-DD`.\
**Example:** `2024-01-15`
Authority that issued the permit. Max 120 characters.\
**Example:** `Bezirksamt Mitte von Berlin`
German 5-digit postal code of the issuing authority.\
**Example:** `10117`
City of the issuing authority.\
**Example:** `Berlin`
Whether a public-sector body holds a stake in the business.\
**Possible values:** `true` or `false`
### Employees [#employees]
The employee counts. **Omit it** when the business has no employees; the GewA 1 asks for both
counts, so both are required once it is sent.
Number of full-time employees, as a bracket.\
**Possible values:** `0`, `1`, `2`, `3`, `4`, `5`, `6-10`, `11-20`, `21-50` or `50+`
Number of part-time employees, as a bracket.\
**Possible values:** `0`, `1`, `2`, `3`, `4`, `5`, `6-10`, `11-20`, `21-50` or `50+`
### Owners [#owners]
Everyone registering the trade, 1 to 9 entries, in the order they should appear. Each owner signs
their own GewA 1 and, on the `assisted` package, their own power of attorney.
First name of the owner. Max 72 characters.\
**Example:** `Anna`
Last name of the owner. Max 72 characters.\
**Example:** `Schmidt`
Birth name of the owner. **Omit it** when it is the same as `last_name`. Max 72 characters.\
**Example:** `Weber`
Date of birth of the owner. Format: `YYYY-MM-DD`.\
**Example:** `1986-03-12`
City of birth of the owner.\
**Example:** `Leipzig`
Country of birth of the owner, as an ISO 3166-1 alpha-2 code.\
**Example:** `DE`
Nationality of the owner, as an ISO 3166-1 alpha-2 code.\
**Example:** `DE`
Gender of the owner.\
**Possible values:** `male`, `female`, `diverse` or `no-information`
Phone number of the owner. Digits, spaces and `+ ( ) . / -` only, 6 to 32 characters.\
**Example:** `+4915100000001`
Email address of the owner.\
**Example:** `anna.schmidt@beispiel.de`
This owner's signatures.
Signature for this owner's GewA 1 form. Send either this or `documents.gewa_1`, never both:
a form you supply is signed already.\
**Example:** `M 10 10 L 90 90 M 90 10 L 10 90`
Signature for this owner's power of attorney (Vollmacht zur Einreichung). Required for the
`assisted` package, which files the registration on their behalf, and rejected for `self`.\
**Example:** `M 10 10 L 90 90 M 90 10 L 10 90`
This owner's own documents. **Omit it** to have everything generated for you.
Attach this owner's already-signed GewA 1 instead of having one filled from the data you
send. Omit it, and send `signatures.gewa_1` instead, to have it generated.
The name of the file part carrying the signed form. Send the request as
`multipart/form-data`, with the payload in a `data` field and the form in a part of
this name. It must be a PDF, at most 50 MB.\
**Example:** `gewa-anna-schmidt`
Details of this owner's residence permit. **Omit it** when they hold none.
Date the permit was issued. Must be in the past. Format: `YYYY-MM-DD`.\
**Example:** `2023-02-01`
Authority that issued the permit. Max 120 characters.\
**Example:** `Ausländerbehörde Berlin`
Whether the residence permit restricts self-employment. Required when this owner's
`residence_permit` is sent, and rejected when it is not.\
**Possible values:** `true` or `false`
This owner's residential address. **Omit it** when they live at the establishment. They may
live abroad; the country decides the postal-code rule.
Street and house number. Max 72 characters.\
**Example:** `Kastanienallee 12`
A second address line. Max 72 characters.\
**Example:** `Hinterhaus`
Postal code. Must be a German 5-digit code when `country` is `DE`. Max 12 characters.\
**Example:** `10435`
City. Max 72 characters, no digits.\
**Example:** `Berlin`
State or region. Max 72 characters.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code.\
**Example:** `CH`
## Response [#response]
Outcome of the request.\
**Possible values:** `success` or `error`
Human-readable outcome message.\
**Example:** `Trade registration created successfully.`
UUID of the client company the case belongs to, created here when you omitted `company_id`.\
**Example:** `9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e`
UUID of the trade registration case. Use it with the GET endpoint.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
The status the case landed in, driven by `package`.\
**Possible values:** `form-rendered` or `submitted`
The owners as they were created, in the order you sent them, each with the documents they signed.
A download link is valid for **24 hours**.
First name, echoed back so the entry can be matched to the one you sent.\
**Example:** `Anna`
Last name.\
**Example:** `Schmidt`
This owner's documents. A key is absent when that document could not be generated.
The GewA 1 (Gewerbeanmeldung): filled from your data and carrying this owner's signature,
or the form you supplied in `documents.gewa_1`.
The signed Vollmacht zur Einreichung. Present for the `assisted` package only, which is the
one that files the registration on the owners' behalf.
The unique identifier of the document in **UUID** format.\
**Example:** `baa38d14-c224-4894-823a-87536c5e45d4`
Display name of the document, suffixed with the owner it belongs to.\
**Example:** `GewA 1 - Gewerbe-Anmeldung (Anna Schmidt)`
A signed URL to download the document as a PDF.\
**Example:** `https://app.beglaubigt.de/download?bucket=company-documents&id=baa38d14-c224-4894-823a-87536c5e45d4&token=a1H...To5`
The custom reference string you provided.\
**Example:** `REF-2025-001`
The language used when communicating with the client.\
**Possible values:** `en`, `fr`, `de`, `it` or `es`
ISO 8601 timestamp of the response.\
**Example:** `2025-02-01T07:19:30.443Z`
## Example [#example]
```json theme={null}
{
"name": "Musterbau GmbH",
"legal_form": "gmbh",
"package": "assisted",
"reason": "new-foundation",
"establishment_type": "main-office",
"acquisition_type": "main-occupation",
"registration_number": "HRB 123456 B",
"operational_activity_start_date": "2030-12-01",
"business_type": ["craft", "trade"],
"purpose": "Innenausbau und Trockenbauarbeiten",
"phone": "+4930123456",
"email": "kontakt@musterbau.de",
"registered_office": {
"street": "Friedrichstraße 176",
"street_second_line": "Aufgang C",
"zip": "10117",
"city": "Berlin"
},
"business_address": {
"street": "Torstraße 1",
"street_second_line": "c/o Muster",
"zip": "10119",
"city": "Berlin",
"state": "Berlin",
"country": "de"
},
"industrial_license": {
"issue_date": "2024-01-15",
"issuing_authority": "Bezirksamt Mitte von Berlin",
"zip": "10117",
"location": "Berlin"
},
"has_public_sector_participation": false,
"employees": {
"full_time": "6-10",
"part_time": "2"
},
"owners": [
{
"first_name": "Anna",
"last_name": "Schmidt",
"birth_name": "Weber",
"dob": "1986-03-12",
"place_of_birth": "Basel",
"country_of_birth": "CH",
"nationality": "CH",
"gender": "female",
"phone": "+4915100000001",
"email": "anna.schmidt@beispiel.de",
"signatures": {
"gewa_1": "M 10 10 L 90 90 M 90 10 L 10 90",
"power_of_attorney": "M 10 10 L 90 90 M 90 10 L 10 90"
},
"residence_permit": {
"issue_date": "2023-02-01",
"issuing_authority": "Ausländerbehörde Berlin"
},
"has_employment_restrictions": false,
"address": {
"street": "Kastanienallee 12",
"street_second_line": "Hinterhaus",
"zip": "10435",
"city": "Berlin",
"state": "Berlin",
"country": "DE"
}
},
{
"first_name": "Jonas",
"last_name": "Meier",
"dob": "1984-02-11",
"place_of_birth": "Bremen",
"country_of_birth": "DE",
"nationality": "DE",
"gender": "male",
"phone": "+4915100000004",
"email": "jonas.meier@beispiel.de",
"signatures": {
"gewa_1": "M 20 20 L 80 80",
"power_of_attorney": "M 20 20 L 80 80"
}
}
],
"environment": "sandbox",
"client_reference": "REF-2025-001",
"client_preferred_language": "de"
}
```
The payload travels in the `data` field of a `multipart/form-data` request, with one
part per attached form:
```bash theme={null}
curl https://api.beglaubigt.de/v1/trade-registration \
-H "Authorization: Bearer sk-123e4567-e89b-12d3-a456-426614174000" \
-F 'data=' \
-F 'gewa-anna-schmidt=@gewa-1-anna-schmidt.pdf;type=application/pdf' \
-F 'gewa-jonas-meier=@gewa-1-jonas-meier.pdf;type=application/pdf'
```
```json theme={null}
{
"name": "Musterbau GmbH",
"legal_form": "gmbh",
"package": "assisted",
"reason": "new-foundation",
"establishment_type": "main-office",
"acquisition_type": "main-occupation",
"registration_number": "HRB 123456 B",
"operational_activity_start_date": "2030-12-01",
"business_type": ["craft", "trade"],
"purpose": "Innenausbau und Trockenbauarbeiten",
"phone": "+4930123456",
"email": "kontakt@musterbau.de",
"registered_office": {
"street": "Friedrichstraße 176",
"street_second_line": "Aufgang C",
"zip": "10117",
"city": "Berlin"
},
"business_address": {
"street": "Torstraße 1",
"street_second_line": "c/o Muster",
"zip": "10119",
"city": "Berlin",
"state": "Berlin",
"country": "de"
},
"industrial_license": {
"issue_date": "2024-01-15",
"issuing_authority": "Bezirksamt Mitte von Berlin",
"zip": "10117",
"location": "Berlin"
},
"has_public_sector_participation": false,
"employees": {
"full_time": "6-10",
"part_time": "2"
},
"owners": [
{
"first_name": "Anna",
"last_name": "Schmidt",
"birth_name": "Weber",
"dob": "1986-03-12",
"place_of_birth": "Basel",
"country_of_birth": "CH",
"nationality": "CH",
"gender": "female",
"phone": "+4915100000001",
"email": "anna.schmidt@beispiel.de",
"documents": {
"gewa_1": {
"file": "gewa-anna-schmidt"
}
},
"signatures": {
"power_of_attorney": "M 10 10 L 90 90 M 90 10 L 10 90"
},
"residence_permit": {
"issue_date": "2023-02-01",
"issuing_authority": "Ausländerbehörde Berlin"
},
"has_employment_restrictions": false,
"address": {
"street": "Kastanienallee 12",
"street_second_line": "Hinterhaus",
"zip": "10435",
"city": "Berlin",
"state": "Berlin",
"country": "DE"
}
},
{
"first_name": "Jonas",
"last_name": "Meier",
"dob": "1984-02-11",
"place_of_birth": "Bremen",
"country_of_birth": "DE",
"nationality": "DE",
"gender": "male",
"phone": "+4915100000004",
"email": "jonas.meier@beispiel.de",
"documents": {
"gewa_1": {
"file": "gewa-jonas-meier"
}
},
"signatures": {
"power_of_attorney": "M 20 20 L 80 80"
}
}
],
"environment": "sandbox",
"client_reference": "REF-2025-001",
"client_preferred_language": "de"
}
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Trade registration created successfully.",
"company_id": "9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e",
"trade_registration_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "submitted",
"owners": [
{
"first_name": "Anna",
"last_name": "Schmidt",
"documents": {
"gewa_1": {
"id": "baa38d14-c224-4894-823a-87536c5e45d4",
"name": "GewA 1 - Gewerbe-Anmeldung (Anna Schmidt)",
"download_url": "https://app.beglaubigt.de/download?bucket=company-documents&id=baa38d14-c224-4894-823a-87536c5e45d4&token=a1H...To5"
},
"power_of_attorney": {
"id": "7c1f0f42-9a6d-4a1e-bb18-2f0f0a4d9c33",
"name": "Vollmacht zur Einreichung (Anna Schmidt)",
"download_url": "https://app.beglaubigt.de/download?bucket=company-documents&id=7c1f0f42-9a6d-4a1e-bb18-2f0f0a4d9c33&token=b2K...Qp9"
}
}
},
{
"first_name": "Jonas",
"last_name": "Meier",
"documents": {
"gewa_1": {
"id": "1f9c7a55-3b64-4a20-9f0e-5c4a2d7b6e11",
"name": "GewA 1 - Gewerbe-Anmeldung (Jonas Meier)",
"download_url": "https://app.beglaubigt.de/download?bucket=company-documents&id=1f9c7a55-3b64-4a20-9f0e-5c4a2d7b6e11&token=c3L...Rt2"
},
"power_of_attorney": {
"id": "9d2b8e07-4c15-4d33-8a72-6e1f0b3c9a48",
"name": "Vollmacht zur Einreichung (Jonas Meier)",
"download_url": "https://app.beglaubigt.de/download?bucket=company-documents&id=9d2b8e07-4c15-4d33-8a72-6e1f0b3c9a48&token=d4M...Su3"
}
}
}
],
"client_reference": "REF-2025-001",
"client_preferred_language": "de",
"timestamp": "2025-02-01T07:19:30.443Z"
}
}
```
# Get Translation (/translation/get)
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Path Parameters [#path-parameters]
The unique identifier of the translation case to retrieve.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
### Response [#response]
Indicates the outcome of the request.\
**Possible values**: `success` or `error`
A human-readable summary of the result.\
**Example**: `Translation fetched successfully.`
The unique identifier for the translation case in a **UUID** format.\
**Example**: `123e4567-e89b-12d3-a456-426614174000`
The current status of the translation process.\
**Possible values**: `draft`, `pending`, `completed`, `archive`, `feedback-requested` or `refund-needed`
The service type.\
**Possible values**: `standard` or `certified`
The 2-letter ISO country code of the country where the certified translation is valid.\
**Example**: `DE`
The ISO code of the language the original document is written in.\
**Example**: `de`
The ISO code of the language the document should be translated into.\
**Example**: `en`
Indicates if a legal apostille was requested for the translated documents.\\
The priority level of the request.\
**Possible values**: `standard`, `priority` or `express`
List of documents associated with this case.
Unique document UUID.\
**Example**: `123e4567-e89b-12d3-a456-426614174001`
The role of the document in the case.\
**Possible values**: `original` or `translation`
The file name of the document.\
**Example**: `birth_certificate.pdf`
Number of pages in the document.\
**Example**: `2`
A temporary signed URL to download the PDF. Valid for **24 hours**.\
**Example**: `https://app.beglaubigt.de/download?bucket=translation-documents&id=123e4567-e89b-12d3-a456-426614174000&token=a1H...To5`
The selected delivery method for the final documents.\
**Possible values**: `email`, `postal` or `express`
Indicates if order insurance was applied to the request.
Information about the requesting client.
The first name of the client.\
**Example**: `John`
The last name of the client.\
**Example**: `Doe`
The email address of the client.\
**Example**: `john.doe@example.com`
The phone number of the client.\
**Example**: `+491701234567`
The physical address where the documents will be shipped.
The type of recipient.\
**Possible values**: `private` or `business` \\
The first name of the recipient.\
**Example**: `John`
The last name of the recipient.\
**Example**: `Doe`
The name of the company.\
**Example**: `Beglaubigt GmbH`
The street name and house number.\
**Example**: `Hauptstraße 12`
The city of the address.\
**Example**: `Berlin`
The postal code.\
**Example**: `10115`
The 2-letter ISO country code.\
**Example**: `DE`
Additional information like floor, suite, or apartment.\
**Example**: `Hinterhaus, 2. OG`
The address used for invoicing. Follows the same structure as `delivery_address`.
The total price of the translation in EUR.\
**Example**: `85.50`
Direct dashboard link to the case.\
**Example**: `https://app.beglaubigt.de/cases/123e4567-e89b-12d3-a456-426614174000`
The custom reference provided during request creation.\
**Example**: `PO-99821`
The ISO code for notification preferences.\
**Possible values**: `de`, `en`, `fr`, `es` or `it`
ISO 8601 timestamp of translation creation.\
**Example**: `2026-02-07T14:21:30.000Z`
```
--request GET 'https://api.beglaubigt.de/v1/translation/123e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer '
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Translation fetched successfully.",
"translation_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "pending",
"translation_type": "certified",
"certification_jurisdiction": "DE",
"source_language": "de",
"target_language": "en",
"is_apostille_needed": true,
"urgency": "priority",
"documents": [
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"type": "original",
"name": "birth_certificate.pdf",
"pages": 2,
"download_url": "https://app.beglaubigt.de/download?bucket=translation-documents&id=123e4567-e89b-12d3-a456-426614174001&token=a1H...To5"
}
],
"delivery_method": "express",
"is_insurance_needed": false,
"client_details": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+491701234567"
},
"delivery_address": {
"person_type": "private",
"first_name": "John",
"last_name": "Doe",
"street": "Hauptstraße 12",
"additional": "Hinterhaus, 2. OG",
"city": "Berlin",
"zip": "10115",
"country": "DE"
},
"billing_address": {
"person_type": "private",
"first_name": "John",
"last_name": "Doe",
"street": "Hauptstraße 12",
"city": "Berlin",
"zip": "10115",
"country": "DE"
},
"price": 85.50,
"url": "[https://app.beglaubigt.de/cases/123e4567-e89b-12d3-a456-42661417400]",
"client_reference": "PO-99821",
"client_preferred_language": "de",
"created_at": "2026-02-07T14:21:30.000Z"
}
}
```
# Create Translation (/translation/post)
### Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
### Body [#body]
The type of translation service required. Use `certified` for officially recognized translations for authorities, or `standard` for professional business and private documents.\
**Possible values**: `standard` or `certified`
The 2-letter ISO country code of the country where the certified translation will be used.\
**Example**: `DE`\
**Note**: Required if `translation_type` is `certified`.
The ISO code of the language the original document is written in. Refer to the list of supported languages below.\
**Example**: `de`
The ISO code of the language the document should be translated into. Refer to the list of supported languages below.\
**Example**: `en`
| Language | ISO | Language | ISO | Language | ISO |
| :------------- | :-------- | :-------------- | :------ | :------------- | :-------- |
| Afrikaans | `af` | Hebrew | `he` | Norwegian | `no` |
| Amharic | `am` | Hindi | `hi` | Punjabi | `pa` |
| Arabic | `ar` | Croatian | `hr` | Polish | `pl` |
| Azerbaijani | `az` | Haitian Creole | `ht` | Pashto/Pushto | `ps` |
| Belarusian | `be` | Hungarian | `hu` | Portuguese | `pt-pt` |
| Bulgarian | `bg` | Armenian | `hy` | Romanian | `ro` |
| Bengali/Bangla | `bn` | Indonesian | `id` | Moldavian | `mo` |
| Catalan | `ca` | Icelandic | `is` | Singhalese | `si` |
| Czech | `cs` | Italian | `it` | Slovak | `sk` |
| Russian | `ru` | Japanese | `ja` | Slovenian | `sl` |
| Danish | `da` | Georgian | `ka` | Somali | `so` |
| German | `de` | Khmer | `km` | Albanian | `sq` |
| Greek | `el` | Kannada | `kn` | Serbian | `sr` |
| English | `en-gb` | Korean | `ko` | Swedish | `sv` |
| Spanish | `es` | Kurdish | `ku` | Swahili | `sw` |
| Estonian | `et` | Latin | `la` | Tamil | `ta` |
| Finnish | `fi` | Lingala | `ln` | Thai | `th` |
| French | `fr` | Lithuanian | `lt` | Tigrinya | `ti` |
| Farsi | `fy` | Latvian/Lettish | `lv` | Tagalog | `tl` |
| Irish | `ga` | Maori | `mi` | Turkish | `tr` |
| Gujarati | `gu` | Macedonian | `mk` | Ukrainian | `uk` |
| Hausa | `ha` | Mongolian | `mn` | Urdu | `ur` |
| Marathi | `mr` | Malay | `ms` | Uzbek | `uz` |
| Vietnamese | `vi` | Yoruba | `yo` | Chinese (Simp) | `zh-hans` |
| Chinese (Trad) | `zh-hant` | Dari | `fa-af` | Maltese | `mt` |
| Burmese | `my` | Nepali | `ne` | Dutch | `nl` |
> **Warning**: While we support a wide range of languages, certain specific language combinations are currently unavailable. Please review the **Unsupported Language Pairs** section below before submitting your request to avoid validation errors.
Requests for the following specific language combinations will return a `422` error:
| From (Source) | To (Target) | From (Source) | To (Target) |
| :----------------- | :---------------- | :---------------- | :---------------- |
| Afrikaans (`af`) | German (`de`) | Dutch (`nl`) | German (`de`) |
| Afrikaans (`af`) | English (`en-gb`) | French (`fr`) | Nepali (`ne`) |
| Albanian (`sq`) | Lithuanian (`lt`) | Georgian (`ka`) | Lithuanian (`lt`) |
| Albanian (`sq`) | Spanish (`es`) | Indonesian (`id`) | Spanish (`es`) |
| Azerbaijani (`az`) | Dutch (`nl`) | Latvian (`lv`) | Dutch (`nl`) |
| Azerbaijani (`az`) | English (`en-gb`) | Lithuanian (`lt`) | Croatian (`hr`) |
| Bengali (`bn`) | German (`de`) | Malay (`ms`) | German (`de`) |
| Bulgarian (`bg`) | Ukrainian (`uk`) | Marathi (`mr`) | French (`fr`) |
| Burmese (`my`) | French (`fr`) | Marathi (`mr`) | German (`de`) |
| Burmese (`my`) | German (`de`) | Polish (`pl`) | English (`en-gb`) |
| Burmese (`my`) | Spanish (`es`) | Romanian (`ro`) | Indonesian (`id`) |
| Dari (`fa-af`) | English (`en-gb`) | | |
The priority level of the request.
`standard`: 3-5 business days.\
`priority`: \~48 hours.\
`urgent`: \~24 hours.
**Possible values**: `standard`, `priority` or `urgent`\
**Default value**: `standard`
Indicates if a legal apostille is required for the translated documents.\
**Default value**: `false`
An array of strings containing the URLs of the documents to be translated.\
**Example**: `["https://example.com/doc1.pdf"]`
How the final translation should be delivered.\
**Possible values**: `email`, `postal` or `express`\
**Default value**: `email`
Additional instructions or notes for the translator (Max 191 characters).\
**Example**: `Please ignore the handwritten scribbles at the bottom of the page.`
Whether to include insurance for the translation order.\
**Default value**: `false`
Information about the person requesting the translation.
First name of the client.\
**Example**: `John`
Last name of the client.\
**Example**: `Doe`
Email address for communication and digital delivery.\
**Example**: `john.doe@example.com`
Contact phone number in international format.\
**Example**: `+4915222320123`
The physical address for shipping.\
**Note**: Required if `delivery_method` is `postal` or `express`.
**Possible values**: `private` or `business`\
**Default value**: `private`
Recipient's first name.\
**Example**: `Max`
Recipient's last name.\
**Example**: `Mustermann`
Name of the company (if applicable).\
**Example**: `Muster GmbH`
Street name and house number.\
**Example**: `Schillerstraße 15`
City name.\
**Example**: `Berlin`
Postal/Zip code.\
**Example**: `10115`
2-letter ISO country code.\
**Example**: `DE`
Contact phone for delivery.\
**Example**: `+493012345678`
Extra details (e.g., Suite, Apartment, Floor).\
**Example**: `Hinterhaus, 2. OG`
The address to be used for the invoice. Uses the same structure as `delivery_address`.
A custom reference string for internal tracking.\
**Example**: `PO-99821`
Preferred language for automated notifications.\
**Possible values**: `en`, `de`, `es`, `fr` or `it`
### Response [#response]
Indicates the outcome of the request.\
**Possible values**: `success` or `error`
A human-readable summary of the result.\
**Example**: `Translation created successfully.`
The unique **UUID** identifying the created translation case.\
**Example**: `8963cd77-b5f9-4280-986d-6137e9fea106`
The initial status of the translation.\
**Value**: `pending`
The dashboard URL to monitor the translation progress.\
**Example**: `https://app.beglaubigt.de/cases/123e4567-e89b-12d3-a456-426614174000`
The ISO 8601 timestamp of when the case was created.
```json theme={null}
{
"translation_type": "certified",
"certification_jurisdiction": "DE",
"source_language": "de",
"target_language": "en",
"urgency": "priority",
"is_apostille_needed": true,
"translator_notes": "Please ensure the name 'Müller' is transliterated exactly as written.",
"documents": [
"https://example.com/my-document.pdf"
],
"delivery_method": "express",
"is_insurance_needed": false,
"client_details": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+491701234567"
},
"delivery_address": {
"person_type": "private",
"first_name": "John",
"last_name": "Doe",
"street": "Hauptstraße 12",
"additional": "Hinterhaus, 2. OG",
"city": "Berlin",
"zip": "10115",
"country": "DE"
},
"client_reference": "MY_CLIENT_12345"
}
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Translation created successfully.",
"translation_id": "8963cd77-b5f9-4280-986d-6137e9fea106",
"status": "pending",
"url": "https://app.beglaubigt.de/cases/8963cd77-b5f9-4280-986d-6137e9fea106",
"timestamp": "2026-02-07T14:21:30.000Z",
"client_reference": "MY_CLIENT_12345"
}
}
```
# Freiberufler / Einzelunternehmen (/tax-registration/post/eun)
`POST https://api.beglaubigt.de/v1/tax-registration`
The request for a **Freiberufler** or **Einzelunternehmen** (freelancer or sole proprietor). `legal_form`
is `einzelunternehmen`, which maps to the ELSTER **FsE\_EUn** form. There is no company entity: the
taxpayer is the owner, and the client company is named after them.
## Authorization [#authorization]
Include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
## Request [#request]
### Core [#core]
Assign the tax registration to a specific existing company. The company must not already have a tax
registration; if it does, the request returns `409 COMPANY_ALREADY_REGISTERED`. The `environment` must
match the company: a `sandbox` registration cannot be assigned to a production company (or the reverse),
which returns `409 ENVIRONMENT_MISMATCH`. An unknown `company_id` returns `404 COMPANY_NOT_FOUND`. **Omit it** to have a new company created and linked automatically.\
**Example:** `9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e`
Business address for the client company. Only applies when a
new company is created (omit `company_id`); it is rejected if sent together with `company_id`.
Street and house number.\
**Example:** `Torstraße 1`
Postal code.\
**Example:** `10119`
City.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code.\
**Example:** `de`
A second address line (c/o, suite, …).\
**Example:** `c/o Muster`
State or region.\
**Example:** `Berlin`
The legal form.\
**Possible values:** `einzelunternehmen`
The service package the client selected.\
**Possible values:** `self` or `guided`
The client's signature as an SVG path string (the drawn signature).\
**Example:** `M 10 10 L 90 90 M 90 10 L 10 90`
The ELSTER environment to file against. It also sets the created company's type: `sandbox` creates a
staging company and files against test ELSTER; `production` creates a live company.\
**Possible values:** `sandbox` or `production`
A custom reference string for your own tracking.\
**Example:** `REF-2025-001`
### Business [#business]
Description of the business activity. Max 200 characters.\
**Example:** `Freiberufliche IT-Beratung`
The date the business begins operating. Format: `YYYY-MM-DD`.\
**Example:** `2025-04-01`
### Owner & Address [#owner--address]
The natural person behind the sole proprietorship (Inhaber).
First name. Max 72 characters.\
**Example:** `Max`
Last name. Max 72 characters.\
**Example:** `Mustermann`
Contact email, kept for follow-up, not part of the ELSTER filing.\
**Example:** `max.mustermann@example.com`
Contact phone, kept for follow-up, not part of the ELSTER filing.\
**Example:** `+491701234567`
Date of birth. Format: `YYYY-MM-DD`.\
**Example:** `1985-07-10`
Exercised profession (Berufsbezeichnung). Max 51 characters.\
**Example:** `IT-Berater`
German tax ID (Steuer-Identifikationsnummer): 11 digits, validated with the ISO 7064 (Mod 11,10) checksum.\
**Example:** `09481663279`
2-digit church-tax key (Religionsschlüssel); `11` means not liable for church tax.\
**Example:** `11`
Existing personal tax number (Steuernummer), 13-digit unified format.\
**Example:** `1121081508150`
Owner's residence (see the [Address object](#address-object)). A residence abroad is expressed by the address `country` (anything other than `de`).
Whether the business address equals the owner's home address.\
**Possible values:** `true` or `false`
Business address, required when `address_same_as_home` is `false` (see the [Address object](#address-object)).
### Bank Account [#bank-account]
The owner's business bank account IBAN. For a non-German IBAN you must also supply `bic`.\
**Example:** `DE89370400440532013000`
The bank identifier (BIC/SWIFT) for the account, 8 to 11 characters. Required for non-German IBANs.\
**Example:** `COBADEFFXXX`
### Revenue & Profit Estimates [#revenue--profit-estimates]
Estimated revenue and taxable profit for the formation year and the following year. All amounts are
whole euros.
Estimates for the formation year (the year the business starts operating).
Estimated revenue. Cannot be lower than `profit_amount`.\
**Example:** `20000`
Estimated taxable profit.\
**Example:** `18000`
Estimates for the year after the formation year.
Estimated revenue. Cannot be lower than `profit_amount`.\
**Example:** `35000`
Estimated taxable profit.\
**Example:** `30000`
### VAT [#vat]
Freelancers (Freiberufler) are always taxed on a cash basis (Ist-Versteuerung, § 20 UStG), so
`vat.accounting_method` does not apply to this form.
The company's VAT setup.
The VAT regime the company elects. `small-business` elects the small-business exemption (Kleinunternehmer,
§ 19 UStG); `standard` is the regular VAT regime (Regelbesteuerung). Required when the election is available
(founding-year revenue ≤ €25,000 and following-year ≤ €100,000). Above €25,000 the company is on the regular
VAT regime regardless, so the field has no effect there.\
**Possible values:** `small-business` or `standard`
Whether you expect to owe VAT to the tax office (`payable`, Zahllast) or receive a refund (`refundable`, Überschuss).\
**Possible values:** `payable` or `refundable`
Estimated net VAT amount for the year, either payable or refunded.\
**Example:** `4000`
How often VAT returns are filed. Required for an input-VAT surplus (Vorsteuerüberschuss,
`estimated_balance_type = refundable`) greater than €9,000, where only `monthly` is valid; `quarterly` is the tax office's default.\
**Possible values:** `monthly` or `quarterly`
Whether to request an EU VAT identification number (USt-IdNr), used for cross-border B2B trade.\
**Possible values:** `true` or `false`
Whether you sell through online marketplaces such as Amazon or Etsy (§ 25e UStG record-keeping).\
**Possible values:** `true` or `false`
Whether to apply for the reverse-charge certificate for construction and building-cleaning services
(USt 1 TG, § 13b UStG). When `true`, `reverse_charge_service_type` is required.\
**Possible values:** `true` or `false`
The type of service the reverse-charge certificate covers. Required when `request_reverse_charge_certificate` is `true`.\
**Possible values:** `construction`, `building-cleaning` or `both`
### Employees & Payroll [#employees--payroll]
Whether there are employees. Enables the payroll block. When `true`, the fields below are all required.\
**Possible values:** `true` or `false`
Number of employees. Required when `has_employees = true`.\
**Example:** `3`
Start of wage payments. Must not be before `operational_activity_start_date`. Required when
`has_employees = true`. Format: `YYYY-MM-DD`.\
**Example:** `2025-06-01`
Estimated annual wage tax (Lohnsteuer). Required when `has_employees = true`.\
**Example:** `6000`
### Shared Objects [#shared-objects]
Street including the house number, which must be present, e.g. `Hauptstraße 12` or `Hauptstraße 12a`. Max 72 characters.\
**Example:** `Torstraße 1`
Additional address line (floor, c/o, …), kept as supplementary information.\
**Example:** `2. Etage`
Postal code. A German address must be a 5-digit code.\
**Example:** `60311`
City. Max 72 characters, no digits.\
**Example:** `Frankfurt am Main`
Federal state (Bundesland).\
**Example:** `Hessen`
ISO 3166-1 alpha-2 country code. `de` is domestic; any other value marks the address as abroad.\
**Example:** `de`
## Response [#response]
Outcome of the request.\
**Possible values:** `success` or `error`
Human-readable outcome message.\
**Example:** `Tax registration XML generated and stored. Awaiting manual ELSTER submission.`
UUID of the tax registration case (equal to the `id` you supplied, if any). Use it with the GET endpoint.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
The case status once the XML passed schema and XSD checks.\
**Possible values:** `validated`
ISO 8601 timestamp of the response.\
**Example:** `2025-02-01T07:19:30.443Z`
## Example [#example]
```json theme={null}
{
"legal_form": "einzelunternehmen",
"package": "self",
"signature_path": "M 10 10 L 90 90 M 90 10 L 10 90",
"purpose": "Freiberufliche IT-Beratung",
"operational_activity_start_date": "2025-04-01",
"owner": {
"first_name": "Max",
"last_name": "Mustermann",
"dob": "1985-07-10",
"profession": "IT-Berater",
"tax_identification_number": "09481663279",
"religion": "11",
"address": {
"street": "Schweizer Strasse 8",
"street_second_line": "2. Etage",
"zip": "60594",
"city": "Frankfurt am Main",
"country": "de"
}
},
"address_same_as_home": true,
"financial_estimates": {
"formation_year": { "revenue_amount": 20000, "profit_amount": 18000 },
"following_year": { "revenue_amount": 35000, "profit_amount": 30000 }
},
"environment": "sandbox"
}
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Tax registration XML generated and stored. Awaiting manual ELSTER submission.",
"tax_registration_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "validated",
"timestamp": "2025-02-01T07:19:30.443Z"
}
}
```
# Overview (/tax-registration/post)
`POST https://api.beglaubigt.de/v1/tax-registration`
This endpoint creates a tax registration for one of the supported German legal forms. The `legal_form` field selects the
shape of the request, and each legal form maps to a distinct ELSTER form with its own fields and rules.
Pick the page for your legal form, each one is a complete reference:
* **[UG / GmbH](/tax-registration/post/kapg)**: the corporation form (Kapitalgesellschaft).
* **[GbR / eGbR](/tax-registration/post/persg)**: the partnership form (Personengesellschaft).
* **[Freiberufler / Einzelunternehmen](/tax-registration/post/eun)**: the sole-proprietor form.
## How It Works [#how-it-works]
1. You submit the company's details for a given `legal_form`.
2. The API validates the payload and generates the matching ELSTER XML form.
3. The registration is analyzed automatically. If nothing is flagged it is submitted to ELSTER; if
anything is flagged, a manager reviews and files it.
## Authorization [#authorization]
To authenticate requests, include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
# UG / GmbH (/tax-registration/post/kapg)
`POST https://api.beglaubigt.de/v1/tax-registration`
## Authorization [#authorization]
Include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
## Request [#request]
### Core [#core]
Assign the tax registration to a specific existing company. The company must not already have a tax
registration; if it does, the request returns `409 COMPANY_ALREADY_REGISTERED`. The `environment` must
match the company: a `sandbox` registration cannot be assigned to a production company (or the reverse),
which returns `409 ENVIRONMENT_MISMATCH`. An unknown `company_id` returns `404 COMPANY_NOT_FOUND`. **Omit it** to have a new company created and linked automatically.\
**Example:** `9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e`
Business address for the client company. Only applies when a
new company is created (omit `company_id`); it is rejected if sent together with `company_id`.
Street and house number.\
**Example:** `Torstraße 1`
Postal code.\
**Example:** `10119`
City.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code.\
**Example:** `de`
A second address line (c/o, suite, …).\
**Example:** `c/o Muster`
State or region.\
**Example:** `Berlin`
The legal form of the company.\
**Possible values:** `ug` or `gmbh`
The service package.\
**Possible values:** `self` or `guided`
The client's signature as an SVG path string.\
**Example:** `M 10 10 L 90 90 M 90 10 L 10 90`
The ELSTER environment to file against. It also sets the created company's type: `sandbox` creates a
staging company and files against test ELSTER; `production` creates a live company.\
**Possible values:** `sandbox` or `production`
A custom reference string for your own tracking.\
**Example:** `REF-2025-001`
### Company & Founding [#company--founding]
Registered company name including the legal-form suffix. Max 120 characters.\
**Example:** `Muster Handels GmbH`
Description of the business activity. Max 200 characters.\
**Example:** `Softwareentwicklung und IT-Beratung.`
Date of the notarial formation deed (Gründungsurkunde).\
**Example:** `2025-01-15`
The date the business begins operating. Must not be before `notarization_date`. Format: `YYYY-MM-DD`.\
**Example:** `2025-02-01`
Whether the fiscal year differs from the calendar year.\
**Possible values:** `true` or `false`
Start of the deviating fiscal year. Required when `fiscal_year_deviates_from_calendar = true`.
Format: `YYYY-MM-DD`.\
**Example:** `2025-04-01`
Share capital in euros, a whole number. A UG must be between `1` and `24999`; a GmbH
must be at least `25000`.\
**Example:** `25000`
Amount of the share capital already paid in. Cannot exceed `capital`.\
**Example:** `25000`
How the company was founded: `cash` for a cash contribution (Bargründung), `in-kind` for a
contribution in kind (Sachgründung), or `conversion` when it results from converting an existing
business (Umwandlung).\
**Possible values:** `cash`, `in-kind` or `conversion`
The kind of conversion. Required when `formation_type = conversion`, and only allowed then: `merger`
for a merger (Verschmelzung), `division` for a split (Spaltung), `form-change` for a change of legal
form (Formwechsel), or `asset-transfer` for a transfer of assets (Vermögensübertragung).\
**Possible values:** `merger`, `division`, `form-change` or `asset-transfer`
Whether the company only manages its own assets.\
**Possible values:** `true` or `false`
Registered business address (see the [Address object](#address-object)).
### Directors & Shareholders [#directors--shareholders]
Managing directors. 1–9 entries.
First name. Max 72 characters.\
**Example:** `Max`
Middle name. Appended to the first name in the ELSTER filing. Max 72 characters.\
**Example:** `Karl`
Last name. Max 72 characters.\
**Example:** `Mustermann`
Contact email, kept for follow-up, not part of the ELSTER filing.\
**Example:** `max.mustermann@example.com`
Contact phone, kept for follow-up, not part of the ELSTER filing.\
**Example:** `+491701234567`
Date of birth. Format: `YYYY-MM-DD`.\
**Example:** `1985-07-10`
German tax ID (Steuer-Identifikationsnummer): 11 digits, validated with the ISO 7064 (Mod 11,10) checksum.\
**Example:** `09481663279`
The director's address (see the [Address object](#address-object)).
Shareholders, split into two arrays: `individuals` (natural persons) and `entities` (legal entities).
At least 1 and at most 99 across both, and the `share_percentage` values must sum to exactly 100.
Natural-person shareholders.
First name. Max 72 characters.\
**Example:** `Max`
Last name. Max 72 characters.\
**Example:** `Mustermann`
Date of birth. Format: `YYYY-MM-DD`.\
**Example:** `1985-07-10`
German tax ID (Steuer-Identifikationsnummer): 11 digits, validated with the ISO 7064 (Mod 11,10) checksum.\
**Example:** `09481663279`
Address (see the [Address object](#address-object)).
Ownership share in percent, up to 100 (2 to 4 decimal places allowed).\
**Example:** `100`
Legal-entity shareholders.
Company name. Max 120 characters.\
**Example:** `Beispiel Holding GmbH`
Address (see the [Address object](#address-object)).
Ownership share in percent, up to 100 (2 to 4 decimal places allowed).\
**Example:** `0`
The founding notary (Gründungsnotar). Optional; when present, all sub-fields are required.
First name. Max 72 characters.\
**Example:** `Julia`
Last name. Max 72 characters.\
**Example:** `Notarin`
The notary's office address (see the [Address object](#address-object)).
### Commercial Register [#commercial-register]
The company's Handelsregister state, grouped under `commercial_register`. `status` says where the
company stands, and drives which of the other fields are required.
The register state. Omit it entirely for a company that has not applied yet (same as `status: not-applied`).
Where the company stands in the register.
* **`not-applied`**: no register application yet. Carries no other fields.
* **`application-filed`**: the application is filed but the entry is still pending. Requires `registration_application_date`.
* **`registered`**: the company is entered. Requires `registration_number`, `registration_date` and `registration_court`.
**Possible values:** `not-applied`, `application-filed` or `registered`
The Handelsregister number, once the company has been entered. Send the number only; a leading `HRB`
is optional and dropped (a GmbH/UG is always Abteilung B). A suffix is kept with its space removed
(`12345 B` becomes `12345B`). Required when `status` is `registered`.\
**Example:** `12345`
Date the company was entered in the register. Required when `status` is `registered`. Format: `YYYY-MM-DD`.\
**Example:** `2025-01-20`
Date the registration application was filed. Required when `status` is `application-filed`. Format: `YYYY-MM-DD`.\
**Example:** `2025-01-10`
Registering court. Required when `status` is `registered`.\
**Example:** `Charlottenburg`
### Bank Account [#bank-account]
The company's bank account IBAN.\
**Example:** `DE89370400440532013000`
The bank identifier (BIC/SWIFT), 8 to 11 characters. Required when `iban` is a non-German IBAN.\
**Example:** `COBADEFFXXX`
### Revenue & Profit Estimates [#revenue--profit-estimates]
Estimated revenue and taxable profit for the formation year and the following year. All amounts are
whole euros.
Estimates for the formation year (the year the business starts operating).
Estimated revenue. Cannot be lower than `profit_amount`.\
**Example:** `60000`
Estimated taxable profit.\
**Example:** `20000`
Estimates for the year after the formation year.
Estimated revenue. Cannot be lower than `profit_amount`.\
**Example:** `90000`
Estimated taxable profit.\
**Example:** `40000`
### VAT [#vat]
It uses the VAT exemption under § 19 UStG: it does not charge VAT on its invoices and files no VAT returns.
* **Founding year:** qualifies when founding-year revenue is ≤ €25,000.
* **Later years:** stays a Kleinunternehmer while the previous year was ≤ €25,000 and the current year does not exceed €100,000.
To use it, set `vat.regime` to `small-business`. The VAT-calculation fields (`vat.accounting_method`,
`vat.estimated_balance_type`, `vat.estimated_balance_amount` and `vat.return_frequency`) then do not
apply and are rejected if sent.
Setting `vat.regime` to `standard` opts the client out of the small-business regime, so they charge
VAT on invoices and file VAT returns.
The company's VAT setup.
The VAT regime the company elects. `small-business` elects the small-business exemption (Kleinunternehmer,
§ 19 UStG); `standard` is the regular VAT regime (Regelbesteuerung). Required when the election is available
(founding-year revenue ≤ €25,000 and following-year ≤ €100,000). Above €25,000 the company is on the regular
VAT regime regardless, so the field has no effect there.\
**Possible values:** `small-business` or `standard`
When you owe the VAT you've charged:
* **`accrual`** (Sollversteuerung): the VAT is due as soon as you issue the invoice, even if the customer hasn't paid yet.
* **`cash`** (Istversteuerung): the VAT is due only once the customer actually pays.
A KapG can choose `cash` only when founding-year revenue is ≤ €800,000; above that, `accrual` is required.
Required unless the company is a small business (Kleinunternehmer), where it does not apply.\
**Possible values:** `accrual` or `cash`
Whether you expect to owe VAT to the tax office (`payable`, Zahllast) or receive a refund (`refundable`, Überschuss).
Required unless the company is a small business (Kleinunternehmer): that is, when `vat.regime` is `standard`, or founding-year revenue is more than €25,000.\
**Possible values:** `payable` or `refundable`
Estimated net VAT amount for the year, either payable or refunded. Required unless the company is a small business (Kleinunternehmer)
(see `estimated_balance_type`).\
**Example:** `4000`
How often VAT returns are filed. `quarterly` is the default. You can choose `monthly` (for faster
input-VAT refunds) only when you expect a refund (`estimated_balance_type = refundable`) of more than €9,000,
and the field is required in that case.\
**Possible values:** `monthly` or `quarterly`
Whether to request an EU VAT identification number (USt-IdNr), used for cross-border B2B trade.\
**Possible values:** `true` or `false`
Whether the company sells through online marketplaces such as Amazon or Etsy (§ 25e UStG record-keeping).\
**Possible values:** `true` or `false`
Whether to apply for the reverse-charge certificate for construction and building-cleaning services
(USt 1 TG, § 13b UStG). When `true`, `reverse_charge_service_type` is required.\
**Possible values:** `true` or `false`
The type of service the reverse-charge certificate covers. Required when `request_reverse_charge_certificate` is `true`.\
**Possible values:** `construction`, `building-cleaning` or `both`
### Employees & Payroll [#employees--payroll]
Whether there are employees. Enables the payroll block. When `true`, the nested fields are all required.\
**Possible values:** `true` or `false`
Number of employees.\
**Example:** `4`
Number of employees who are also shareholders.\
**Example:** `1`
Start of wage payments. Must not be before `operational_activity_start_date`. Format: `YYYY-MM-DD`.\
**Example:** `2025-05-01`
Estimated annual wage tax.\
**Example:** `20000`
### Shared Objects [#shared-objects]
Street including the house number, which must be present, e.g. `Hauptstraße 12` or `Hauptstraße 12a`. Max 72 characters.\
**Example:** `Torstraße 1`
Additional address line (floor, c/o, …), kept as supplementary information.\
**Example:** `2. Etage`
Postal code. A German address must be a 5-digit code.\
**Example:** `60311`
City. Max 72 characters, no digits.\
**Example:** `Frankfurt am Main`
Federal state (Bundesland).\
**Example:** `Hessen`
ISO 3166-1 alpha-2 country code. `de` is domestic; any other value marks the address as abroad.\
**Example:** `de`
## Response [#response]
Outcome of the request.\
**Possible values:** `success` or `error`
Human-readable outcome message.\
**Example:** `Tax registration XML generated and stored. Awaiting manual ELSTER submission.`
UUID of the tax registration case (equal to the `id` you supplied, if any). Use it with the GET endpoint.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
The case status once the XML passed schema and XSD checks.\
**Possible values:** `validated`
ISO 8601 timestamp of the response.\
**Example:** `2025-02-01T07:19:30.443Z`
## Example [#example]
```json theme={null}
{
"legal_form": "gmbh",
"name": "Muster Handels GmbH",
"purpose": "Handel mit Elektronikwaren",
"package": "self",
"signature_path": "M 10 10 L 90 90 M 90 10 L 10 90",
"notarization_date": "2025-01-15",
"operational_activity_start_date": "2025-02-01",
"fiscal_year_deviates_from_calendar": false,
"capital": 25000,
"paid_in_capital": 25000,
"formation_type": "cash",
"address": {
"street": "Hauptstrasse 12",
"street_second_line": "2. Etage",
"zip": "60311",
"city": "Frankfurt am Main",
"country": "de"
},
"directors": [
{
"first_name": "Max",
"middle_name": "Karl",
"last_name": "Mustermann",
"email": "max.mustermann@example.com",
"phone": "+491701234567",
"dob": "1985-07-10",
"tax_identification_number": "09481663279",
"address": {
"street": "Hauptstrasse 12",
"zip": "60311",
"city": "Frankfurt am Main",
"country": "de"
}
}
],
"shareholders": {
"individuals": [
{
"first_name": "Max",
"last_name": "Mustermann",
"dob": "1985-07-10",
"tax_identification_number": "09481663279",
"address": {
"street": "Hauptstrasse 12",
"zip": "60311",
"city": "Frankfurt am Main",
"country": "de"
},
"share_percentage": 100
}
],
"entities": []
},
"financial_estimates": {
"formation_year": {
"revenue_amount": 60000,
"profit_amount": 20000
},
"following_year": {
"revenue_amount": 90000,
"profit_amount": 40000
}
},
"vat": {
"estimated_balance_type": "payable",
"estimated_balance_amount": 8000
},
"commercial_register": {
"status": "registered",
"registration_number": "12345",
"registration_date": "2025-01-20",
"registration_court": "Charlottenburg"
},
"environment": "sandbox",
"client_reference": "REF-2025-001"
}
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Tax registration XML generated and stored. Awaiting manual ELSTER submission.",
"tax_registration_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "validated",
"timestamp": "2025-02-01T07:19:30.443Z"
}
}
```
# GbR / eGbR (/tax-registration/post/persg)
`POST https://api.beglaubigt.de/v1/tax-registration`
The request for a **GbR** or **eGbR** (Personengesellschaft). `legal_form` is `gbr` or `egbr`, which maps
to the ELSTER **FsE\_PersG** form. An eGbR is a GbR entered in the company register
(Gesellschaftsregister); express it via the register fields below.
## Authorization [#authorization]
Include an Authorization header with a Bearer token:
`Authorization: Bearer `
**Example:** `Bearer sk-123e4567-e89b-12d3-a456-426614174000`
## Request [#request]
### Core [#core]
Assign the tax registration to a specific existing company. The company must not already have a tax
registration; if it does, the request returns `409 COMPANY_ALREADY_REGISTERED`. The `environment` must
match the company: a `sandbox` registration cannot be assigned to a production company (or the reverse),
which returns `409 ENVIRONMENT_MISMATCH`. An unknown `company_id` returns `404 COMPANY_NOT_FOUND`. **Omit it** to have a new company created and linked automatically.\
**Example:** `9b2e4c7a-1d3f-4a8b-9c6e-2f5a7b8c1d0e`
Business address for the client company. Only applies when a
new company is created (omit `company_id`); it is rejected if sent together with `company_id`.
Street and house number.\
**Example:** `Torstraße 1`
Postal code.\
**Example:** `10119`
City.\
**Example:** `Berlin`
Country as an ISO 3166-1 alpha-2 code.\
**Example:** `de`
A second address line (c/o, suite, …).\
**Example:** `c/o Muster`
State or region.\
**Example:** `Berlin`
The legal form of the company.\
**Possible values:** `gbr` or `egbr`
The service package the client selected.\
**Possible values:** `self` or `guided`
The client's signature as an SVG path string (the drawn signature).\
**Example:** `M 10 10 L 90 90 M 90 10 L 10 90`
The ELSTER environment to file against. It also sets the created company's type: `sandbox` creates a
staging company and files against test ELSTER; `production` creates a live company.\
**Possible values:** `sandbox` or `production`
A custom reference string for your own tracking.\
**Example:** `REF-2025-001`
### Company & Founding [#company--founding]
Partnership name (Firmenname). Max 120 characters.\
**Example:** `Muster & Partner GbR`
Description of the business activity. Max 200 characters.\
**Example:** `Grafikdesign und Beratung`
The date the business begins operating. Must not be before `founding_date`. Format: `YYYY-MM-DD`.\
**Example:** `2025-03-01`
Date the partnership was formed. Format: `YYYY-MM-DD`.\
**Example:** `2025-03-01`
How the partnership came about: `1` new formation (Neugründung), `2` relocation (Verlegung), `3` takeover (Übernahme), `4` conversion (Umwandlung).\
**Possible values:** `1`, `2`, `3` or `4`
Method used to determine taxable profit: `01` cash accounting (EÜR), `02` double-entry (Bilanz), `03` standard rates (Durchschnittssätze), `04` other (Sonstige).\
**Possible values:** `01`, `02`, `03` or `04`
Registered business address (see the [Address object](#address-object)).
### Partners [#partners]
Representatives (Vertreter). 1–99 entries.
First name. Max 72 characters.\
**Example:** `Max`
Middle name. Appended to the first name in the ELSTER filing. Max 72 characters.\
**Example:** `Karl`
Last name. Max 72 characters.\
**Example:** `Mustermann`
Contact email, kept for follow-up, not part of the ELSTER filing.\
**Example:** `max.mustermann@example.com`
Contact phone, kept for follow-up, not part of the ELSTER filing.\
**Example:** `+491701234567`
Date of birth. Format: `YYYY-MM-DD`.\
**Example:** `1985-07-10`
German tax ID (Steuer-Identifikationsnummer): 11 digits, validated with the ISO 7064 (Mod 11,10) checksum.\
**Example:** `09481663279`
The representative's address (see the [Address object](#address-object)).
Partners (Beteiligte), split into two arrays: `individuals` (natural persons) and `entities` (legal
entities). **At least 2** and at most 99 across both, and the `share_percentage` values must sum to 100.
Natural-person partners.
First name. Max 72 characters.\
**Example:** `Max`
Last name. Max 72 characters.\
**Example:** `Mustermann`
Date of birth. Format: `YYYY-MM-DD`.\
**Example:** `1985-07-10`
German tax ID (Steuer-Identifikationsnummer): 11 digits, validated with the ISO 7064 (Mod 11,10) checksum.\
**Example:** `09481663279`
Address (see the [Address object](#address-object)).
Ownership share in percent, up to 100 (2 to 4 decimal places allowed).\
**Example:** `50`
Legal-entity partners.
Company name. Max 120 characters.\
**Example:** `Beispiel Holding GmbH`
Address (see the [Address object](#address-object)).
Ownership share in percent, up to 100 (2 to 4 decimal places allowed).\
**Example:** `50`
### Company Register [#company-register]
For an eGbR that is entered, intends to register, or has applied, supply the register state.
Whether entry in the company register is intended (this is what turns a GbR into an eGbR).\
**Possible values:** `true` or `false`
The register number, present once the eGbR has been entered.\
**Example:** `12345`
Date of entry in the register. Format: `YYYY-MM-DD`.\
**Example:** `2025-03-20`
Whether the registration application has been filed while the entry is still pending.\
**Possible values:** `true` or `false`
Date the registration application was filed. Format: `YYYY-MM-DD`.\
**Example:** `2025-03-10`
Registering court.\
**Example:** `Frankfurt am Main`
### Bank Account [#bank-account]
The company's bank account IBAN. For a non-German IBAN you must also supply `bic`.\
**Example:** `DE89370400440532013000`
The bank identifier (BIC/SWIFT) for the account, 8 to 11 characters. Required for non-German IBANs.\
**Example:** `COBADEFFXXX`
### Revenue & Profit Estimates [#revenue--profit-estimates]
Estimated revenue and taxable profit for the formation year and the following year. All amounts are
whole euros.
Estimates for the formation year (the year the business starts operating).
Estimated revenue. Cannot be lower than `profit_amount`.\
**Example:** `40000`
Estimated taxable profit.\
**Example:** `30000`
Estimates for the year after the formation year.
Estimated revenue. Cannot be lower than `profit_amount`.\
**Example:** `60000`
Estimated taxable profit.\
**Example:** `50000`
### VAT [#vat]
The company's VAT setup.
The VAT regime the company elects. `small-business` elects the small-business exemption (Kleinunternehmer,
§ 19 UStG); `standard` is the regular VAT regime (Regelbesteuerung). Required when the election is available
(founding-year revenue ≤ €25,000 and following-year ≤ €100,000). Above €25,000 the company is on the regular
VAT regime regardless, so the field has no effect there.\
**Possible values:** `small-business` or `standard`
When you owe the VAT you've charged: with `accrual` (Sollversteuerung) the VAT is due as soon as you issue the
invoice, even if the customer hasn't paid yet; with `cash` (Istversteuerung) it's due only once the customer
actually pays. Omit for small businesses (Kleinunternehmer).\
**Possible values:** `accrual` or `cash`
The legal ground for choosing cash-basis VAT, only when `vat.accounting_method = cash`: `revenue` (turnover below the
§20 UStG limit), `section-148-ao` (exempt from bookkeeping under §148 AO) or `liberal-profession` (§18 EStG).\
**Possible values:** `revenue`, `section-148-ao` or `liberal-profession`
Whether you expect to owe VAT to the tax office (`payable`, Zahllast) or receive a refund (`refundable`, Überschuss).\
**Possible values:** `payable` or `refundable`
Estimated net VAT amount for the year, either payable or refunded.\
**Example:** `4000`
How often VAT returns are filed. Required for an input-VAT surplus (Vorsteuerüberschuss,
`estimated_balance_type = refundable`) greater than €9,000, where only `monthly` is valid; `quarterly` is the tax office's default.\
**Possible values:** `monthly` or `quarterly`
Whether to request an EU VAT identification number (USt-IdNr), used for cross-border B2B trade.\
**Possible values:** `true` or `false`
Whether the company sells through online marketplaces such as Amazon or Etsy (§ 25e UStG record-keeping).\
**Possible values:** `true` or `false`
Whether to apply for the reverse-charge certificate for construction and building-cleaning services
(USt 1 TG, § 13b UStG). When `true`, `reverse_charge_service_type` is required.\
**Possible values:** `true` or `false`
The type of service the reverse-charge certificate covers. Required when `request_reverse_charge_certificate` is `true`.\
**Possible values:** `construction`, `building-cleaning` or `both`
### Employees & Payroll [#employees--payroll]
Whether there are employees. Enables the payroll block. When `true`, the fields below are all required.\
**Possible values:** `true` or `false`
Number of employees. Required when `has_employees = true`.\
**Example:** `4`
Number of employees who are also partners. Required when `has_employees = true`.\
**Example:** `1`
Start of wage payments. Must not be before `operational_activity_start_date`. Required when
`has_employees = true`. Format: `YYYY-MM-DD`.\
**Example:** `2025-05-01`
Estimated annual wage tax (Lohnsteuer). Required when `has_employees = true`.\
**Example:** `20000`
### Shared Objects [#shared-objects]
Street including the house number, which must be present, e.g. `Hauptstraße 12` or `Hauptstraße 12a`. Max 72 characters.\
**Example:** `Torstraße 1`
Additional address line (floor, c/o, …), kept as supplementary information.\
**Example:** `2. Etage`
Postal code. A German address must be a 5-digit code.\
**Example:** `60311`
City. Max 72 characters, no digits.\
**Example:** `Frankfurt am Main`
Federal state (Bundesland).\
**Example:** `Hessen`
ISO 3166-1 alpha-2 country code. `de` is domestic; any other value marks the address as abroad.\
**Example:** `de`
## Response [#response]
Outcome of the request.\
**Possible values:** `success` or `error`
Human-readable outcome message.\
**Example:** `Tax registration XML generated and stored. Awaiting manual ELSTER submission.`
UUID of the tax registration case (equal to the `id` you supplied, if any). Use it with the GET endpoint.\
**Example:** `450506c1-d1a7-46e2-aca6-41a816805595`
The case status once the XML passed schema and XSD checks.\
**Possible values:** `validated`
ISO 8601 timestamp of the response.\
**Example:** `2025-02-01T07:19:30.443Z`
## Example [#example]
```json theme={null}
{
"legal_form": "gbr",
"package": "self",
"signature_path": "M 10 10 L 90 90 M 90 10 L 10 90",
"name": "Muster & Partner GbR",
"purpose": "Grafikdesign und Beratung",
"operational_activity_start_date": "2025-03-01",
"founding_date": "2025-03-01",
"founding_kind": "1",
"accounting_profit_method": "01",
"address": {
"street": "Berger Strasse 45",
"street_second_line": "2. Etage",
"zip": "60316",
"city": "Frankfurt am Main",
"country": "de"
},
"directors": [
{
"first_name": "Max",
"middle_name": "Karl",
"last_name": "Mustermann",
"dob": "1985-07-10",
"address": {
"street": "Berger Strasse 45",
"zip": "60316",
"city": "Frankfurt am Main",
"country": "de"
}
}
],
"shareholders": {
"individuals": [
{
"first_name": "Max",
"last_name": "Mustermann",
"dob": "1985-07-10",
"address": {
"street": "Berger Strasse 45",
"zip": "60316",
"city": "Frankfurt am Main",
"country": "de"
},
"share_percentage": 50
},
{
"first_name": "Erika",
"last_name": "Musterfrau",
"dob": "1990-03-22",
"address": {
"street": "Berger Strasse 45",
"zip": "60316",
"city": "Frankfurt am Main",
"country": "de"
},
"share_percentage": 50
}
],
"entities": []
},
"financial_estimates": {
"formation_year": { "revenue_amount": 40000, "profit_amount": 30000 },
"following_year": { "revenue_amount": 60000, "profit_amount": 50000 }
},
"environment": "sandbox"
}
```
```json theme={null}
{
"response": {
"result": "success",
"message": "Tax registration XML generated and stored. Awaiting manual ELSTER submission.",
"tax_registration_id": "450506c1-d1a7-46e2-aca6-41a816805595",
"status": "validated",
"timestamp": "2025-02-01T07:19:30.443Z"
}
}
```