API-Dokumentation

Kantrik Enrich reichert Firmennamen mit Firmendaten an: Branche, Größe, Standort, Technologien und, wenn gewünscht, Rollen möglicher Ansprechpartner.

Schnellstart

1. In der Plattform ein Demo-Konto anlegen. Es startet mit 500 Probe-Credits.
2. Unter „Schlüssel“ einen API-Schlüssel anlegen (er wird einmal angezeigt).
3. Aufrufen:

export KANTRIK_API_KEY=kk_...

curl -s https://api.kantrik.com/v1/enrich \
  -H "Authorization: Bearer $KANTRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"name":"Nordtech GmbH","domain":"nordtech.example"},{"name":"Elbbau AG"},{"name":"Müller & Söhne AG"}],"include_contacts":true}'

Antwort (so antwortet der Dienst tatsächlich auf diese Eingabe):

{
  "request_id": "req_8f2c41d0a9",
  "plan": "growth",
  "results": [
    {
      "input_index": 0,
      "match": "matched",
      "company": {
        "name": "Nordtech GmbH",
        "domain": "nordtech.example",
        "industry": "Logistik und Transport",
        "employees": "1-10",
        "city": "Köln",
        "country": "DE",
        "founded": 2000,
        "technologies": [
          "Slack",
          "Jira",
          "AWS"
        ]
      },
      "contacts": [
        {
          "role": "Leitung Marketing",
          "seniority": "director"
        },
        {
          "role": "Einkauf",
          "seniority": "manager"
        }
      ]
    },
    {
      "input_index": 1,
      "match": "matched",
      "company": {
        "name": "Elbbau AG",
        "domain": "elbbau.example",
        "industry": "Finanzdienstleistungen",
        "employees": "201-500",
        "city": "Dresden",
        "country": "DE",
        "founded": 1989,
        "technologies": [
          "Azure",
          "Salesforce",
          "Odoo"
        ]
      },
      "contacts": [
        {
          "role": "Personalleitung",
          "seniority": "director"
        },
        {
          "role": "Leitung Vertrieb",
          "seniority": "director"
        }
      ]
    },
    {
      "input_index": 2,
      "match": "unmatched",
      "company": null,
      "contacts": []
    }
  ],
  "credits_used": 6,
  "credits_remaining": 24994
}

Authentifizierung

Jede Anfrage trägt den Schlüssel als Bearer-Token: Authorization: Bearer kk_.... Schlüssel gehören zum Konto, nicht zu einer Person. Sie können mehrere haben und einzelne sperren; der letzte bleibt immer bestehen. Rufen Sie die API vom Server aus auf: der Schlüssel gehört nicht in Browser-Code (CORS ist nicht freigegeben).

POST /v1/enrich

Bis zu 100 Datensätze je Aufruf, Körper bis 256 KB. Jeder Datensatz hat name (bis 200 Zeichen) und optional domain. Die Ergebnisse stehen in der Reihenfolge der Eingabe; match ist matched, partial (nur Branche, Ort, Land) oder unmatched (company ist null).

GET /v1/company

Eine einzelne Firma nachschlagen, mit den Parametern name, domain und include_contacts.

curl -s "https://api.kantrik.com/v1/company?name=Elbbau%20AG&include_contacts=true" \
  -H "Authorization: Bearer $KANTRIK_API_KEY"

Credits und Preise

Abgerechnet werden Credits: 1 je Treffer, 3 je Treffer mit Ansprechpartner-Rollen, 0 ohne Treffer. Jeder Plan enthält Credits; darüber hinaus wird je 1.000 Credits abgerechnet.

Das Probe-Konto hat 500 Credits einmalig; sind sie verbraucht, antwortet die API mit limit_reached.

Rate Limits

Das Limit gilt je Konto und Minute (Tabelle oben). Jede Antwort zeigt den Stand: RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden bis zum Fenster-Ende). Ist das Limit erreicht, antwortet die API mit 429, dem Fehlercode rate_limited und Retry-After (Sekunden). Warten Sie diese Zeit ab, bevor Sie es erneut versuchen.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
RateLimit-Limit: 10
RateLimit-Remaining: 0
RateLimit-Reset: 23

{"error":{"code":"rate_limited","message":"Rate limit of 10 requests per minute reached. Retry in 23 seconds.","doc_url":"https://api.kantrik.com/docs#rate_limited"},"request_id":"req_..."}

Fehler

Fehler haben immer dieselbe Form: {"error":{"code","message","doc_url","param"?},"request_id":"..."}. Verlassen Sie sich auf code, nicht auf den Text. Nennen Sie dem Support die request_id.

Konto-Endpunkte

# Verbrauch der Periode samt Rechnungsvorschau
curl -s https://api.kantrik.com/v1/usage    -H "Authorization: Bearer $KANTRIK_API_KEY"
# Ausgestellte Rechnungen
curl -s https://api.kantrik.com/v1/invoices -H "Authorization: Bearer $KANTRIK_API_KEY"
# Schlüssel auflisten, anlegen, sperren
curl -s https://api.kantrik.com/v1/keys     -H "Authorization: Bearer $KANTRIK_API_KEY"
curl -s -X POST https://api.kantrik.com/v1/keys -H "Authorization: Bearer $KANTRIK_API_KEY"
curl -s -X DELETE https://api.kantrik.com/v1/keys/key_1a2b3c4d -H "Authorization: Bearer $KANTRIK_API_KEY"
# Plan wechseln
curl -s -X POST https://api.kantrik.com/v1/plan -H "Authorization: Bearer $KANTRIK_API_KEY" -H "Content-Type: application/json" -d '{"plan":"growth"}'

OpenAPI

Die maschinenlesbare Beschreibung (OpenAPI 3.1) liegt unter https://api.kantrik.com/openapi.json. Sie wird mit den automatischen Tests gegen die echten Antworten geprüft.

Ausprobieren ohne Code

Im Playground der Plattform können Sie Namen eingeben und die Antwort sehen, samt dem passenden curl-Aufruf.