Firmenatlas API-Dokumentation

Erstelle oder rotiere deinen Key in der Accountverwaltung. Der vollständige Key wird nur einmal angezeigt. Trage ihn in Swagger unter Authorize ohne das Wort Bearer ein; in eigenen Requests wird er als Bearer-Token gesendet.

export FIRMENATLAS_API_KEY="fa_api_DEIN_VOLLSTAENDIGER_KEY"

curl "https://api.firmenatlas.com/v1/companies?query=Firmenatlas&limit=10" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY"

Eine erfolgreiche Antwort enthält die Nutzdaten unter data und technische Metadaten unter meta. Alle erfolgreichen V1-Endpunkte liefern HTTP 200, auch POST-Operationen.

{
  "data": {
    "unternehmen": [
      {
        "firmenbuchnummer": "123456a",
        "name": "Beispiel GmbH",
        "sitz": "Wien",
        "rechtsform": "Gesellschaft mit beschränkter Haftung",
        "status": "Aktiv"
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "generatedAt": "2026-08-19T10:15:30.000Z",
    "limit": 10,
    "nextCursor": null,
    "hasMore": false
  }
}

Basis-URL

https://api.firmenatlas.com

IDs und Schlüssel

Pagination

Bei der ersten Anfrage lässt du cursor weg. Wenn meta.hasMore den Wert true hat, übergibst du meta.nextCursor unverändert an die nächste Anfrage. Der Cursor darf nicht interpretiert oder verändert werden.

GET /v1/companies?query=Beispiel&limit=10
GET /v1/companies?query=Beispiel&limit=10&cursor=eyJvZmZzZXQiOjEwfQ

Alle Endpunkte

Die einfache Suche ist für Namens- und Firmenbuchnummern-Lookups gedacht. Sie liefert kompakte Treffer, aber noch kein vollständiges Unternehmensprofil, und zählt nicht zum Monatskontingent.

Lädt Registerdaten, die letzten Finanzkennzahlen und kompakte Beziehungskennzahlen. Vollständige Abschlüsse und Eigentümerdaten haben eigene Endpunkte.

curl "https://api.firmenatlas.com/v1/companies/123456a" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY"

curl "https://api.firmenatlas.com/v1/companies/123456a/financial-statements?years=2025,2024&limit=2" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY"

verfuegbareGeschaeftsjahre nennt alle bekannten Jahre; ausgelieferteGeschaeftsjahre die aktuelle Antwort und fehlendeGeschaeftsjahre explizit angeforderte Jahre ohne Daten. Jeder Abschluss enthält Währung, Bilanz, Gewinn- und Verlustrechnung, Kennzahlen, Mitarbeiterwerte und Quelle.

Der Download besteht bewusst aus zwei Schritten: zuerst den Dokument-Key finden, danach einen kurzlebigen signierten Link erzeugen.

# 1. Dokumente auflisten
curl "https://api.firmenatlas.com/v1/companies/123456a/documents?limit=20" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY"

# 2. dokumentKey aus der Antwort URL-encodiert einsetzen
curl -X POST "https://api.firmenatlas.com/v1/documents/DOKUMENT_KEY/download-link" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY"

Verwende diesen Endpunkt für Filterkombinationen, ausgewählte Ergebnisfelder und Sortierung. Die gültigen öffentlichen Feldpfade kommen aus GET /v1/company-search/fields. Verfügbare Kategorien und Verteilungen liefert POST /v1/company-search/facets.

curl -X POST "https://api.firmenatlas.com/v1/companies/search" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "rechtsformen": ["Gesellschaft mit beschränkter Haftung"],
      "bundeslaender": ["Wien"],
      "bilanzsumme": { "min": 1000000 }
    },
    "fields": [
      "firmenbuchnummer",
      "name",
      "letztesGeschaeftsjahr.bilanzsumme"
    ],
    "sort": {
      "field": "letztesGeschaeftsjahr.bilanzsumme",
      "order": "desc"
    },
    "page": 1,
    "pageSize": 50
  }'

Eine Kante zeigt immer vom Eigentümer zum Beteiligungsziel. Der Wurzelknoten hat Tiefe 0. Personen werden nicht rekursiv expandiert; eindeutig identifizierte Unternehmen schon. Zyklen werden gemeldet und nicht weiterverfolgt.

GET /v1/people?query=Max%20Mustermann&birthYear=1975&limit=10

Die Suche liefert eine personId. Verwende genau diese ID anschließend für Profil und Netzwerk. Sie ist eine undurchsichtige Routenreferenz und keine dauerhaft garantierte Stammdaten-ID. Eine Personenreferenz aus einem Unternehmensprofil kann anders aufgebaut sein und soll nicht allein anhand der ID mit Suchtreffern dedupliziert werden.

Das Profil enthält Name, Geburtsdaten soweit verfügbar, Aliasnamen, Funktionen, persönliche Beteiligungen, verbundene Unternehmen und exakte Kennzahlen. Mit status=all werden auch historische Beziehungen geliefert. Die Pagination begrenzt nur die ausgelieferte Funktionsliste; Kennzahlen, verbundene Unternehmen, verbundene Personen und der Personengraph bleiben unabhängig von limit und cursor.

Das Netzwerk beginnt bei der Person, ergänzt direkt verbundene Unternehmen und dort verbundene Personen. Weitere Personen werden innerhalb derselben Antwort nicht rekursiv expandiert. Für weitere Tiefe rufst du deren personId als neue Wurzel auf.

Listen gehören dem Account und stehen damit allen entsprechend berechtigten Account-Nutzern zur Verfügung. Der typische Ablauf ist: Listen abrufen oder anlegen, Unternehmen hinzufügen, Liste mit Einträgen laden.

# Liste anlegen
curl -X POST "https://api.firmenatlas.com/v1/lists" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Wiener Zielkunden" }'

# Unternehmen hinzufügen
curl -X POST "https://api.firmenatlas.com/v1/lists/LISTEN_ID/items" \
  -H "Authorization: Bearer $FIRMENATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firmenbuchnummer": "123456a",
    "kommentar": "Im nächsten Quartal kontaktieren"
  }'

REST und MCP teilen das monatliche Account-Kontingent. api_access steuert nur die REST-API-Key-Freischaltung; MCP bleibt unabhängig davon per OAuth erreichbar und seine erfolgreichen Tool-Aufrufe werden trotzdem erfasst. Einfache Firmen- und Personensuchen sowie Lookup-Metadaten zählen nicht. Erweiterte Suchen und erfolgreiche Datenabrufe zählen grundsätzlich einmal. Fehlgeschlagene Aufrufe werden nicht gezählt.

{
  "data": {
    "monatlichesLimit": null,
    "diesenMonatVerbraucht": 27,
    "diesenMonatVerbleibend": null,
    "einfacheSuchenZaehlen": false,
    "erweiterteSuchenZaehlen": true,
    "zurueckgesetztAm": "2026-09-01T00:00:00.000Z"
  }
}

Verlasse dich auf HTTP-Status und error.code. Die Nachricht ist für Menschen gedacht. Gib bei Support-Anfragen immer die requestId an.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Die Anfrage ist ungültig.",
    "details": {},
    "requestId": "req_..."
  }
}