Filtering

POST /search/companies/filter answers a structured question — "GmbHs in Bavaria, founded since 2025, with a managing director over 60" — rather than a text query. It costs 25 credits a page.

Shape

{
  "company": { "…": "criteria on the register entry itself" },
  "financials": { "…": "criteria on the most recent statement" },
  "officers": { "conditions": [] },
  "shareholders": { "conditions": [] },
  "limit": 20
}

Four groups, and at least one is required — an empty filter is a 400, not the whole register. Everything you give must hold: the groups combine with AND, and so do the fields inside company and financials.

Criteria on the company

{
  "company": {
    "status": ["active"],
    "legal_form_code": ["gmbh", "gmbh_co_kg"],
    "city": { "equals": "Berlin" },
    "incorporation_date": { "gte": "2025-01-01" },
    "capital_amount": { "gte": 25000, "lte": 100000 }
  },
  "limit": 20
}

Three kinds of value, and which one a field takes is fixed:

near is its own thing: {"latitude": 48.13, "longitude": 11.58, "radius_meters": 5000}.

Criteria on officers and shareholders

These take conditions, because a company has many of each and it matters whether one officer satisfies the whole condition or three officers satisfy a third of it each.

{
  "officers": {
    "match": "all",
    "conditions": [
      { "role": ["managing_director"], "age": { "gte": 60 } }
    ]
  },
  "limit": 20
}

Every field inside one condition must match the same officer. The example finds companies with a managing director over 60 — not companies with a managing director and, separately, somebody over 60.

match says how several conditions combine: all (the default) requires each condition to be met by some officer, any requires one of them. min_matching and max_matching count how many officers must meet a condition — max_matching: 1 finds companies with a single signatory.

shareholders works the same way, with interest, owner_type, percentage, held_since, tenure_years and is_current. Filtering interest: ["limited_partner"] selects Kommanditisten.

When a filter cannot be expressed

Some questions have no honest translation, and those return 400 with a problem document saying so rather than a result that quietly means something else:

• status other than active or terminated. The underlying data records whether a company is active, not which of four states it is in. A liquidation filter would return every inactive company, which is not what you asked.
• legal_form_code: ["foreign_entity"]. Foreign forms are written 1,281 different ways in the register, so there is no set of spellings to match on.

A filter that silently widened would be worse than one that refuses: you would build a segment on it and never know.

Paging

limit and the next_page token page the result set — see Pagination. Each call costs 25 credits regardless of how many results come back, so prefer a larger limit over many small pages.