> ## 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 Options Reference

> Complete reference for the optional filter options used in API requests to filter German company data across multiple entities.

## 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.

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

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

<Note>
  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."
</Note>

## 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:

```json theme={null}
{
  "offset": 0,
  "limit": 50,
  "filters": {
    "entity_name": {
      "field_name": {
        "operator": "operator_type",
        "value": "filter_value"
      }
    }
  }
}
```

**Example API Request:**

```json theme={null}
{
  "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

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

#### Filter by City and Active Status

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

#### Geographic Search (Companies in Munich)

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

#### Register Number Range

```json theme={null}
{
  "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

```json theme={null}
{
  "offset": 0,
  "limit": 50,
  "filters": {
    "company_meta_data": {
      "company_purpose": {
        "operator": "contains",
        "value": "Software"
      }
    }
  }
}
```

#### Filter by Share Capital Range

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

##### Find Companies with Specific Person as Shareholder

```json theme={null}
{
  "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

```json theme={null}
{
  "offset": 0,
  "limit": 50,
  "filters": {
    "representatives": {
      "person_id": {
        "operator": "eq",
        "value": "person-uuid-here"
      }
    }
  }
}
```

##### Find Companies with Multiple Representatives

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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 |

<Note>
  Only persons can have prokura rights, not companies.
</Note>

#### Examples

##### Find Companies with Specific Person Having Prokura

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

#### Unknown Field

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

#### Invalid Operator

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

#### Missing Required Parameters

```json theme={null}
{
  "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

```json theme={null}
{
  "found": false,
  "message": "No companies found matching the criteria",
  "applied_filters": {
    "total_entities": 2,
    "total_filter_count": 4
  }
}
```

## Advanced Usage

### Performance Optimization

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

### Best Practices

#### Efficient Filtering

```json theme={null}
// ✅ 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

```json theme={null}
{
  "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

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

## Filter Schema Reference

### Complete Entity Schema

```typescript theme={null}
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.