Insolvenz-Radar API Documentation

Overview

The Insolvenz-Radar API provides access to insolvency data with comprehensive search capabilities, authentication, and rate limiting. The API follows RESTful principles.

Features

• RESTful API design
• API Key authentication
• Rate limiting per company
• Comprehensive search functionality
• Field selection for optimized responses
• Wildcard search support
• Pagination support
• Company financial metrics
• CORS enabled
• JSON responses

Authentication

All API requests require authentication using an API key. The API key must be included in the request headers.

Get your API Key

Header Format

Authentication Flow

1. Include your API key in the X-API-Key header
2. If valid, the request proceeds; if invalid, returns 401 Unauthorized

Rate Limiting

The API implements rate limiting on a per account basis with daily windows. Rate limits depend on your plan.

Rate Limit Headers

Rate Limit Behavior

• Rate limits reset every day
• When rate limit is exceeded, API returns 429 Too Many Requests

Endpoints

{
  "ok": true
}

{
  "data": [
    {
      "veroeffentlicht": "2024-01-15T10:30:00+00:00",
      "az": "AZ 123/24",
      "gericht": "Amtsgericht München",
      "name": "Example GmbH",
      "sitz": "München",
      "register": "München, HRB 266691",
      "type": "eroeffnung",
      "firstname": "Max",
      "lastname": "Mustermann",
      "birthday": "1980-05-15",
      "reg_number": "HRB 266691",
      "reg_type": "HRB",
      "reg_number_number": 266691,
      "administrator": {
        "name": "Rechtsanwalt Niklas Lütcke",
        "street": "Lennéstraße 7",
        "zip": "10785",
        "city": "Berlin",
        "office": "Kanzlei Mitte",
        "phone": "+49 30 1234567",
        "fax": "+49 30 1234568",
        "email": "kanzlei@beispiel.de",
        "url": "https://www.beispiel-kanzlei.de"
      },
      "debtor_address_street": "Hauptstraße",
      "debtor_address_housenumber": "123",
      "debtor_address_postcode": "80331",
      "debtor_address_city": "München",
      "company_purpose": "Handel mit Waren aller Art",
      "discharged": false,
      "discharge_date": null,
      "company_metrics": [
        { "type": "revenue", "year": 2021, "value": 4200000 },
        { "type": "revenue", "year": 2022, "value": 3800000 },
        { "type": "balance", "year": 2022, "value": 1200000 },
        { "type": "employees", "year": 2022, "value": 38 }
      ],
      "message": "In dem Insolvenzverfahren über das Vermögen der Musterhandel GmbH ..."
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1500
  }
}

Search Parameters Details

Wildcard Search

Most string parameters support wildcard search using the * character:

• name=*GmbH* - Find companies with "GmbH" in the name
• firstname=*i*m* - Find first names containing "i" and "m"
• lastname=Meyer - Exact match (no wildcards)
• debtor_address_street=*Hauptstraße* - Find debtors on streets containing "Hauptstraße"
• debtor_address_city=*München* - Find debtors in cities containing "München"
• debtor_address_postcode=144* - Find debtors with postal codes starting with "144"
• company_purpose=*Software* - Find companies with "Software" in their purpose
• industry=*Pharma* - Find entries with industry names containing "Pharma"

Industry Values

The industry parameter accepts the following values (exact match or wildcard search with *):

Entry Types

The type parameter accepts specific values for different insolvency procedures and decisions:

Note: Type values are case-sensitive.

Date Filtering

Date parameters accept YYYY-MM-DD format:

• veroeffentlicht_from / veroeffentlicht_to – Publication date range (00:00:00 to 23:59:59)
• discharge_date_from / discharge_date_to – Discharge date range (available from the Business plan)

Pagination

Pagination is handled via page and per_page parameters:

• Page numbers start at 1
• Items per page:
  • The maximum number of items per page is determined by your pricing plan:
  • Free: 3 (7 days test phase)
  • Light: 3
  • Standard: 25
  • Business: 100
  • Expert: 100

Company Metrics Business

Where available, the API can return historical financial and operational metrics for insolvent companies — such as revenue, earnings, balance sheet totals, and employee counts sourced from public filings. This feature is available from the Business plan.

How it works

1. Add metrics_type to your request to enable metrics (e.g. metrics_type=revenue).
2. Optionally narrow the value range with metrics_min and/or metrics_max — only entries matching the range are returned.
3. Optionally pin to a specific year with metrics_year. If omitted, the most recent year available per entry is used for filtering.
4. Add company_metrics to the fields parameter (or omit fields entirely) to receive all available metric types and years for each matched entry in the response.

Metric Types

Response structure

When company_metrics is included in the response, each entry contains an array of metric objects:

"company_metrics": [
  { "type": "revenue",   "year": 2021, "value": 4200000 },
  { "type": "revenue",   "year": 2022, "value": 3800000 },
  { "type": "balance",   "year": 2022, "value": 1200000 },
  { "type": "employees", "year": 2022, "value": 38 }
]

Values are integers (euros for financial metrics, headcount for employees). The array is ordered by type, then year ascending.

Examples

Field Selection

Use the fields parameter to specify which fields to return in the response. This can significantly reduce response size and improve performance.

Available Fields

Usage Examples

Returns only company name, first name, last name, and birthday fields.

Returns only publication date, court, and type fields.

Returns name, location, and all available financial metrics for each entry.

Response Format

Success Responses

All successful responses return JSON with UTF-8 encoding and include appropriate headers.

Data Fields

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "Error message description"
}

