Our search endpoint offers a flexible and powerful way to find specific companies. This guide explains the various filtering options available.

​
Basic Structure

The core of the filtering mechanism is the filters array in the request body. Each object in this array represents a single filter condition and must contain a field and a corresponding value using one of the available filter types. 
{
  "filters": [
    {
      "field": "status",
      "value": "active"
    }
  ]
}

​
Free-Text Search Query

Besides structured filters, you can also perform a free-text search using the query field. This is useful for finding companies by name or previous names. 
{
  "query": {
    "value": "Descartes"
  },
  "filters": [
    {
      "field": "city",
      "value": "Berlin"
    }
  ]
}
This will search for companies with “Descartes” in their name or previous names and are located in Berlin.

​
Examples

Here are a few examples of how you can combine different filters to achieve specific search results.

​
All Restaurants

To find all companies in the restaurant industry, you can filter by the industry_codes field. 
{
  "filters": [
    {
      "field": "industry_codes",
      "value": "56.11" 
    }
  ]
}

​
Newly Founded Companies

To find companies that were incorporated in the last week, you can use a range filter on the incorporated_at field. 
{
  "filters": [
    {
      "field": "incorporated_at",
      "min": "15-07-2024"
    }
  ]
}

​
High-Revenue Companies with a Large Workforce

To find companies with more than 100 employees and over 100 million in revenue, you can combine two range filters. 
{
  "filters": [
    {
      "field": "employees",
      "min": "100"
    },
    {
      "field": "revenue",
      "min": "100000000"
    }
  ]
}

​
Companies in a Specific Location

To find all companies with a registered address in a specific postal code. 
{
  "filters": [
    {
      "field": "zip",
      "value": "10117"
    }
  ]
}
To find all GmbH companies with a capital of more than 1 million EUR. 
{
  "filters": [
    {
      "field": "legal_form",
      "value": "gmbh"
    },
    {
      "field": "capital_amount",
      "min": "1000000"
    },
    {
      "field": "capital_currency",
      "value": "EUR"
    }
  ]
}

​
Filterable Fields

You can filter on a wide range of fields. Here is a list of all available fields:
FieldDescription
statusThe current status of the company (e.g., active, inactive, liquidation).
legal_formThe legal form of the company (e.g., gmbh, ag).
register_numberThe company’s registration number.
register_courtThe court where the company is registered.
register_typeThe type of register (e.g., HRB, HRA).
cityThe city where the company is located.
activeA boolean indicating if the company is active.
incorporated_atThe date of incorporation.
zipThe postal code of the company’s address.
addressThe full address of the company.
balance_sheet_totalThe total of the balance sheet.
revenueThe company’s revenue.
cashThe company’s cash reserves.
employeesThe number of employees.
equityThe company’s equity.
real_estateThe value of the company’s real estate.
materialsThe value of the company’s materials.
pension_provisionsThe company’s pension provisions.
salariesThe company’s salary expenses.
taxesThe company’s tax expenses.
liabilitiesThe company’s liabilities.
capital_reservesThe company’s capital reserves.
net_incomeThe company’s net income.
industry_codesThe company’s industry codes (WZ2025).
capital_amountThe amount of the company’s capital.
capital_currencyThe currency of the company’s capital.

​
Filter Types

There are several ways to specify the filter value, depending on the desired comparison.

​
Exact Match: value

For a simple exact match, use the value property. 
{
  "field": "legal_form",
  "value": "gmbh"
}

​
Multiple Values: values

To match against a list of possible values, use the values array. This is useful for “OR” conditions. 
{
  "field": "city",
  "values": ["Berlin", "Hamburg", "München"]
}

​
Keyword Matching: keywords

For text fields, keywords allows you to find records containing any of the specified words. 
{
  "field": "zip",
  "keywords": ["10117", "10119"]
}

​
Range Filtering: min and max

For numerical and date fields, you can specify a range using min and max. 
{
  "field": "employees",
  "min": "10",
  "max": "100"
}
You can also specify just a minimum or a maximum. 
{
  "field": "revenue",
  "min": "1000000"
}

​
Date Formatting

When filtering by date, use the DD-MM-YYYY format. 
{
  "field": "incorporated_at",
  "min": "01-01-2020",
  "max": "31-12-2021"
}

​
Location Filtering

You can also filter companies based on their geographical location by providing a location object in the request body. This allows you to find companies within a certain radius of a given point. The location object requires latitude and longitude, and optionally accepts a radius in kilometers. 
{
  "location": {
    "latitude": 52.5200,
    "longitude": 13.4050,
    "radius": 10
  }
}

​
Combining Filters

You can combine multiple filter objects in the filters array. These conditions are joined with an “AND” operator, meaning a company must satisfy all of them to be included in the results. 
{
  "filters": [
    {
      "field": "legal_form",
      "value": "gmbh"
    },
    {
      "field": "employees",
      "min": "50"
    }
  ]
}