Copy
openapi: 3.1.0
info:
title: OpenRegister API
version: 1.0.0
description: |
API for accessing comprehensive company data from official registers.
This API provides access to company information, shareholder data, financial reports, and contact details.
servers:
- url: https://api.openregister.de
description: Production
security:
- BearerAuth: []
paths:
/v1/autocomplete/company:
get:
tags:
- v1
summary: Autocomplete company search
operationId: autocompleteCompany
parameters:
- name: query
in: query
required: true
description: |
Text search query to find companies by name.
Example: "Descartes Technologies UG"
schema:
type: string
responses:
"200":
description: Successful search operation
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyAutocompleteResponse"
"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: 'My API Key',
});
const response = await client.search.autocompleteCompaniesV1({ query: 'query' });
console.log(response.results);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.search.autocomplete_companies_v1(
query="query",
)
print(response.results)
- 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"),
)
response, err := client.Search.AutocompleteCompaniesV1(context.TODO(), openregister.SearchAutocompleteCompaniesV1Params{
Query: "query",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Results)
}
/v1/search/company:
post:
tags:
- v1
summary: Search for companies
operationId: companyFilterSearch
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CompanySearchRequest"
required: true
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: 'My API Key',
});
const companySearch = await client.search.findCompaniesV1();
console.log(companySearch.pagination);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
company_search = client.search.find_companies_v1()
print(company_search.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"),
)
companySearch, err := client.Search.FindCompaniesV1(context.TODO(), openregister.SearchFindCompaniesV1Params{
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", companySearch.Pagination)
}
/v1/search/person:
post:
tags:
- v1
summary: Search for people
operationId: personFilterSearch
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/PersonSearchRequest"
required: true
responses:
"200":
description: Successful search operation
content:
application/json:
schema:
$ref: "#/components/schemas/PersonSearchResponse"
"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: 'My API Key',
});
const response = await client.search.findPersonV1();
console.log(response.pagination);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.search.find_person_v1()
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"),
)
response, err := client.Search.FindPersonV1(context.TODO(), openregister.SearchFindPersonV1Params{
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Pagination)
}
/v0/search/company:
get:
tags:
- v0
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: 'My API Key',
});
const companySearch = await client.search.findCompaniesV0();
console.log(companySearch.pagination);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
company_search = client.search.find_companies_v0()
print(company_search.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"),
)
companySearch, err := client.Search.FindCompaniesV0(context.TODO(), openregister.SearchFindCompaniesV0Params{
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", companySearch.Pagination)
}
/v0/search/lookup:
get:
tags:
- v0
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: 'My API Key',
});
const response = await client.search.lookupCompanyByURL({ url: 'https://example.com' });
console.log(response.company_id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
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"),
)
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:
tags:
- v0
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
/v1/company/{company_id}:
get:
tags:
- v1
summary: Get detailed company information
operationId: getCompanyV1
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
- name: realtime
in: query
required: false
description: >
Get the most up-to-date company information directly from the Handelsregister.
When set to true, we fetch the latest data in real-time from the official German commercial
register, ensuring you receive the most current company details.
Note: Real-time requests take longer but guarantee the freshest data available.
schema:
type: boolean
responses:
"200":
description: Successfully retrieved company data
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyV1"
"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: 'My API Key',
});
const response = await client.company.getDetailsV1('company_id');
console.log(response.id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.company.get_details_v1(
company_id="company_id",
)
print(response.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"),
)
response, err := client.Company.GetDetailsV1(
context.TODO(),
"company_id",
openregister.CompanyGetDetailsV1Params{
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.ID)
}
/v1/person/{person_id}:
get:
tags:
- v1
summary: Get detailed person information
operationId: getPerson
parameters:
- name: person_id
in: path
description: The id of the person
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Successfully retrieved person data
content:
application/json:
schema:
$ref: "#/components/schemas/Person"
"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 - Person 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: 'My API Key',
});
const response = await client.person.getDetailsV1('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(response.id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.person.get_details_v1(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.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"),
)
response, err := client.Person.GetDetailsV1(context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.ID)
}
/v0/company/{company_id}/shareholders:
get:
tags:
- v0
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
/v1/company/{company_id}/owners:
get:
tags:
- v1
summary: Get company owners
operationId: getOwners
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
- name: realtime
in: query
required: false
description: >
Get the most up-to-date company information directly from the Handelsregister.
When set to true, we fetch the latest data in real-time from the official German commercial
register, ensuring you receive the most current company details.
Note: Real-time requests take longer but guarantee the freshest data available.
schema:
type: boolean
responses:
"200":
description: The owners of the company
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyOwners"
"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: 'My API Key',
});
const response = await client.company.getOwnersV1('company_id');
console.log(response.company_id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.company.get_owners_v1(
company_id="company_id",
)
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"),
)
response, err := client.Company.GetOwnersV1(
context.TODO(),
"company_id",
openregister.CompanyGetOwnersV1Params{
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.CompanyID)
}
/v1/company/{company_id}/holdings:
get:
tags:
- v1
summary: Get company holdings
operationId: getHoldings
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
responses:
"200":
description: The holdings of the company
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyHoldings"
"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: 'My API Key',
});
const response = await client.company.getHoldingsV1('company_id');
console.log(response.company_id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.company.get_holdings_v1(
"company_id",
)
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"),
)
response, err := client.Company.GetHoldingsV1(context.TODO(), "company_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.CompanyID)
}
/v1/person/{person_id}/holdings:
get:
tags:
- v1
summary: Get person holdings
operationId: getPersonHoldings
parameters:
- name: person_id
in: path
required: true
description: |
Unique person identifier.
Example: cc78ab54-d958-49b8-bae7-2f6c0c308837
schema:
type: string
format: uuid
responses:
"200":
description: The holdings of the person
content:
application/json:
schema:
$ref: "#/components/schemas/PersonHoldings"
"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: 'My API Key',
});
const response = await client.person.getHoldingsV1('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(response.person_id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.person.get_holdings_v1(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.person_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"),
)
response, err := client.Person.GetHoldingsV1(context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.PersonID)
}
/v0/company/{company_id}/contact:
get:
tags:
- v0
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: 'My API Key',
});
const response = await client.company.getContactV0('company_id');
console.log(response.vat_id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.company.get_contact_v0(
"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"),
)
response, err := client.Company.GetContactV0(context.TODO(), "company_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.VatID)
}
/v0/document/{document_id}:
get:
tags:
- v0
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
/v1/document/{document_id}:
get:
tags:
- v1
summary: Get document information
operationId: getDocumentV1
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: 'My API Key',
});
const response = await client.document.getCachedV1('document_id');
console.log(response.id);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.document.get_cached_v1(
"document_id",
)
print(response.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"),
)
response, err := client.Document.GetCachedV1(context.TODO(), "document_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.ID)
}
/v0/document/{document_id}/download:
get:
tags:
- v0
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
/v0/jobs/document/{id}:
get:
tags:
- v0
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
/v0/jobs/document:
post:
tags:
- v0
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
/v1/document:
get:
tags:
- v1
summary: Fetch a document in realtime.
operationId: getRealtimeDocument
parameters:
- name: company_id
in: query
required: true
schema:
type: string
- name: document_category
in: query
required: true
schema:
type: string
enum:
- current_printout
- chronological_printout
- historical_printout
- structured_information
- shareholder_list
- articles_of_association
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/RealtimeDocumentResponse"
"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: 'My API Key',
});
const response = await client.document.getRealtimeV1({
company_id: 'company_id',
document_category: 'current_printout',
});
console.log(response.category);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.document.get_realtime_v1(
company_id="company_id",
document_category="current_printout",
)
print(response.category)
- 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"),
)
response, err := client.Document.GetRealtimeV1(context.TODO(), openregister.DocumentGetRealtimeV1Params{
CompanyID: "company_id",
DocumentCategory: openregister.DocumentGetRealtimeV1ParamsDocumentCategoryCurrentPrintout,
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Category)
}
/v1/company/{company_id}/financials:
get:
tags:
- v1
summary: Get financial reports
operationId: getFinancialReports
parameters:
- name: company_id
in: path
required: true
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/FinancialsResponse"
"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: 'My API Key',
});
const response = await client.company.getFinancialsV1('company_id');
console.log(response.reports);
- lang: Python
source: |-
from openregister import Openregister
client = Openregister(
api_key="My API Key",
)
response = client.company.get_financials_v1(
"company_id",
)
print(response.reports)
- 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"),
)
response, err := client.Company.GetFinancialsV1(context.TODO(), "company_id")
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Reports)
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
API Key Authentication
Provide your API key as a Bearer token in the Authorization header.
schemas:
SearchFilterBase:
type: object
description: |
Filter by field. The property sets `value`, `values`, `keywords` and `min`/`max`
are mutually exclusive. Dates must be YYYY-MM-DD.
properties:
value:
type: string
min:
type: string
max:
type: string
values:
type: array
items:
type: string
keywords:
type: array
items:
type: string
PersonSearchFilter:
allOf:
- $ref: "#/components/schemas/SearchFilterBase"
- type: object
properties:
field:
$ref: "#/components/schemas/PersonSearchFilterField"
required:
- field
CompanySearchFilter:
allOf:
- $ref: "#/components/schemas/SearchFilterBase"
- type: object
properties:
field:
$ref: "#/components/schemas/CompanySearchFilterField"
required:
- field
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
CompanySearchRequest:
type: object
properties:
query:
description: |
Search query to filter companies.
$ref: "#/components/schemas/CompanySearchRequestQuery"
filters:
description: |
Filters to filter companies.
type: array
items:
$ref: "#/components/schemas/CompanySearchFilter"
location:
description: |
Location to filter companies.
$ref: "#/components/schemas/CompanySearchLocationFilter"
pagination:
description: |
Pagination parameters.
$ref: "#/components/schemas/SearchRequestPagination"
PersonSearchRequest:
type: object
properties:
query:
description: |
Search query to filter people.
$ref: "#/components/schemas/PersonSearchRequestQuery"
filters:
description: |
Filters to filter people.
type: array
items:
$ref: "#/components/schemas/PersonSearchFilter"
pagination:
description: |
Pagination parameters.
$ref: "#/components/schemas/SearchRequestPagination"
CompanySearchRequestQuery:
type: object
properties:
value:
type: string
description: |
Search query to filter companies.
required:
- value
PersonSearchRequestQuery:
type: object
properties:
value:
type: string
description: |
Search query to filter people.
required:
- value
SearchRequestPagination:
type: object
properties:
page:
type: integer
description: |
Page number to return.
per_page:
type: integer
description: |
Number of results per page.
PersonSearchFilterField:
type: string
enum:
- date_of_birth
- city
- active
CompanySearchFilterField:
type: string
enum:
- status
- legal_form
- register_number
- register_court
- register_type
- city
- active
- incorporated_at
- zip
- address
- balance_sheet_total
- revenue
- cash
- employees
- equity
- real_estate
- materials
- pension_provisions
- salaries
- taxes
- liabilities
- capital_reserves
- net_income
- industry_codes
- capital_amount
- capital_currency
- number_of_owners
- has_sole_owner
- has_representative_owner
- is_family_owned
- youngest_owner_age
SearchFilter:
type: object
description: |
Filter by field. The properties values, value, keywords and min/max are mutually exclusive.
Dates must be in the format YYYY-MM-DD.
properties:
field:
oneOf:
- $ref: "#/components/schemas/PersonSearchFilterField"
- $ref: "#/components/schemas/CompanySearchFilterField"
value:
type: string
description: |
Value to filter on.
min:
type: string
description: |
Minimum value to filter on.
max:
type: string
description: |
Maximum value to filter on.
values:
type: array
items:
type: string
description: |
Values to filter on.
keywords:
type: array
items:
type: string
description: |
Keywords to filter on.
CompanySearchLocationFilter:
type: object
properties:
longitude:
type: number
x-go-type: float64
description: |
Longitude to filter on.
latitude:
type: number
x-go-type: float64
description: |
Latitude to filter on.
radius:
type: number
description: |
Radius in kilometers to filter on.
Example: 10
required:
- longitude
- latitude
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: "[email protected]"
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
PersonSearchResponse:
type: object
properties:
results:
type: array
description: |
List of people matching the search criteria.
items:
$ref: "#/components/schemas/PersonSearchResponseItem"
pagination:
$ref: "#/components/schemas/Pagination"
required:
- results
- pagination
CompanyAutocompleteResponse:
type: object
properties:
results:
type: array
description: |
List of companies matching the search criteria.
items:
$ref: "#/components/schemas/CompanySearchResponseItem"
required:
- results
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
nullable: true
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
- country
- register_number
- register_type
- register_court
- active
- legal_form
PersonSearchResponseItem:
type: object
properties:
id:
type: string
description: |
Unique person identifier.
Example: 1234-5678-9012-345678901234
name:
type: string
description: |
Name of the person.
Example: "Max Mustermann"
city:
type: string
description: |
City of the person.
Example: "Berlin"
nullable: true
date_of_birth:
type: string
description: |
Date of birth of the person.
Format: ISO 8601 (YYYY-MM-DD)
Example: "1990-01-01"
active:
type: boolean
description: |
Person status - true if active, false if inactive.
required:
- id
- name
- city
- date_of_birth
- active
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"
x-stainless-naming:
python:
property_name: company_register
argument_name: company_register
method_argument: company_register
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
CompanyV1:
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"
x-stainless-naming:
python:
property_name: company_register
argument_name: company_register
method_argument: company_register
registers:
description: |
Historical registration changes.
Shows how registration details changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyRegister"
status:
description: |
Current status of the company:
- active: Operating normally
- inactive: No longer operating
- liquidation: In the process of being dissolved
type: string
enum:
- active
- inactive
- liquidation
name:
description: |
Current official name of the company.
$ref: "#/components/schemas/CompanyName"
names:
description: |
Historical company names.
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.
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.
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.
Shows how the company capital changed over time.
type: array
items:
$ref: "#/components/schemas/CompanyCapital"
representation:
description: |
List of individuals or entities authorized to represent the company.
Includes directors, officers, and authorized signatories.
type: array
items:
$ref: "#/components/schemas/CompanyRepresentativeV1"
indicators:
description: |
Key company indicators like net income, employee count, revenue, etc..
$ref: "#/components/schemas/CompanyIndicators"
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.
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
nullable: true
industry_codes:
description: |
Industry codes of the company.
type: object
properties:
WZ2025:
type: array
items:
$ref: "#/components/schemas/IndustryCode"
required:
- WZ2025
sources:
description: |
Sources of the company data.
type: array
items:
$ref: "#/components/schemas/Source"
required:
- id
- register
- registers
- status
- name
- names
- address
- addresses
- purpose
- purposes
- capital
- capitals
- representation
- indicators
- legal_form
- documents
- incorporated_at
- terminated_at
- industry_codes
- sources
Source:
type: object
properties:
document_url:
description: |
Url of the source document. In the form of a presigned url accessible for 30 minutes.
type: string
required:
- document_url
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:
nullable: true
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:
nullable: true
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
CompanyRepresentativeV1:
type: object
properties:
id:
description: |
Unique identifier for the representative.
For companies: Format matches company_id pattern
For individuals: UUID
Example: "DE-HRB-F1103-267645" or UUID
May be null for certain representatives.
type: string
nullable: true
name:
description: The name of the representative. E.g. "Max Mustermann" or "Max Mustermann GmbH"
type: string
type:
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
nullable: true
legal_person:
$ref: "#/components/schemas/CompanyRepresentativeV1LegalPerson"
natural_person:
$ref: "#/components/schemas/CompanyRepresentativeV1NaturalPerson"
required:
- id
- name
- type
- role
- start_date
- end_date
CompanyRepresentativeV1NaturalPerson:
nullable: true
type: object
properties:
city:
description: |
City where the representative is located.
Example: "Berlin"
type: string
nullable: true
first_name:
description: |
First name of the representative.
Example: "Max"
type: string
nullable: true
last_name:
description: |
Last name of the representative.
Example: "Mustermann"
type: string
nullable: true
date_of_birth:
description: |
Date of birth of the representative.
May still be null for natural persons if it is not available.
Format: ISO 8601 (YYYY-MM-DD)
Example: "1990-01-01"
type: string
nullable: true
required:
- city
- first_name
- last_name
- date_of_birth
CompanyRepresentativeV1LegalPerson:
type: object
nullable: true
properties:
name:
type: string
city:
type: string
nullable: true
country:
description: |
Country where the representative is located, in ISO 3166-1 alpha-2 format.
Example: "DE" for Germany
type: string
required:
- name
- city
- country
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
CompanyIndicators:
description: |
The indicators for the company sorted by date with the first element being the latest.
type: array
items:
$ref: "#/components/schemas/CompanyIndicator"
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
CompanyIndicator:
description: |
The indicators of the company for a given year.
Values of the indicator are given in the smallest currency unit (cents).
Example: 2099 represents €20.99 for monetary values
For non-monetary values (e.g., employees), the actual number.
type: object
properties:
date:
description: |
Date to which this financial indicators apply.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
report_id:
description: The report id (source) of the indicators.
type: string
format: uuid
balance_sheet_total:
description: The balance sheet total of that year (in cents).
type: integer
format: int64
nullable: true
net_income:
description: The net income of that year (in cents).
type: integer
format: int64
nullable: true
revenue:
description: The revenue of that year (in cents).
type: integer
format: int64
nullable: true
cash:
description: The cash of that year (in cents).
type: integer
format: int64
nullable: true
employees:
description: The number of employees of that year.
type: integer
format: int64
nullable: true
equity:
description: The equity of that year (in cents).
type: integer
format: int64
nullable: true
real_estate:
description: The real estate of that year (in cents).
type: integer
format: int64
nullable: true
materials:
description: The materials of that year (in cents).
type: integer
format: int64
nullable: true
pension_provisions:
description: The pension provisions of that year (in cents).
type: integer
format: int64
nullable: true
salaries:
description: The salaries of that year (in cents).
type: integer
format: int64
nullable: true
taxes:
description: The taxes of that year (in cents).
type: integer
format: int64
nullable: true
liabilities:
description: The liabilities of that year (in cents).
type: integer
format: int64
nullable: true
capital_reserves:
description: The capital reserves of that year (in cents).
type: integer
format: int64
nullable: true
required:
- date
- report_id
- balance_sheet_total
- net_income
- revenue
- cash
- employees
- equity
- real_estate
- materials
- pension_provisions
- salaries
- taxes
- liabilities
- capital_reserves
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: "[email protected]"
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
RealtimeDocumentResponse:
type: object
properties:
url:
type: string
format: uri
category:
type: string
enum:
- current_printout
- chronological_printout
- historical_printout
- structured_information
- shareholder_list
- articles_of_association
file_date:
type: string
nullable: true
file_name:
type: string
nullable: true
required:
- url
- category
- file_date
- file_name
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
CompanyOwners:
type: object
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
owners:
type: array
items:
$ref: "#/components/schemas/CompanyOwnerItem"
sources:
description: |
Sources of the company owners data.
type: array
items:
$ref: "#/components/schemas/Source"
required:
- company_id
- owners
- sources
CompanyOwnerItem:
type: object
properties:
id:
description: |
Unique identifier for the shareholder.
For companies: Format matches company_id pattern
For individuals: UUID
Example: "DE-HRB-F1103-267645" or UUID
May be null for certain shareholders.
type: string
nullable: true
type:
description: The type of shareholder.
$ref: "#/components/schemas/EntityType"
relation_type:
description: |
Type of relationship between the entity and the company.
$ref: "#/components/schemas/CompanyRelationType"
name:
description: The name of the shareholder. E.g. "Max Mustermann" or "Max Mustermann GmbH"
type: string
natural_person:
description: |
Details about the natural person.
$ref: "#/components/schemas/CompanyOwnerNaturalPerson"
legal_person:
description: |
Details about the legal person.
$ref: "#/components/schemas/CompanyOwnerLegalPerson"
nominal_share:
description: |
Nominal value of shares in Euro.
Example: 100
type: number
format: double
percentage_share:
description: |
Percentage of company ownership.
Example: 5.36 represents 5.36% ownership
type: number
format: double
nullable: true
start:
description: |
Date when the relation started. Only available for some types of owners.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
nullable: true
required:
- id
- type
- relation_type
- name
- natural_person
- legal_person
- nominal_share
- percentage_share
- start
CompanyOwnerNaturalPerson:
type: object
nullable: true
properties:
full_name:
type: string
first_name:
type: string
last_name:
type: string
date_of_birth:
type: string
nullable: true
city:
type: string
country:
type: string
required:
- full_name
- first_name
- last_name
- date_of_birth
- city
- country
CompanyOwnerLegalPerson:
type: object
nullable: true
properties:
name:
type: string
city:
type: string
nullable: true
country:
description: |
Country where the owner is located, in ISO 3166-1 alpha-2 format.
Example: "DE" for Germany
type: string
required:
- name
- city
- country
CompanyHoldings:
type: object
description: |
Companies this entity owns or has invested in.
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
holdings:
type: array
items:
$ref: "#/components/schemas/CompanyHoldingItem"
required:
- company_id
- holdings
CompanyHoldingItem:
type: object
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
relation_type:
description: |
Type of relationship between the entity and the company.
$ref: "#/components/schemas/CompanyRelationType"
name:
type: string
description: |
Name of the company.
nominal_share:
type: number
description: |
Amount of shares or capital in the company.
Example: 100
format: double
percentage_share:
type: number
description: |
Share of the company.
Example: 0.5 represents 50% ownership
format: double
nullable: true
start:
type: string
description: |
Date when the ownership started.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
nullable: true
end:
type: string
description: |
Date when the ownership ended.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
nullable: true
required:
- company_id
- relation_type
- name
- nominal_share
- percentage_share
- start
- end
CompanyRelationType:
type: string
enum:
- shareholder
- stockholder
- limited_partner
- general_partner
FinancialsResponse:
type: object
properties:
reports:
type: array
items:
$ref: "#/components/schemas/Report"
required:
- reports
Report:
type: object
properties:
report_id:
description: |
Unique identifier for the financial report.
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
type: string
consolidated:
description: |
Whether the report is a consolidated report or not.
type: boolean
aktiva:
$ref: "#/components/schemas/ReportTable"
passiva:
$ref: "#/components/schemas/ReportTable"
guv:
nullable: true
$ref: "#/components/schemas/ReportTable"
report_start_date:
type: string
nullable: true
report_end_date:
type: string
required:
- report_id
- aktiva
- consolidated
- passiva
- report_end_date
- report_start_date
ReportTable:
type: object
properties:
rows:
type: array
items:
$ref: "#/components/schemas/ReportRow"
required:
- rows
ReportRow:
type: object
properties:
name:
type: string
formatted_name:
type: string
current_value:
type: integer
format: int64
nullable: true
previous_value:
type: integer
format: int64
nullable: true
children:
type: array
items:
$ref: "#/components/schemas/ReportRow"
required:
- name
- formatted_name
- current_value
- previous_value
- children
Person:
type: object
properties:
id:
description: |
Unique person identifier.
Example: cc78ab54-d958-49b8-bae7-2f6c0c308837
type: string
first_name:
description: |
First name of the person.
type: string
last_name:
description: |
Last name of the person.
type: string
date_of_birth:
description: |
Date of birth of the person.
Format: ISO 8601 (YYYY-MM-DD)
Example: "1990-01-01"
type: string
nullable: true
age:
description: |
Age of the person.
type: integer
nullable: true
city:
description: |
City of the person.
type: string
management_positions:
description: |
Management positions of the person.
type: array
items:
description: |
All current and past management positions of the person.
$ref: "#/components/schemas/PersonManagementPosition"
required:
- id
- first_name
- last_name
- date_of_birth
- age
- city
- age
- management_positions
PersonManagementPosition:
type: object
properties:
register_id:
type: string
description: |
Register ID of the company.
Example: DE-HRB-F1103-267645
company_name:
type: string
description: |
Name of the company.
Example: "Descartes Technologies GmbH"
role:
type: string
description: |
Role of the person in the company.
Example: "DIRECTOR"
start_date:
description: |
Date when the person started the management position.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
type: string
end_date:
description: |
Date when the person ended the management position.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2023-01-01"
type: string
required:
- register_id
- company_name
- role
PersonHoldings:
type: object
description: |
Companies this entity owns or has invested in.
properties:
person_id:
type: string
description: |
Unique person identifier.
Example: cc78ab54-d958-49b8-bae7-2f6c0c308837
holdings:
description: |
Shareholder and limited partner positions of the person.
type: array
items:
$ref: "#/components/schemas/PersonHoldingItem"
required:
- person_id
- holdings
IndustryCode:
type: object
description: |
Industry codes from WZ 2025.
properties:
code:
type: string
required:
- code
PersonHoldingItem:
type: object
properties:
company_id:
type: string
description: |
Unique company identifier.
Example: DE-HRB-F1103-267645
relation_type:
description: |
Type of relationship between the entity and the company.
$ref: "#/components/schemas/CompanyRelationType"
name:
type: string
description: |
Name of the company.
nominal_share:
type: number
description: |
Amount of shares or capital in the company.
Example: 100
format: double
percentage_share:
type: number
description: |
Share of the company.
Example: 0.5 represents 50% ownership
format: double
nullable: true
start:
type: string
description: |
Date when the ownership started.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
nullable: true
end:
type: string
description: |
Date when the ownership ended.
Format: ISO 8601 (YYYY-MM-DD)
Example: "2022-01-01"
nullable: true
required:
- company_id
- relation_type
- name
- nominal_share
- percentage_share
- start
- end