Filter Options Reference

Overview

The filters object is an optional parameter that can be included in API requests to enable advanced filtering of German company data. This comprehensive reference covers all supported filter entities, operators, and provides practical examples for every use case.

This filter object can be used with endpoints like /filter/companies to precisely control which companies are returned based on complex criteria.

The filtering system allows you to query across multiple data entities simultaneously, including company information, metadata, relationships (shareholders, representatives, etc.), and geographic location.

The filtering system supports 23 different operators across 6 entity types, enabling complex queries like “Find all GmbH companies in Munich with share capital between €25,000-€100,000 that have a specific person as shareholder.”

How Filters Work

Filter Architecture

Our filtering system uses a multi-entity approach where you can filter across different data tables simultaneously:

Company: Basic company information (name, legal form, register details)
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

Filter Object Structure

The filters object follows this nested JSON structure:

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "entity_name": {
      "field_name": {
        "operator": "operator_type",
        "value": "filter_value"
      }
    }
  }
}

Example API Request:

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "legal_form": {
        "operator": "eq",
        "value": "GmbH"
      }
    }
  }
}

Filter Logic

Within Entity: All filters are combined with AND logic
Between Entities: Different entity filters are combined with AND logic
Joins: The system automatically handles database joins between entities

Available Operators

Equality Operators

Operator	Description	Supported Types	Example
`eq`	Equal to	All types	`{"operator": "eq", "value": "GmbH"}`
`ne`	Not equal to	All types	`{"operator": "ne", "value": "AG"}`

Comparison Operators

Operator	Description	Supported Types	Example
`gt`	Greater than	Numbers, Dates	`{"operator": "gt", "value": 25000}`
`gte`	Greater than or equal	Numbers, Dates	`{"operator": "gte", "value": 25000}`
`lt`	Less than	Numbers, Dates	`{"operator": "lt", "value": 100000}`
`lte`	Less than or equal	Numbers, Dates	`{"operator": "lte", "value": 100000}`

Pattern Matching

Operator	Description	Supported Types	Example
`like`	SQL LIKE (case sensitive)	Strings	`{"operator": "like", "value": "Tech%"}`
`ilike`	SQL ILIKE (case insensitive)	Strings	`{"operator": "ilike", "value": "%gmbh%"}`
`contains`	Contains substring	Strings	`{"operator": "contains", "value": "Software"}`
`starts_with`	Starts with prefix	Strings	`{"operator": "starts_with", "value": "Tech"}`
`ends_with`	Ends with suffix	Strings	`{"operator": "ends_with", "value": "GmbH"}`

List Operations

Operator	Description	Supported Types	Example
`in`	Value in list	Strings, Numbers, Booleans	`{"operator": "in", "values": ["GmbH", "UG", "AG"]}`
`not_in`	Value not in list	Strings, Numbers, Booleans	`{"operator": "not_in", "values": ["e.K.", "OHG"]}`

Range Operations

Operator	Description	Supported Types	Example
`range`	Between min and max (inclusive)	Numbers, Dates	`{"operator": "range", "min": 25000, "max": 100000}`

Geographic Operations

Operator	Description	Supported Types	Example
`within_radius`	Within distance from point	Geographic	`{"operator": "within_radius", "center_lat": 48.1351, "center_lng": 11.5820, "radius_meters": 5000}`

Company Filters

Filter companies by basic information from the Company table.

Supported Fields

Field	Type	Description	Example Operators
`name`	String	Company name	`eq`, `like`, `contains`
`legal_form`	String	Legal form (GmbH, AG, etc.)	`eq`, `in`, `not_in`
`city`	String	Company city	`eq`, `like`, `contains`
`register_court`	String	Register court	`eq`, `like`, `in`
`register_prefix`	String	Register prefix (HRB, HRA, etc.)	`eq`, `in`
`register_number`	Number	Register number	`eq`, `gt`, `lt`, `range`
`is_active`	Boolean	Active status	`eq`
`is_kg`	Boolean	Is partnership (KG)	`eq`
`location`	Geographic	Geographic coordinates	`within_radius`

Examples

