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",
      "message": "Eröffnung des Insolvenzverfahrens",
      "firstname": "Max",
      "lastname": "Mustermann",
      "birthday": "1980-05-15",
      "reg_number": "HRB 266691",
      "reg_type": "HRB",
      "reg_number_number": 266691,
      "verwalter": "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"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1500
  }
}

Search Parameters Details

Full-Text Search

The q parameter performs a full-text search across the following fields:

• name - Company name
• sitz - Company location
• message - Insolvency message
• verwalter - Administrator name
• firstname - First name
• lastname - Last name
• register - Register information
• company_purpose - Company purpose (Unternehmensgegenstand)

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
• "Not found" - Entry with specified ID not found
• "Rate limiter error" - Internal rate limiting error

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

JavaScript Example

// Search for entries with field selection
fetch('https://api.insolvenz-radar.de/v1/entries/search?q=GmbH&fields=name,firstname,lastname,birthday', {
    headers: {
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    }
})
.then(response => response.json())
.then(data => {
    console.log('Found entries:', data.data);
    console.log('Total:', data.meta.total);
})
.catch(error => {
    console.error('Error:', error);
});

// Wildcard search example
fetch('https://api.insolvenz-radar.de/v1/entries/search?lastname=*müller*&firstname=*a*', {
    headers: {
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    }
})
.then(response => response.json())
.then(data => {
    console.log('Wildcard search results:', data.data);
});

Python Example

import requests

# Search with field selection
response = requests.get(
    'https://api.insolvenz-radar.de/v1/entries/search',
    params={
        'q': 'GmbH',
        '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()}")