# Neugründungen API — Full Reference

> REST API for newly registered German companies from the Handelsregister (German commercial register). ~500 new companies per day. Updated daily.

Base URL: https://handelsregister.callsync.de

## Overview

Every business day, approximately 500 new companies are registered in the German Handelsregister (commercial register). This API provides structured, machine-readable access to these registrations — company name, full address, legal form, directors, business purpose, registered capital, and whether a website was found.

Data source: Official new registrations list from handelsregister.de. Only genuine new company formations are included — relocations and transformations are automatically filtered out.

## Authentication

All requests require a Bearer token in the Authorization header:

```
Authorization: Bearer nrg_your_api_key
```

API keys have the prefix `nrg_` and a daily request limit. Rate limit information is included in every response via headers.

---

## Endpoint: GET /api/companies

Retrieve newly registered companies for a specific date or date range.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| date | string (YYYY-MM-DD) | No | yesterday | Publication date. Cannot be in the future. Mutually exclusive with date_from/date_to. |
| date_from | string (YYYY-MM-DD) | No | — | Start date for range queries. Max 31 days span. Mutually exclusive with date. |
| date_to | string (YYYY-MM-DD) | No | today | End date for range queries. Mutually exclusive with date. |
| state | string | No | — | Federal state code. Valid: bw, by, be, br, hb, hh, he, mv, ni, nw, rp, sl, sn, st, sh, th |
| city | string | No | — | City filter, case-insensitive substring match. Example: "München" |
| legal_form | string | No | — | Legal form filter, case-insensitive substring. Examples: "GmbH", "UG", "AG", "OHG", "KG" |
| register_type | string | No | — | Register type: "HRA" (partnerships like OHG, KG) or "HRB" (corporations like GmbH, UG, AG) |
| search | string | No | — | Company name search, case-insensitive substring match. Example: "Tech" |
| has_website | string | No | — | "true" = only companies with website, "false" = only without. Useful for web agencies. |
| sort | string | No | name | Sort field. Prefix with "-" for descending. Valid: name, -name, city, -city, founding_date, -founding_date, register_type, -register_type, state, -state |
| limit | integer | No | 100 | Page size (1-500) |
| offset | integer | No | 0 | Pagination offset |
| format | string | No | json | Output format: "json" or "csv". CSV uses semicolons and UTF-8 BOM for German Excel. |
| fields | string | No | all | Comma-separated field names to return. Example: "name,address,city,has_website" |

### Response (JSON)

```json
{
  "date": "2026-03-24",
  "total": 488,
  "count": 100,
  "limit": 100,
  "offset": 0,
  "has_more": true,
  "companies": [
    {
      "name": "TechBau Solutions GmbH",
      "court": "München",
      "register_type": "HRB",
      "register_number": "123456",
      "legal_form": "Gesellschaft mit beschränkter Haftung",
      "address": "Musterstraße 12",
      "postal_code": "80331",
      "city": "München",
      "state": "by",
      "capital": "25.000,00 EUR",
      "purpose": "Entwicklung und Vertrieb von Software",
      "directors": "Geschäftsführer: Mustermann, Max, München, einzelvertretungsberechtigt",
      "founding_date": "2026-03-15",
      "has_website": false,
      "register_id": "NE:HRB-123456-München"
    }
  ]
}
```

For date range queries, the response contains `date_from` and `date_to` instead of `date`.

### Company Fields

| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| name | string | No | Full company name including legal form suffix |
| court | string | No | Register court (Amtsgericht) where the company is registered |
| register_type | string | No | "HRA" (partnerships) or "HRB" (corporations) |
| register_number | string | No | Registration number at the court |
| legal_form | string | No | Full German legal form name (e.g. "Gesellschaft mit beschränkter Haftung") |
| address | string | Yes | Street address of the registered office |
| postal_code | string | Yes | 5-digit German postal code (PLZ) |
| city | string | Yes | City of the registered office |
| state | string | Yes | Federal state code (2 letters): bw, by, be, br, hb, hh, he, mv, ni, nw, rp, sl, sn, st, sh, th |
| capital | string | Yes | Registered capital, e.g. "25.000,00 EUR" (German number format) |
| purpose | string | Yes | Business purpose / Unternehmensgegenstand — description of business activities |
| directors | string | Yes | Directors / Geschäftsführer — raw text from Handelsregister |
| founding_date | string | Yes | Founding date from articles of association, format YYYY-MM-DD |
| has_website | boolean | No | Whether a website was found for this company (true/false) |
| register_id | string | No | Unique identifier, format: NE:TYPE-NUMBER-COURT (e.g. NE:HRB-123456-München) |

### Pagination

When `has_more` is true, increment `offset` by `limit` to get the next page:

```
# Page 1
GET /api/companies?date=2026-03-24&limit=100&offset=0

# Page 2
GET /api/companies?date=2026-03-24&limit=100&offset=100

# Page 3
GET /api/companies?date=2026-03-24&limit=100&offset=200
```

Continue until `has_more` is false or `count` is 0.

---

## Endpoint: GET /api/stats

Returns available dates with company counts. Use this to discover which dates have data before querying /api/companies.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| state | string | No | — | Federal state code to filter stats by |

### Response

```json
{
  "total_dates": 14,
  "total_companies": 6944,
  "latest_date": "2026-03-24",
  "earliest_date": "2026-03-10",
  "dates": [
    { "date": "2026-03-24", "count": 488 },
    { "date": "2026-03-21", "count": 512 },
    { "date": "2026-03-20", "count": 475 }
  ]
}
```

