OpenAPI Spec for the OpenRegister API
openapi: 3.1.0
info:
title: OpenRegister API
version: 0.1.0
description: |
API for accessing comprehensive company data from official registers.
This API provides access to company information, shareholder data, financial reports, and contact details.
servers:
- url: https://api.openregister.de
description: Production
security:
- BearerAuth: []
paths:
/v0/search/company:
get:
summary: Search for companies
operationId: companySearch
parameters:
- name: query
in: query
required: false
description: |
Text search query to find companies by name.
Example: "Descartes Technologies UG"
schema:
type: string
- name: register_number
in: query
required: false
description: |
Company register number for exact matching.
Example: "230633"
schema:
type: string
- name: register_type
in: query
required: false
description: |
Type of register to filter results.
Example: "HRB" (Commercial Register B)
schema:
$ref: "#/components/schemas/CompanyRegisterType"
- name: register_court
in: query
required: false
description: |
Court where the company is registered.
Example: "Berlin (Charlottenburg)"
schema:
type: string
- name: active
in: query
required: false
description: |
Filter for active or inactive companies.
Set to true for active companies only, false for inactive only.
schema:
type: boolean
default: true
- name: legal_form
in: query
required: false
description: |
Legal form of the company.
Example: "gmbh" for "Gesellschaft mit beschränkter Haftung"
schema:
$ref: "#/components/schemas/CompanyLegalForm"
- name: incorporation_date
in: query
required: false
description: |
Date of incorporation of the company.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
schema:
type: string
description: date format YYYY-MM-DD
- name: page
in: query
required: false
description: Page number for pagination.
schema:
type: integer
default: 1
- name: per_page
in: query
required: false
description: Number of results per page (max 50).
schema:
type: integer
default: 10
responses:
"200":
description: Successful search operation
content:
application/json:
schema:
$ref: "#/components/schemas/CompanySearchResponse"
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"402":
description: Payment Required - Insufficient credits for this request
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const response = await client.search.findCompanies();
console.log(response.pagination);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
response = client.search.find_companies()
print(response.pagination)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
response, err := client.Search.FindCompanies(context.TODO(), openregister.SearchFindCompaniesParams{
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Pagination)
}
/v0/search/lookup:
get:
summary: Find company by website URL
operationId: lookupCompanyWebsite
parameters:
- name: url
in: query
required: true
schema:
type: string
format: uri
description: |
Website URL to search for.
Example: "https://openregister.de"
responses:
"200":
description: Successfully retrieved company data
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyLookupResponse"
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"404":
description: Not found - Company not found
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const response = await client.search.lookupCompanyByURL({ url: 'https://example.com' });
console.log(response.company_id);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
response = client.search.lookup_company_by_url(
url="https://example.com",
)
print(response.company_id)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
response, err := client.Search.LookupCompanyByURL(context.TODO(), openregister.SearchLookupCompanyByURLParams{
URL: "https://example.com",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.CompanyID)
}
/v0/company/{company_id}:
get:
summary: Get detailed company information
operationId: getCompany
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
- name: history
in: query
required: false
description: |
Include historical company data when set to true.
This returns past names, addresses, and other changed information.
schema:
type: boolean
default: true
- name: financials
in: query
required: false
description: |
Include financial data when set to true.
Provides access to financial reports and key financial indicators.
schema:
type: boolean
default: true
- name: documents
in: query
required: false
description: |
Include document metadata when set to true.
Lists available official documents related to the company.
schema:
type: boolean
default: true
responses:
"200":
description: Successfully retrieved company data
content:
application/json:
schema:
$ref: "#/components/schemas/Company"
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"402":
description: Payment Required - Insufficient credits for this request
"404":
description: Not Found - Company ID doesn't exist
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const company = await client.company.retrieve('company_id');
console.log(company.id);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
company = client.company.retrieve(
company_id="company_id",
)
print(company.id)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
company, err := client.Company.Get(
context.TODO(),
"company_id",
openregister.CompanyGetParams{
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", company.ID)
}
/v0/company/{company_id}/shareholders:
get:
summary: Get company shareholders
operationId: getShareholders
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
responses:
"200":
description: Successfully retrieved shareholders
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyShareholders"
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"402":
description: Payment Required - Insufficient credits for this request
"404":
description: Not Found - Company ID doesn't exist
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const response = await client.company.listShareholders('company_id');
console.log(response.document_id);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
response = client.company.list_shareholders(
"company_id",
)
print(response.document_id)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
response, err := client.Company.ListShareholders(context.TODO(), "company_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.DocumentID)
}
/v0/company/{company_id}/contact:
get:
summary: Get company contact information
operationId: getContact
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
responses:
"200":
description: Successfully retrieved contact information
content:
application/json:
schema:
$ref: "#/components/schemas/Contact"
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"402":
description: Payment Required - Insufficient credits for this request
"404":
description: Not Found - No contact information available
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const response = await client.company.retrieveContact('company_id');
console.log(response.vat_id);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
response = client.company.retrieve_contact(
"company_id",
)
print(response.vat_id)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
response, err := client.Company.GetContact(context.TODO(), "company_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.VatID)
}
/v0/document/{document_id}:
get:
summary: Get document information
operationId: getDocument
parameters:
- name: document_id
in: path
required: true
description: |
Unique document identifier.
Example: a6daa905-a87e-451c-9df6-35051eec8b61
schema:
type: string
responses:
"200":
description: Successfully retrieved document information
content:
application/json:
schema:
$ref: "#/components/schemas/Document"
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"402":
description: Payment Required - Insufficient credits for this request
"404":
description: Not Found - Document not found
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const document = await client.document.retrieve('document_id');
console.log(document.id);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
document = client.document.retrieve(
"document_id",
)
print(document.id)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
document, err := client.Document.Get(context.TODO(), "document_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", document.ID)
}
/v0/document/{document_id}/download:
get:
summary: Download document
operationId: downloadDocument
parameters:
- name: document_id
in: path
required: true
description: |
Unique document identifier.
Example: a6daa905-a87e-451c-9df6-35051eec8b61
schema:
type: string
responses:
"200":
description: >-
Successfully downloaded document. The content-disposition header will be set to the original
filename.
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
description: Bad Request - Invalid parameters provided
"401":
description: Unauthorized - Authentication required
"402":
description: Payment Required - Insufficient credits for this request
"404":
description: Not Found - Document not found
"429":
description: Too Many Requests - Rate limit exceeded
"500":
description: Internal Server Error - An error occurred while processing the request
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const response = await client.document.download('document_id');
console.log(response);
const content = await response.blob();
console.log(content);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
response = client.document.download(
"document_id",
)
print(response)
content = response.read()
print(content)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
response, err := client.Document.Download(context.TODO(), "document_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response)
}
/v0/jobs/document/{id}:
get:
summary: Get document job status
operationId: getDocumentJobStatus
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentJobStatus"
"401":
description: Unauthorized
"404":
description: Not Found
"500":
description: Internal Server Error
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const document = await client.jobs.document.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(document.status);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
document = client.jobs.document.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(document.status)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
document, err := client.Jobs.Document.Get(context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", document.Status)
}
/v0/jobs/document:
post:
summary: Create a document job
operationId: createDocumentJob
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentJob"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentJobResponse"
"400":
description: Bad Request
"401":
description: Unauthorized
"404":
description: Not Found
"500":
description: Internal Server Error
x-codeSamples:
- lang: JavaScript
source: |-
import Openregister from 'openregister';
const client = new Openregister({
apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
});
const document = await client.jobs.document.create({
company_id: 'company_id',
document_category: 'current_printout',
});
console.log(document.id);
- lang: Python
source: |-
import os
from openregister import Openregister
client = Openregister(
api_key=os.environ.get("OPENREGISTER_API_KEY"), # This is the default and can be omitted
)
document = client.jobs.document.create(
company_id="company_id",
document_category="current_printout",
)
print(document.id)
- lang: Go
source: |
package main
import (
"context"
"fmt"
"github.com/oregister/openregister-go"
"github.com/oregister/openregister-go/option"
)
func main() {
client := openregister.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("OPENREGISTER_API_KEY")
)
document, err := client.Jobs.Document.New(context.TODO(), openregister.JobDocumentNewParams{
CompanyID: "company_id",
DocumentCategory: openregister.JobDocumentNewParamsDocumentCategoryCurrentPrintout,
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", document.ID)
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
API Key Authentication
Provide your API key as a Bearer token in the Authorization header.
schemas:
CompanyRegisterType:
type: string
description: |
Type of company register where the entity is recorded.
Common types:
- HRB: Commercial Register B (limited liability companies, stock corporations)
- HRA: Commercial Register A (partnerships, sole proprietorships)
- PR: Partnership Register
- GnR: Cooperative Register
- VR: Association Register
enum:
- HRB
- HRA
- PR
- GnR
- VR
CompanyLegalForm:
type: string
description: |
Legal form of the company.
Common German legal forms:
- gmbh: Gesellschaft mit beschränkter Haftung (Limited Liability Company)
- ag: Aktiengesellschaft (Stock Corporation)
- ug: Unternehmergesellschaft (Entrepreneurial Company with limited liability)
- ohg: Offene Handelsgesellschaft (General Partnership)
- kg: Kommanditgesellschaft (Limited Partnership)
- ev: Eingetragener Verein (Registered Association)
enum:
- ag
- eg
- ek
- ev
- ewiv
- foreign
- gbr
- ggmbh
- gmbh
- kg
- kgaa
- unknown
- llp
- municipal
- ohg
- se
- ug
CompanyLookupResponse:
type: object
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
email:
type: string
description: |
Email address of the company.
Example: "info@maxmustermann.de"
phone:
type: string
description: |
Phone number of the company.
Example: "+49 123 456 789"
vat_id:
type: string
description: |
Value Added Tax identification number.
Example: "DE123456789"
required:
- company_id
CompanySearchResponse:
type: object
properties:
results:
type: array
description: |
List of companies matching the search criteria.
items:
$ref: "#/components/schemas/CompanySearchResponseItem"
pagination:
$ref: "#/components/schemas/Pagination"
required:
- results
- pagination
CompanySearchResponseItem:
type: object
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
name:
type: string
description: |
Official registered company name.
Example: "Max Mustermann GmbH"
country:
type: string
description: |
Country where the company is registered using ISO 3166-1 alpha-2 code.
Example: "DE" for Germany
register_number:
type: string
description: |
Registration number in the company register.
Example: "230633"
register_type:
$ref: "#/components/schemas/CompanyRegisterType"
description: |
Type of company register.
Example: "HRB" for Commercial Register B
register_court:
type: string
description: |
Court where the company is registered.
Example: "Berlin (Charlottenburg)"
active:
type: boolean
description: |
Company status - true if active, false if inactive.
legal_form:
$ref: "#/components/schemas/CompanyLegalForm"
description: |
Legal form of the company.
Example: "gmbh" for Gesellschaft mit beschränkter Haftung
required:
- company_id
- name
- register_number
- register_type
- register_court
- active
- legal_form
Company:
type: object
properties:
id:
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
type: string
register:
description: |
Current registration information of the company.
$ref: "#/components/schemas/CompanyRegister"
registers:
description: |
Historical registration changes, only included when history=true.
Shows how registration details changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyRegister"
status:
description: |
Current status of the company:
- active: Operating normally
- inactive: No longer operating
- liquidation: In the process of being dissolved
type: string
enum:
- active
- inactive
- liquidation
name:
description: |
Current official name of the company.
$ref: "#/components/schemas/CompanyName"
names:
description: |
Historical company names, only included when history=true.
Shows how the company name changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyName"
address:
description: |
Current registered address of the company.
$ref: "#/components/schemas/CompanyAddress"
addresses:
description: |
Historical addresses, only included when history=true.
Shows how the company address changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyAddress"
purpose:
description: |
Current official business purpose of the company.
$ref: "#/components/schemas/CompanyPurpose"
purposes:
description: |
Historical business purposes, only included when history=true.
Shows how the company purpose changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyPurpose"
capital:
description: |
Current registered capital of the company.
$ref: "#/components/schemas/CompanyCapital"
capitals:
description: |
Historical capital changes, only included when history=true.
Shows how the company capital changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyCapital"
representation:
description: |
List of individuals or entities authorized to represent the company.
Includes directors, officers, and authorized signatories.
type: array
items:
$ref: "#/components/schemas/CompanyRepresentative"
financials:
description: |
Financial reports and key financial indicators,
only included when financials=true.
$ref: "#/components/schemas/CompanyFinancials"
legal_form:
description: |
Legal form of the company.
Example: "gmbh" for Gesellschaft mit beschränkter Haftung
$ref: "#/components/schemas/CompanyLegalForm"
documents:
description: |
Available official documents related to the company,
only included when documents=true.
type: array
items:
$ref: "#/components/schemas/CompanyDocument"
incorporated_at:
description: |
Date when the company was officially registered.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
terminated_at:
description: |
Date when the company was officially terminated (if applicable).
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
required:
- id
- incorporated_at
- register
- status
- name
- address
- legal_form
- representation
CompanyAddress:
type: object
properties:
street:
description: |
Street name and number.
Example: "Musterstraße 1"
type: string
city:
description: |
City or locality name.
Example: "Berlin"
type: string
postal_code:
description: |
Postal or ZIP code.
Example: "10117"
type: string
country:
description: |
Country name.
Example: "Germany"
type: string
extra:
description: |
Additional address information such as c/o or attention line.
Example: "c/o Max Mustermann"
type: string
start_date:
description: |
Date when this address became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
formatted_value:
description: |
Complete address formatted as a single string.
Example: "Musterstraße 1, 10117 Berlin, Germany"
type: string
required:
- city
- country
- start_date
- formatted_value
CompanyCapital:
type: object
properties:
amount:
description: |
Capital amount as a decimal number.
Example: 100000.00 represents 100,000.00 monetary units
type: number
format: double
currency:
description: |
Currency code for the capital amount.
Example: "EUR" for Euro
type: string
enum:
- EUR
- DEM
- USD
start_date:
description: |
Date when this capital amount became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2023-01-01"
type: string
required:
- amount
- currency
- start_date
CompanyPurpose:
type: object
properties:
purpose:
description: |
Official description of the company's business activities and objectives.
This is the registered purpose as stated in official documents.
type: string
start_date:
description: |
Date when this purpose became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
required:
- purpose
- start_date
CompanyName:
type: object
properties:
name:
description: |
Official company name including any legal form designations.
Example: "Descartes Technologies UG (haftungsbeschränkt)"
type: string
legal_form:
description: |
Legal form of the company at this point in time.
Example: "gmbh" for Gesellschaft mit beschränkter Haftung
$ref: "#/components/schemas/CompanyLegalForm"
start_date:
description: |
Date when this name became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
required:
- name
- legal_form
- start_date
CompanyRegister:
type: object
properties:
company_id:
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
type: string
register_number:
description: |
Registration number in the company register.
Example: "230633"
type: string
register_type:
description: |
Type of register where the company is recorded.
Example: "HRB" (Commercial Register B)
$ref: "#/components/schemas/CompanyRegisterType"
register_court:
description: |
Court where the company is registered.
Example: "Berlin (Charlottenburg)"
type: string
start_date:
description: |
Date when this registration information became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
required:
- register_number
- register_type
- register_court
CompanyDocument:
type: object
properties:
id:
description: |
Unique identifier for the document.
Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
type: string
type:
description: |
Categorization of the document:
- articles_of_association: Company statutes/bylaws
- sample_protocol: Standard founding protocol
- shareholder_list: List of company shareholders
type: string
enum:
- articles_of_association
- sample_protocol
- shareholder_list
date:
description: |
Document publication or filing date.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
latest:
description: |
Whether this is the latest version of the document_type.
type: boolean
required:
- id
- type
- date
- latest
CompanyRepresentative:
type: object
properties:
id:
description: |
Unique identifier for the representative.
For companies: Format matches company_id pattern
For individuals: UUID
Example: "DE-HRB-F1103-267645" or UUID
May be null for certain representatives.
type: string
name:
description: The name of the representative. E.g. "Max Mustermann" or "Max Mustermann GmbH"
type: string
type:
description: Whether the representation is a natural person or a legal entity.
$ref: "#/components/schemas/EntityType"
role:
description: The role of the representation. E.g. "DIRECTOR"
$ref: "#/components/schemas/RepresentationRole"
start_date:
description: |
Date when this representative role became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
end_date:
description: |
Date when this representative role ended (if applicable).
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
city:
description: |
City where the representative is located.
Example: "Berlin"
type: string
country:
description: |
Country where the representative is located, in ISO 3166-1 alpha-2 format.
Example: "DE" for Germany
type: string
first_name:
description: |
First name of the representative. Only provided for type=natural_person.
Example: "Max"
type: string
last_name:
description: |
Last name of the representative. Only provided for type=natural_person.
Example: "Mustermann"
type: string
date_of_birth:
description: |
Date of birth of the representative. Only provided for type=natural_person.
May still be null for natural persons if it is not available.
Format: ISO 8601 (YYYY-MM-DD)
Example: "1990-01-01"
type: string
required:
- name
- type
- role
- start_date
- city
- country
CompanyShareholders:
type: object
properties:
document_id:
description: |
Unique identifier for the document this was taken from.
Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
type: string
date:
description: |
Date when this shareholder information became effective.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
shareholders:
type: array
items:
$ref: "#/components/schemas/CompanyShareholder"
required:
- document_id
- date
- shareholders
CompanyShareholder:
type: object
properties:
id:
description: |
Unique identifier for the shareholder.
For companies: Format matches company_id pattern
For individuals: UUID
Example: "DE-HRB-F1103-267645" or UUID
May be null for certain shareholders.
type: string
type:
description: The type of shareholder.
$ref: "#/components/schemas/EntityType"
name:
description: The name of the shareholder. E.g. "Max Mustermann" or "Max Mustermann GmbH"
type: string
nominal_share:
description: |
Nominal value of shares in Euro.
Example: 100
type: integer
format: int64
percentage_share:
description: |
Percentage of company ownership.
Example: 5.36 represents 5.36% ownership
type: number
format: double
country:
description: |
Country where the shareholder is located, in ISO 3166-1 alpha-2 format.
Example: "DE" for Germany
type: string
required:
- name
- type
- nominal_share
- percentage_share
- country
EntityType:
type: string
enum:
- natural_person
- legal_person
RepresentationRole:
type: string
enum:
- DIRECTOR
- PROKURA
- SHAREHOLDER
- OWNER
- PARTNER
- PERSONAL_LIABLE_DIRECTOR
- LIQUIDATOR
- OTHER
CompanyFinancials:
type: object
properties:
reports:
description: The financial reports of the company.
type: array
items:
$ref: "#/components/schemas/FinancialReport"
indicators:
description: |
Key financial metrics extracted from the reports.
Includes balance sheet totals, revenue, and other important figures.
type: array
items:
$ref: "#/components/schemas/FinancialIndicator"
required:
- reports
- indicators
FinancialReport:
type: object
properties:
id:
description: The unique identifier for the financial report. E.g. "f47ac10b-58cc-4372-a567-0e02b2c3d479"
type: string
name:
description: The name of the financial report. E.g. "Jahresabschluss 2022"
type: string
published_at:
description: The date when the financial report was published. E.g. "2022-01-01"
type: string
required:
- id
- name
- published_at
FinancialIndicator:
type: object
properties:
report_id:
description: >-
The identifier for the financial report this indicator originates from. E.g.
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
type: string
type:
description: The type of indicator.
type: string
enum:
- balance_sheet_total
- net_income
- revenue
- cash
- employees
- equity
- real_estate
- materials
- pension_provisions
- salaries
- taxes
- liabilities
- capital_reserves
value:
description: |
Value of the indicator in the smallest currency unit (cents).
Example: 2099 represents €20.99 for monetary values
For non-monetary values (e.g., employees), the actual number.
type: integer
format: int64
date:
description: |
Date to which this financial indicator applies.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
required:
- report_id
- type
- value
- date
Contact:
type: object
properties:
source_url:
description: |
Where the contact information was found.
Example: "https://openregister.de"
type: string
format: uri
email:
description: |
Company contact email address.
Example: "founders@openregister.de"
type: string
phone:
description: |
Company phone number.
Example: "+49 030 12345678"
type: string
vat_id:
description: |
Value Added Tax identification number. (Umsatzsteuer-Identifikationsnummer)
Example: "DE370146530"
type: string
required:
- source_url
Document:
type: object
properties:
id:
description: The unique identifier for the document. E.g. "f47ac10b-58cc-4372-a567-0e02b2c3d479"
type: string
name:
description: The name of the document. E.g. "Musterprotokoll vom 01.01.2022"
type: string
date:
description: The date of the document. E.g. "2022-01-01"
type: string
url:
description: >-
The URL of the document. It can be downloaded from there. Only valid for 15 minutes after the
request.
type: string
format: uri
type:
description: The type of document.
type: string
enum:
- articles_of_association
- sample_protocol
- shareholder_list
required:
- id
- name
- date
- url
- type
Pagination:
type: object
properties:
page:
type: integer
description: Current page number.
per_page:
type: integer
description: Number of results per page.
total_pages:
type: integer
description: Total number of pages.
total_results:
type: integer
description: Total number of results.
required:
- page
- per_page
- total_pages
- total_results
DocumentJobStatus:
type: object
properties:
status:
type: string
enum:
- pending
- completed
- failed
url:
type: string
format: uri
date:
type: string
description: |
Date when the job was created.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
required:
- status
DocumentJob:
type: object
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
document_category:
type: string
enum:
- current_printout
- chronological_printout
- historical_printout
- structured_information
- shareholder_list
- articles_of_association
required:
- company_id
- document_category
DocumentJobResponse:
type: object
properties:
id:
type: string
description: |
Unique job identifier.
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
format: uuid
required:
- id