Filter by Legal Form

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "legal_form": {
        "operator": "in",
        "values": ["GmbH", "UG", "AG"]
      }
    }
  }
}

Filter by City and Active Status

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "city": {
        "operator": "ilike",
        "value": "%münchen%"
      },
      "is_active": {
        "operator": "eq",
        "value": true
      }
    }
  }
}

Geographic Search (Companies in Munich)

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "location": {
        "operator": "within_radius",
        "center_lat": 48.1351,
        "center_lng": 11.5820,
        "radius_meters": 5000
      }
    }
  }
}

Register Number Range

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "register_number": {
        "operator": "range",
        "min": 100000,
        "max": 200000
      },
      "register_court": {
        "operator": "eq",
        "value": "Amtsgericht München"
      }
    }
  }
}

Company Metadata Filters

Filter companies by extended information from the CompanyMetaData table.

Supported Fields

Field	Type	Description	Example Operators
`company_name`	String	Extended company name	`eq`, `like`, `contains`
`legal_form`	String	Legal form	`eq`, `in`
`headquarter`	String	Headquarters location	`eq`, `like`, `contains`
`full_address`	String	Complete address	`like`, `contains`
`city`	String	City	`eq`, `like`, `contains`
`state`	String	State/region	`eq`, `in`
`country`	String	Country	`eq`, `in`
`company_purpose`	String	Business purpose	`like`, `contains`
`share_capital`	Number	Share capital amount	`eq`, `gt`, `lt`, `range`

Examples

Filter by Business Purpose

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company_meta_data": {
      "company_purpose": {
        "operator": "contains",
        "value": "Software"
      }
    }
  }
}

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company_meta_data": {
      "share_capital": {
        "operator": "range",
        "min": 25000,
        "max": 500000
      },
      "city": {
        "operator": "in",
        "values": ["Berlin", "München", "Hamburg"]
      }
    }
  }
}

Filter by Address

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company_meta_data": {
      "full_address": {
        "operator": "contains",
        "value": "Hauptstraße"
      }
    }
  }
}

Relationship Filters

Filter companies based on their relationships with other entities (people or companies).

Shareholders

Find companies where specific entities are shareholders.

Supported Fields

Field	Type	Description
`company_id`	String	Company acting as shareholder
`person_id`	String	Person acting as shareholder
`shareholder_type`	String	Type of shareholder
`percentage_share`	Number	Ownership percentage
`is_entitled`	Boolean	Entitled to benefits

Examples

Find Companies with Specific Company as Shareholder

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "shareholders": {
      "company_id": {
        "operator": "eq",
        "value": "2b902e97-266e-4415-9342-59e8aaf101fd"
      }
    }
  }
}

Find Companies with Specific Person as Shareholder

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "shareholders": {
      "person_id": {
        "operator": "eq",
        "value": "person-uuid-here"
      },
      "percentage_share": {
        "operator": "gte",
        "value": 25
      }
    }
  }
}

Representatives

Find companies where specific entities are representatives/management.

Supported Fields

Field	Type	Description
`company_id`	String	Company acting as representative
`person_id`	String	Person acting as representative

Examples

Find Companies with Specific Person as Representative

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "representatives": {
      "person_id": {
        "operator": "eq",
        "value": "person-uuid-here"
      }
    }
  }
}

Find Companies with Multiple Representatives

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "representatives": {
      "person_id": {
        "operator": "in",
        "values": ["person-1-uuid", "person-2-uuid", "person-3-uuid"]
      }
    }
  }
}

Limited Partners

Find companies where specific entities are limited partners.

Supported Fields

Field	Type	Description
`company_id`	String	Company acting as limited partner
`person_id`	String	Person acting as limited partner

Examples

Find Companies with Specific Company as Limited Partner

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "limited_partners": {
      "company_id": {
        "operator": "eq",
        "value": "2b902e97-266e-4415-9342-59e8aaf101fd"
      }
    }
  }
}

Find Companies with Specific Person as Limited Partner

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "limited_partners": {
      "person_id": {
        "operator": "eq",
        "value": "person-uuid-here"
      }
    }
  }
}

Prokura (Power of Attorney)

