> ## Documentation Index
> Fetch the complete documentation index at: https://docs.registercheck.de/llms.txt
> Use this file to discover all available pages before exploring further.
# Filter Companies
> Filter companies with advanced filtering capabilities.
This endpoint allows filtering companies using advanced criteria across multiple entities
such as shareholders, representatives, limited partners, and company metadata.
It also supports filtering by recently founded companies within a specified time period.
Args:
request_data: Request body containing filter criteria and pagination
Returns:
A filtered list of companies with their basic information
## Filter Object Documentation
This endpoint accepts an optional `filters` parameter that enables advanced filtering across multiple data entities. The filter system supports complex queries across company information, metadata, relationships, and geographic data.
**Learn about all available filters, operators, and examples**
View the comprehensive filtering documentation to understand all supported filter types, operators, and see practical examples for every use case.
## Root‑Level Date Parameters (`days`, `start_date`, `end_date`)
Need to limit results to *recent* or *specific* founding dates? Use these **root‑level** date parameter
| Parameter | Type | Required | Description |
| ------------ | ------------------- | -------- | ----------------------------------------------------------------------------- |
| `days` | Integer | No¹ | Return companies founded within the last **N** days counting back from today. |
| `start_date` | String (YYYY‑MM‑DD) | No¹ | Inclusive lower bound for founding date. |
| `end_date` | String (YYYY‑MM‑DD) | No¹ | Inclusive upper bound for founding date. |
¹ Supply **either** `days` *or* (`start_date` & `end_date`).
### Usage Rules
* **Top‑level only** – add them as top‑level keys (i.e., sibling properties of filters), don't nest them inside the filters object.
* If `end_date` is present it must be **≥ `start_date`**.
* Omit all three parameters if you don’t need a founding‑date filter.
### Quick Date Examples
#### Companies Founded in the Last 30Â Days
```json theme={null}
{
"offset": 0,
"limit": 50,
"days": 30,
"filters": {
"company": {
"is_active": {"operator": "eq", "value": true}
}
}
}
```
#### Companies Founded Between Two Dates
```json theme={null}
{
"offset": 0,
"limit": 50,
"start_date": "2025-01-01",
"end_date": "2025-06-30",
"filters": {
"company": {
"city": {"operator": "eq", "value": "Berlin"}
}
}
}
```
***
### Quick Filter Examples
#### Basic Company Filter
```json theme={null}
{
"offset": 0,
"limit": 50,
"filters": {
"company": {
"legal_form": {
"operator": "eq",
"value": "GmbH"
},
"is_active": {
"operator": "eq",
"value": true
}
}
}
}
```
#### Geographic + Metadata Filter
```json theme={null}
{
"offset": 0,
"limit": 50,
"filters": {
"company": {
"location": {
"operator": "within_radius",
"center_lat": 48.1351,
"center_lng": 11.5820,
"radius_meters": 5000
}
},
"company_meta_data": {
"share_capital": {
"operator": "gte",
"value": 25000
}
}
}
}
```
#### Relationship Filter
```json theme={null}
{
"offset": 0,
"limit": 50,
"filters": {
"shareholders": {
"company_id": {
"operator": "eq",
"value": "2b902e97-266e-4415-9342-59e8aaf101fd"
}
}
}
}
```
### Supported Filter Types
* **Company**: Basic company information (name, legal form, register details, location)
* **Company Metadata**: Extended data (address, purpose, share capital)
* **Shareholders**: Company ownership relationships
* **Representatives**: Management and representation relationships
* **Limited Partners**: Partnership relationships
* **Prokura**: Power of attorney relationships
**Need more examples?** Check out the [complete filtering documentation](/filtering) for detailed explanations, all available operators, and comprehensive examples for every filter type.
## OpenAPI
````yaml post /filter/companies
openapi: 3.1.0
info:
title: Registercheck API
version: 1.0.0
servers:
- url: https://jobs-api.registercheck.de/api/v2
security: []
paths:
/filter/companies:
post:
tags:
- Filter
summary: Filter Companies
description: >-
Filter companies with advanced filtering capabilities.
This endpoint allows filtering companies using advanced criteria across
multiple entities
such as shareholders, representatives, limited partners, and company
metadata.
It also supports filtering by recently founded companies within a
specified time period.
Args:
request_data: Request body containing filter criteria and pagination
Returns:
A filtered list of companies with their basic information
operationId: filter_companies_filter_companies_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompaniesFilterRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FilterCompaniesResponse'
'404':
description: No companies found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Internal server error
security:
- HTTPBearer: []
components:
schemas:
CompaniesFilterRequest:
properties:
days:
anyOf:
- type: integer
- type: 'null'
title: Days
description: >-
Filter companies founded within the last X days (optional if date
range is provided)
start_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Start Date
description: Start date for founding date range filter (YYYY-MM-DD format)
end_date:
anyOf:
- type: string
format: date
- type: 'null'
title: End Date
description: End date for founding date range filter (YYYY-MM-DD format)
register_court:
anyOf:
- type: string
- type: 'null'
title: Register Court
description: Filter by register court
offset:
type: integer
title: Offset
description: Pagination offset
default: 0
limit:
type: integer
title: Limit
description: Pagination limit (max 100)
default: 10
filters:
anyOf:
- $ref: '#/components/schemas/CompaniesAdvancedFilter'
- type: 'null'
description: Advanced filtering options
bypass_cache:
type: boolean
title: Bypass Cache
description: Bypass cache and fetch fresh data
default: false
type: object
title: CompaniesFilterRequest
description: Request model for filtering companies
FilterCompaniesResponse:
properties:
companies:
items:
$ref: '#/components/schemas/FilteredCompany'
type: array
title: Companies
description: List of filtered companies
pagination:
$ref: >-
#/components/schemas/registercheck_jobs__api__models__filter_response__PaginationInfo
description: Pagination information for the results
applied_filters:
$ref: '#/components/schemas/AppliedFilters'
description: Information about the filters that were applied
type: object
required:
- companies
- pagination
- applied_filters
title: FilterCompaniesResponse
description: Model for filter companies endpoint response
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CompaniesAdvancedFilter:
properties:
company:
anyOf:
- $ref: '#/components/schemas/CompanyAdvancedFilter'
- type: 'null'
description: >-
Filter by basic company information (name, legal form, registration
details)
company_meta_data:
anyOf:
- $ref: '#/components/schemas/CompanyMetaDataAdvancedFilter'
- type: 'null'
description: Filter by extended company metadata (address, purpose, capital)
shareholders:
anyOf:
- $ref: '#/components/schemas/ShareholderAdvancedFilter'
- type: 'null'
description: Filter by company shareholders and ownership structure
representatives:
anyOf:
- $ref: '#/components/schemas/ExtractedRepresentativesAdvancedFilter'
- type: 'null'
description: Filter by company representatives and management
limited_partners:
anyOf:
- $ref: '#/components/schemas/ExtractedLimitedPartnersAdvancedFilter'
- type: 'null'
description: Filter by limited partners (for partnerships)
prokura:
anyOf:
- $ref: '#/components/schemas/ProkuraAdvancedFilter'
- type: 'null'
description: Filter by prokura/power of attorney holders
type: object
title: CompaniesAdvancedFilter
description: Complete advanced filter model for recently founded companies
FilteredCompany:
properties:
id:
type: string
title: Id
description: Unique company identifier
name:
type: string
title: Name
description: Official company name
slug:
anyOf:
- type: string
- type: 'null'
title: Slug
description: URL-friendly version of the company name
legal_form:
anyOf:
- type: string
- type: 'null'
title: Legal Form
description: Legal form of the company (e.g., GmbH, AG)
register_number:
anyOf:
- type: integer
- type: 'null'
title: Register Number
description: Company registration number
register_prefix:
anyOf:
- type: string
- type: 'null'
title: Register Prefix
description: Company registration prefix (e.g., HRB)
register_court:
anyOf:
- type: string
- type: 'null'
title: Register Court
description: Court where the company is registered
country:
anyOf:
- type: string
- type: 'null'
title: Country
description: Country code where company is registered
default: DE
status:
anyOf:
- $ref: '#/components/schemas/CompanyStatus'
- type: 'null'
description: Current status of the company
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: Timestamp when the company record was created
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
description: Timestamp when the company record was last updated
type: object
required:
- id
- name
title: FilteredCompany
description: Model for a company in filter results
registercheck_jobs__api__models__filter_response__PaginationInfo:
properties:
total:
type: integer
title: Total
description: Total number of results available
offset:
type: integer
title: Offset
description: Number of results to skip from the beginning
limit:
type: integer
title: Limit
description: Maximum number of results to return in this page
type: object
required:
- total
- offset
- limit
title: PaginationInfo
description: Model for pagination information
AppliedFilters:
properties:
days:
anyOf:
- type: integer
- type: 'null'
title: Days
description: Number of days filter applied (if any)
register_court:
anyOf:
- type: string
- type: 'null'
title: Register Court
description: Register court filter applied (if any)
filters_applied:
type: boolean
title: Filters Applied
description: Whether advanced filters were applied
type: object
required:
- filters_applied
title: AppliedFilters
description: Model for applied filters information
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
CompanyAdvancedFilter:
properties:
name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by company name (supports 'eq', 'like', 'in')
legal_form:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by legal form (e.g., 'GmbH', 'AG', 'KG')
register_court:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by registration court (e.g., 'Amtsgericht München')
register_prefix:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by register prefix (e.g., 'HRB', 'HRA')
register_number:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by company registration number
is_active:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by company status - true for active, false for terminated
is_kg:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by KG partnership type - true for KG companies
location:
anyOf:
- $ref: '#/components/schemas/LocationFilterOperation'
- type: 'null'
description: Filter by geographic location using radius search
wkz_codes:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by WZ codes (German industry classification)
type: object
title: CompanyAdvancedFilter
description: Advanced filter model for Company fields
CompanyMetaDataAdvancedFilter:
properties:
headquarter:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by company headquarters location
full_address:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by complete address string
city:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by city name
state:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by state/province
country:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by country code (e.g., 'DE', 'AT', 'CH')
company_purpose:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by business purpose/activity description
share_capital:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by share capital amount (supports numeric operators)
type: object
title: CompanyMetaDataAdvancedFilter
description: Advanced filter model for CompanyMetaData fields
ShareholderAdvancedFilter:
properties:
company_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific company is a shareholder (use 'eq'
for single ID or 'in' for multiple IDs)
person_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific person is a shareholder (use 'eq'
for single ID or 'in' for multiple IDs)
name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by shareholder name (supports 'eq', 'like', 'in')
shareholder_type:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by shareholder type (e.g., 'natural_person', 'legal_entity')
percentage_share:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by percentage ownership (supports numeric operators like
'gte', 'lte', 'between')
is_entitled:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by entitlement status - true for entitled shareholders
type: object
title: ShareholderAdvancedFilter
description: >-
Advanced filter model for role-based shareholder filtering.
Allows filtering companies by their shareholders (either companies or
persons).
ExtractedRepresentativesAdvancedFilter:
properties:
company_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific company is a representative/manager
(use 'eq' for single ID or 'in' for multiple IDs)
person_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific person is a representative/manager
(use 'eq' for single ID or 'in' for multiple IDs)
name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by representative full name (supports 'eq', 'like', 'in',
'contains')
first_name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by representative first name
last_name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by representative last name
age:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by representative age in years (supports 'eq', 'gte', 'lte',
'between' operators)
birth_date:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by representative birth date (format: YYYY-MM-DD, supports
'eq', 'gte', 'lte', 'between' operators)
type: object
title: ExtractedRepresentativesAdvancedFilter
description: >-
Advanced filter model for role-based representative filtering.
Allows filtering companies by their representatives (either companies or
persons).
ExtractedLimitedPartnersAdvancedFilter:
properties:
company_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific company is a limited partner (use
'eq' for single ID or 'in' for multiple IDs)
person_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific person is a limited partner (use
'eq' for single ID or 'in' for multiple IDs)
name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by limited partner full/company name (supports 'eq', 'like',
'in', 'contains')
first_name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by limited partner first name
last_name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by limited partner last name
age:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by limited partner age in years (supports 'eq', 'gte', 'lte',
'between' operators)
birth_date:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by limited partner birth date (format: YYYY-MM-DD, supports
'eq', 'gte', 'lte', 'between' operators)
type: object
title: ExtractedLimitedPartnersAdvancedFilter
description: >-
Advanced filter model for role-based limited partner filtering.
Allows filtering companies by their limited partners (either companies
or persons).
ProkuraAdvancedFilter:
properties:
person_id:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Find companies where a specific person has prokura/power of attorney
(use 'eq' for single ID or 'in' for multiple IDs)
first_name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by prokura person first name
last_name:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: Filter by prokura person last name
age:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by prokura person age in years (supports 'eq', 'gte', 'lte',
'between' operators)
birth_date:
anyOf:
- $ref: '#/components/schemas/FilterOperation'
- type: 'null'
description: >-
Filter by prokura person birth date (format: YYYY-MM-DD, supports
'eq', 'gte', 'lte', 'between' operators)
type: object
title: ProkuraAdvancedFilter
description: |-
Advanced filter model for role-based prokura filtering.
Allows filtering companies by their prokura persons.
CompanyStatus:
type: string
enum:
- ACTIVE
- LIQUIDATION
- TERMINATED
title: CompanyStatus
FilterOperation:
properties:
operator:
type: string
title: Operator
description: >-
Filter operator: 'eq' (equals), 'in' (in list), 'gte' (greater than
or equal), 'lte' (less than or equal), 'like' (contains text),
'between' (range)
value:
anyOf:
- type: string
- type: integer
- type: number
- type: boolean
- type: 'null'
title: Value
description: Single value for operators like 'eq', 'gte', 'lte', 'like'
values:
anyOf:
- items: {}
type: array
- type: 'null'
title: Values
description: List of values for 'in' operator
min:
anyOf:
- type: number
- type: 'null'
title: Min
description: Minimum value for 'between' operator
max:
anyOf:
- type: number
- type: 'null'
title: Max
description: Maximum value for 'between' operator
type: object
required:
- operator
title: FilterOperation
description: Model for individual filter operations
LocationFilterOperation:
properties:
operator:
type: string
title: Operator
description: Location operator, currently only 'within_radius' is supported
default: within_radius
center_lat:
type: number
title: Center Lat
description: Center latitude coordinate for radius search
center_lng:
type: number
title: Center Lng
description: Center longitude coordinate for radius search
radius_meters:
type: number
title: Radius Meters
description: Search radius in meters from the center point
type: object
required:
- center_lat
- center_lng
- radius_meters
title: LocationFilterOperation
description: Model for location-based filter operations
securitySchemes:
HTTPBearer:
type: http
description: Enter your API key
scheme: bearer
````