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
• 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,
      "message": "In dem Insolvenzverfahren über das Vermögen der Musterhandel GmbH, Beispielstraße 1, 12345 Musterstadt, 
                  vertreten durch die Geschäftsführerin Maxima Beispiel Registergericht: Amtsgericht Musterstadt Register-Nr.: HRB 123456 – Schuldnerin –
                  Das Insolvenzverfahren wird nach Abhalten des Schlusstermins im schriftlichen Verfahren 
                  und Vollzug der Schlussverteilung a u f g e h o b e n . Rechtsbehelfsbelehrung..... "
    }
  ],
  "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
  • Standard: 25
  • Business: 100
  • Expert: 100

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.

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" - Hourly rate limit reached

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.

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: Search with wildcard and field selection ---
$query = http_build_query([
    'name' => 'Galeria*',
    'fields' => 'veroeffentlicht,name,register, administrator'
]);

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

var_dump($data);

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()}")