Find companies where specific persons have prokura rights.

Supported Fields

Field	Type	Description
`person_id`	String	Person with prokura rights

Only persons can have prokura rights, not companies.

Examples

Find Companies with Specific Person Having Prokura

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "prokura": {
      "person_id": {
        "operator": "eq",
        "value": "person-uuid-here"
      }
    }
  }
}

Combining Filters

You can combine filters across multiple entities for complex queries.

Example: Complex Multi-Entity Filter

Find active GmbH companies in Munich with share capital over €50,000 that have a specific person as shareholder:

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "legal_form": {
        "operator": "eq",
        "value": "GmbH"
      },
      "city": {
        "operator": "ilike",
        "value": "%münchen%"
      },
      "is_active": {
        "operator": "eq",
        "value": true
      }
    },
    "company_meta_data": {
      "share_capital": {
        "operator": "gte",
        "value": 50000
      }
    },
    "shareholders": {
      "person_id": {
        "operator": "eq",
        "value": "person-uuid-here"
      }
    }
  }
}

Example: Technology Companies with Management Filter

Find technology companies in Berlin with specific management:

{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company": {
      "city": {
        "operator": "eq",
        "value": "Berlin"
      },
      "is_active": {
        "operator": "eq",
        "value": true
      }
    },
    "company_meta_data": {
      "company_purpose": {
        "operator": "contains",
        "value": "Software"
      }
    },
    "representatives": {
      "person_id": {
        "operator": "in",
        "values": ["person-1-uuid", "person-2-uuid"]
      }
    }
  }
}

Error Handling

Validation Errors

The system validates all filters before execution. Common validation errors:

Unknown Entity

{
  "error": "ValidationError",
  "message": "Unknown entity: invalid_entity_name",
  "details": ["Available entities: company, company_meta_data, shareholders, representatives, limited_partners, prokura"]
}

Unknown Field

{
  "error": "ValidationError", 
  "message": "Field validation failed",
  "details": ["company.invalid_field: Field not supported for entity company"]
}

Invalid Operator

{
  "error": "ValidationError",
  "message": "Operator validation failed", 
  "details": ["company.legal_form: Operator 'invalid_op' not supported for string fields"]
}

Missing Required Parameters

{
  "error": "ValidationError",
  "message": "Parameter validation failed",
  "details": ["company.location: within_radius operator requires center_lat, center_lng, and radius_meters"]
}

Query Execution Errors

No Results Found

{
  "found": false,
  "message": "No companies found matching the criteria",
  "applied_filters": {
    "total_entities": 2,
    "total_filter_count": 4
  }
}

Advanced Usage

Performance Optimization

Use Specific Filters: More specific filters reduce result sets and improve performance
Limit Result Sets: Use appropriate limit values (max 100)
Geographic Filters: Use reasonable radius values for location searches
Index-Friendly Operators: eq and in operators perform better than like patterns

Best Practices

Efficient Filtering

// ✅ Good: Specific and efficient
{
  "filters": {
    "company": {
      "legal_form": {"operator": "eq", "value": "GmbH"},
      "register_court": {"operator": "eq", "value": "München"}
    }
  }
}

// ❌ Avoid: Too broad and slow
{
  "filters": {
    "company": {
      "name": {"operator": "like", "value": "%"}
    }
  }
}

Combining Geographic and Entity Filters

{
  "filters": {
    "company": {
      "location": {
        "operator": "within_radius",
        "center_lat": 48.1351,
        "center_lng": 11.5820,
        "radius_meters": 2000
      },
      "legal_form": {
        "operator": "in", 
        "values": ["GmbH", "UG"]
      }
    },
    "company_meta_data": {
      "share_capital": {
        "operator": "gte",
        "value": 25000
      }
    }
  }
}

Caching

Filter results are cached for 5 minutes
Cache keys include filter content, so different filters won’t interfere
Use consistent filter ordering for better cache hit rates

Complex filters with multiple relationship joins may impact performance. Monitor your query execution times and optimize filters as needed.

Filter Schema Reference

Complete Entity Schema

