Schnellstart

In fünf Minuten zum ersten Firmenprofil.

Du brauchst ein Konto und ein Terminal. Am Ende hast du mit einer Beispielanfrage das Firmenprofil der Hetzner Online GmbH abgerufen und weißt, was in der Antwort steht.

API-Schlüssel kopieren

Lege ein kostenloses Konto an und bestätige deine E-Mail-Adresse. Du bekommst 150 Startcredits, die 30 Tage gelten.

Dein erster API-Schlüssel liegt schon bereit, unter Konto › API-Schlüssel. Kopiere ihn und behandle ihn wie ein Passwort.

Jede Anfrage schickt den Schlüssel im Header x-api-key mit. In den Beispielen steht dafür DEIN_API_SCHLUESSEL.

Antwortet die API mit 401, fehlt der Schlüssel oder er ist unvollständig kopiert. Bei 403 ist deine E-Mail-Adresse noch nicht bestätigt. Den Link dazu findest du in deinem Postfach.

Firmenprofil abrufen

Ruf fetch-organization auf und gib den Firmennamen im Parameter q mit. Ohne weitere Parameter bekommst du die Basisdaten für 5 Credits.

Kopiere die Anfrage, setze deinen Schlüssel ein und führe sie aus. cURL gibt das JSON direkt aus. In Python und JavaScript steht die Antwort danach in data. Mit print(data["name"]) bzw. console.log(data.name) siehst du den Firmennamen.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: DEIN_API_SCHLUESSEL" \
  --data-urlencode 'q=Hetzner Online GmbH'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "DEIN_API_SCHLUESSEL"},
    params={
        "q": "Hetzner Online GmbH",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");

const response = await fetch(url, {
  headers: { "x-api-key": "DEIN_API_SCHLUESSEL" },
});
const data = await response.json();

Antwort lesen

Die Antwort ist das Firmenprofil als JSON. Diese Felder brauchst du am häufigsten:

Antwort lesen
Feld	Bedeutung
entity_id	Die ID der Firma bei handelsregister.ai. Speichere sie für Folgeabfragen.
name, legal_form, status	Firmenname, Rechtsform und Registerstatus, im Beispiel `ACTIVE`.
registration	Registergericht, Registerart und Registernummer, im Beispiel Ansbach HRB 6089.
address, seat	Geschäftsanschrift mit Koordinaten, dazu der Sitz laut Register.
purpose, industry_classification	Unternehmensgegenstand und Branche nach WZ 2008 und WZ 2025.
representation_scheme	Vertretungsregelung: `current` gilt heute, `history` zeigt jeden eingetragenen Stand.
meta	Was die Anfrage gekostet hat (`request_credit_cost`) und dein Guthaben danach (`credits_remaining`).

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "status": "ACTIVE",5  "legal_form": "GmbH",6  "registration": {7    "court": "Ansbach",8    "register_type": "HRB",9    "register_number": "6089"10  },11  "industry_classification": {12    "WZ2008": [13      {14        "code": "62.01.0",15        "label": "Erbringung von Dienstleistungen der Informationstechnologie"16      },17      {18        "code": "63.11.0",19        "label": "Datenverarbeitung, Hosting und damit verbundene Tätigkeiten"20      },21      {22        "code": "61.90.0",23        "label": "Telekommunikation, sonstige"24      }25    ],26    "WZ2025": [27      {28        "code": "62.20.1",29        "label": "Erbringung von Beratungsleistungen auf dem Gebiet der Informationstechnologie"30      },31      {32        "code": "46.50.1",33        "label": "Großhandel mit Datenverarbeitungsgeräten, peripheren Geräten und Software"34      },35      {36        "code": "62.90.0",37        "label": "Erbringung von sonstigen Dienstleistungen der Informationstechnologie"38      }39    ]40  },41  "address": {42    "house_number": "25",43    "street": "Industriestraße",44    "postal_code": "91710",45    "city": "Gunzenhausen",46    "county": "Weißenburg-Gunzenhausen",47    "state": "Bayern",48    "country": "DEU",49    "coordinates": {50      "latitude": 49.12483,51      "longitude": 10.7805252    }53  },54  "seat": {55    "city": "Gunzenhausen"56  },57  "registration_date": null,58  "representation_scheme": {59    "current": [60      "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."61    ],62    "history": [63      {64        "value": [65          "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."66        ],67        "effective_from": "2002-10-15",68        "effective_to": "2015-07-28"69      },70      {71        "value": [72          "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."73        ],74        "effective_from": "2015-07-28",75        "effective_to": null76      }77    ]78  },79  "purpose": "Die Durchführung von Internet- und Netzwerkdienstleistungen, das Erstellen und Vertreiben von Software, der Handel mit Hard- und Software, der Betrieb einer Werbeagentur,darüber hinaus der Im- und Export von Waren aller Art, soweit sie keiner Einfuhr- oder Ausfuhrbeschränkung unterliegen und soweit keine Genehmigungen erforderlich sind.",80  "meta": {81    "request_credit_cost": 5,82    "credits_remaining": 14583  }84}

200 · Beispielantwort für die Hetzner Online GmbH, nur die Basisdaten

Mit der entity_id fragst du dieselbe Firma später direkt ab. Sie ist auch der Schlüssel für fetch-document und Signals. Genauso eindeutig sind Registergericht und Registernummer, im Beispiel Ansbach HRB 6089.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: DEIN_API_SCHLUESSEL" \
  --data-urlencode 'q=94eb910fef13f94585c48c263fa446d4'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "DEIN_API_SCHLUESSEL"},
    params={
        "q": "94eb910fef13f94585c48c263fa446d4",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "94eb910fef13f94585c48c263fa446d4");

const response = await fetch(url, {
  headers: { "x-api-key": "DEIN_API_SCHLUESSEL" },
});
const data = await response.json();

Weiter geht es

Features dazunehmen Geschäftsführung, Gesellschafter oder Finanzen in derselben Anfrage. Firma per Registernummer abrufen Der eindeutige Weg über Registergericht, Registernummer und entity_id. Grundbegriffe Wie Credits, Echtzeit, Historie und leere Werte funktionieren. ChatGPT-Plugin Dieselben Daten im Chat, ganz ohne Code. Python-SDK Die API in Python, mit fertigen Methoden. Node-SDK Die API in JavaScript und TypeScript.