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 hourly windows. Rate limits depend on your plan.

Rate Limit Headers

Rate Limit Behavior

• Rate limits reset every hour
• 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": "Dr. Max Mustermann",
      "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",
      "administrator": "Dr. Max Mustermann, Musterstraße 123, 80331 München, +49 123 4567890, max.mustermann@example.com, https://www.example.com"
    }
  ],
  "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

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 and are automatically converted to full datetime ranges:

• veroeffentlicht_from - From 00:00:00 of the specified date
• veroeffentlicht_to - To 23:59:59 of the specified date

Pagination

Pagination is handled via page and per_page parameters:

• Page numbers start at 1
• Maximum 100 items per page
• Default: 25 items per page

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

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