Common Error Messages

• "Missing X-API-Key" - API key header not provided
• "Invalid API key" - API key not found in database
• "Rate limit exceeded" - Daily rate limit reached
• "Filtering by company metrics is available from Business plan." - metrics_* parameters used on a lower plan
• "Invalid parameter metrics_type. Allowed values: earnings, revenue, balance, employees." - unknown metric type
• "Invalid parameter metrics_min. Expected non-negative integer." - non-numeric value for metrics_min or metrics_max
• "Invalid parameter metrics_year. Expected a valid year (e.g. 2023)." - invalid year value

Examples

Basic Search

Wildcard Search

Date Range Search

Field Selection

Filter by Court and Type

Complex Search with Multiple Filters

Debtor Address Search

Filter by discharge status and date

Request discharged and discharge_date in fields; filter with discharged, discharge_date_from, and discharge_date_to. Available from the Business plan.

Filter by company metrics

Use metrics_type together with metrics_min/metrics_max to filter by financial figures. Add company_metrics to fields to receive all available metrics in the response. Available from the Business plan.

Health Check

PHP Example

// Your API key
$apiKey = 'your-api-key';

// Base URL
$baseUrl = 'https://api.insolvenz-radar.de/v1/entries/search';

// Helper function to perform the API request with curl
function callApi($url, $apiKey) {
    $ch = curl_init();

    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'Content-Type: application/json'
        ],
        CURLOPT_TIMEOUT => 30,
    ]);

    $response = curl_exec($ch);
    $error = curl_error($ch);
    curl_close($ch);

    if ($error) {
        echo "cURL error: $error\n";
        return null;
    }

    $data = json_decode($response, true);
    return $data;
}

// --- Example: Filter by revenue and return all metrics ---
$query = http_build_query([
    'name'         => '*GmbH*',
    'metrics_type' => 'revenue',
    'metrics_min'  => '1000000',
    'fields'       => 'name,sitz,company_metrics',
    'per_page'     => '25',
]);

$data = callApi("$baseUrl?$query", $apiKey);

foreach ($data['data'] as $entry) {
    echo $entry['name'] . "\n";
    foreach ($entry['company_metrics'] as $metric) {
        echo "  {$metric['type']} {$metric['year']}: {$metric['value']}\n";
    }
}

Python Example

import requests

# Search with field selection
response = requests.get(
    'https://api.insolvenz-radar.de/v1/entries/search',
    params={
        'name': 'GALERIA%20Karstadt%20Kaufhof%20GmbH',
        'fields': 'name,firstname,lastname,birthday',
        'page': 1,
        'per_page': 10
    },
    headers={'X-API-Key': 'your-api-key'}
)

if response.status_code == 200:
    data = response.json()
    print(f"Found {data['meta']['total']} entries")
    for entry in data['data']:
        print(f"Name: {entry['name']}, Person: {entry['firstname']} {entry['lastname']}")
else:
    print(f"Error: {response.status_code} - {response.json()}")


# Search with company metrics filter
response = requests.get(
    'https://api.insolvenz-radar.de/v1/entries/search',
    params={
        'name': '*GmbH*',
        'metrics_type': 'revenue',
        'metrics_min': 1000000,
        'fields': 'name,sitz,company_metrics',
        'per_page': 25,
    },
    headers={'X-API-Key': 'your-api-key'}
)

if response.status_code == 200:
    data = response.json()
    for entry in data['data']:
        print(entry['name'])
        for m in entry['company_metrics']:
            print(f"  {m['type']} {m['year']}: {m['value']}")
else:
    print(f"Error: {response.status_code} - {response.json()}")