### Recommended Agent Workflow

1. Call GET /api/stats to discover available dates
2. Use `latest_date` from stats response as the `date` parameter
3. Call GET /api/companies with desired filters
4. Paginate through results using `offset` until `has_more` is false

---

## Error Handling

| Status | Error | Description |
|--------|-------|-------------|
| 400 | "Invalid date format. Use YYYY-MM-DD" | Date parameter not in YYYY-MM-DD format |
| 400 | "Date cannot be in the future. Today is YYYY-MM-DD" | Requested date is after today |
| 400 | "Cannot use 'date' together with 'date_from'/'date_to'" | Mixed single and range date params |
| 400 | "Date range cannot exceed 31 days" | date_from to date_to span > 31 days |
| 400 | "Invalid state code 'xx'. Valid: bw, by, ..." | Unknown state code |
| 400 | "register_type must be 'HRA' or 'HRB'" | Invalid register type |
| 400 | "Invalid sort field '...'" | Unknown sort field |
| 400 | "Invalid field(s): ..." | Unknown field in fields parameter |
| 401 | "Invalid or missing API key" | No or wrong Authorization header |
| 404 | "No data available for this date" | No registrations on this date (weekends/holidays) |
| 429 | "Daily request limit exceeded" | Rate limit hit, resets at midnight CET |

---

## Rate Limiting

Every response includes these headers:

| Header | Description | Example |
|--------|-------------|---------|
| X-RateLimit-Limit | Daily request limit | 100 |
| X-RateLimit-Remaining | Requests left today | 87 |
| X-RateLimit-Reset | Next reset time (ISO 8601, CET midnight) | 2026-03-25T00:00:00+01:00 |

The limit resets every day at midnight CET (Central European Time).

---

## Code Examples

### Python

```python
import requests

API_KEY = "nrg_your_api_key"
BASE = "https://handelsregister.callsync.de"

# Get today's stats
stats = requests.get(f"{BASE}/api/stats", headers={"Authorization": f"Bearer {API_KEY}"}).json()
latest = stats["latest_date"]

# Fetch companies for the latest date
resp = requests.get(f"{BASE}/api/companies", headers={"Authorization": f"Bearer {API_KEY}"}, params={
    "date": latest,
    "register_type": "HRB",
    "has_website": "false",
    "sort": "-founding_date",
    "limit": 100
})
data = resp.json()

for company in data["companies"]:
    print(f"{company['name']} | {company['city']} | {company['purpose']}")

# Paginate if needed
while data["has_more"]:
    resp = requests.get(f"{BASE}/api/companies", headers={"Authorization": f"Bearer {API_KEY}"}, params={
        "date": latest,
        "register_type": "HRB",
        "has_website": "false",
        "sort": "-founding_date",
        "limit": 100,
        "offset": data["offset"] + data["limit"]
    })
    data = resp.json()
    for company in data["companies"]:
        print(f"{company['name']} | {company['city']}")
```

### JavaScript (Node.js / fetch)

```javascript
const API_KEY = "nrg_your_api_key";
const BASE = "https://handelsregister.callsync.de";
const headers = { Authorization: `Bearer ${API_KEY}` };

// Discover latest date
const stats = await fetch(`${BASE}/api/stats`, { headers }).then(r => r.json());
const latestDate = stats.latest_date;

// Fetch all companies (with pagination)
let allCompanies = [];
let offset = 0;
let hasMore = true;

while (hasMore) {
  const url = `${BASE}/api/companies?date=${latestDate}&limit=500&offset=${offset}`;
  const data = await fetch(url, { headers }).then(r => r.json());
  allCompanies.push(...data.companies);
  hasMore = data.has_more;
  offset += data.limit;
}

console.log(`Found ${allCompanies.length} companies`);
```

### curl

```bash
# Single date
curl "https://handelsregister.callsync.de/api/companies?date=2026-03-24&state=by" \
  -H "Authorization: Bearer nrg_your_api_key"

# Date range
curl "https://handelsregister.callsync.de/api/companies?date_from=2026-03-17&date_to=2026-03-24&legal_form=GmbH" \
  -H "Authorization: Bearer nrg_your_api_key"

# CSV export
curl "https://handelsregister.callsync.de/api/companies?date=2026-03-24&format=csv" \
  -H "Authorization: Bearer nrg_your_api_key" \
  -o companies.csv

# Name search
curl "https://handelsregister.callsync.de/api/companies?date=2026-03-24&search=Solar&fields=name,city,purpose" \
  -H "Authorization: Bearer nrg_your_api_key"
```

---

## Federal State Codes

| Code | State | Code | State |
|------|-------|------|-------|
| bw | Baden-Württemberg | ni | Niedersachsen |
| by | Bayern | nw | Nordrhein-Westfalen |
| be | Berlin | rp | Rheinland-Pfalz |
| br | Brandenburg | sl | Saarland |
| hb | Bremen | sn | Sachsen |
| hh | Hamburg | st | Sachsen-Anhalt |
| he | Hessen | sh | Schleswig-Holstein |
| mv | Mecklenburg-Vorpommern | th | Thüringen |

---

## Machine-Readable Resources

- OpenAPI 3.0 Spec: https://handelsregister.callsync.de/openapi.json
- This file: https://handelsregister.callsync.de/llms-full.txt
- Short overview: https://handelsregister.callsync.de/llms.txt
- AI Plugin Manifest: https://handelsregister.callsync.de/.well-known/ai-plugin.json