interface FilterSchema {
  company: {
    name: string[];           // String operators
    legal_form: string[];     // String operators  
    city: string[];           // String operators
    register_court: string[]; // String operators
    register_prefix: string[]; // String operators
    register_number: string[]; // Number operators
    is_active: string[];      // Boolean operators
    is_kg: string[];          // Boolean operators
    location: string[];       // Geographic operators
  };
  company_meta_data: {
    company_name: string[];   // String operators
    legal_form: string[];     // String operators
    headquarter: string[];    // String operators
    full_address: string[];   // String operators
    city: string[];           // String operators
    state: string[];          // String operators
    country: string[];        // String operators
    company_purpose: string[]; // String operators
    share_capital: string[];  // Number operators
  };
  shareholders: {
    company_id: string[];     // ["eq", "in"]
    person_id: string[];      // ["eq", "in"]
    shareholder_type: string[]; // String operators
    percentage_share: string[]; // Number operators
    is_entitled: string[];    // Boolean operators
  };
  representatives: {
    company_id: string[];     // ["eq", "in"]
    person_id: string[];      // ["eq", "in"]
  };
  limited_partners: {
    company_id: string[];     // ["eq", "in"]
    person_id: string[];      // ["eq", "in"]
  };
  prokura: {
    person_id: string[];      // ["eq", "in"]
  };
}

This comprehensive filtering system provides powerful capabilities for precise company data queries across all aspects of German company registry information.

​Overview

​How Filters Work

​Filter Architecture

​Filter Object Structure

​Filter Logic

​Available Operators

​Equality Operators

​Comparison Operators

​Pattern Matching

​List Operations

​Range Operations

​Geographic Operations

​Company Filters

​Supported Fields

​Examples

​Filter by Legal Form

​Filter by City and Active Status

​Geographic Search (Companies in Munich)

​Register Number Range

​Company Metadata Filters

​Supported Fields

​Examples

​Filter by Business Purpose

​Filter by Share Capital Range

​Filter by Address

​Relationship Filters

​Shareholders

​Supported Fields

​Examples

Find Companies with Specific Company as Shareholder

Find Companies with Specific Person as Shareholder

​Representatives

​Supported Fields

​Examples

Find Companies with Specific Person as Representative

Find Companies with Multiple Representatives

​Limited Partners

​Supported Fields

​Examples

Find Companies with Specific Company as Limited Partner

Find Companies with Specific Person as Limited Partner

​Prokura (Power of Attorney)

​Supported Fields

​Examples

Find Companies with Specific Person Having Prokura

​Combining Filters

​Example: Complex Multi-Entity Filter

​Example: Technology Companies with Management Filter

​Error Handling

​Validation Errors

​Unknown Entity

​Unknown Field

​Invalid Operator

​Missing Required Parameters

​Query Execution Errors

​No Results Found

​Advanced Usage

​Performance Optimization

​Best Practices

​Efficient Filtering

​Combining Geographic and Entity Filters

​Caching

​Filter Schema Reference

​Complete Entity Schema

Overview

How Filters Work

Filter Architecture

Filter Object Structure

Filter Logic

Available Operators

Equality Operators

Comparison Operators

Pattern Matching

List Operations

Range Operations

Geographic Operations

Company Filters

Supported Fields

Examples

Filter by Legal Form

Filter by City and Active Status

Geographic Search (Companies in Munich)

Register Number Range

Company Metadata Filters

Supported Fields

Examples

Filter by Business Purpose

Filter by Share Capital Range

Filter by Address

Relationship Filters

Shareholders

Supported Fields

Examples

Representatives

Supported Fields

Examples

Limited Partners

Supported Fields

Examples

Prokura (Power of Attorney)

Supported Fields

Examples

Combining Filters

Example: Complex Multi-Entity Filter

Example: Technology Companies with Management Filter

Error Handling

Validation Errors

Unknown Entity

Unknown Field

Invalid Operator

Missing Required Parameters

Query Execution Errors

No Results Found

Advanced Usage

Performance Optimization

Best Practices

Efficient Filtering

Combining Geographic and Entity Filters

Caching

Filter Schema Reference

Complete Entity Schema