API-Dokumentation

Alle Endpunkte, Parameter, Antwortformate und Credit-Kosten im Überblick.

Authentifizierung & Schnellstart

Base-URL

https://api.factsoft.de/v2

Alle Endpunkte dieser Dokumentation werden an diese Basis-URL angehängt. Die API ist ausschließlich per HTTPS erreichbar.

API-Key (Header)

Jeder Aufruf (außer Test-Endpunkte) benötigt einen API-Key im HTTP-Header:

X-API-Key: Ihr-api-key-hier

Beispiel – vollständiger Aufruf mit curl

curl -X POST https://api.factsoft.de/v2/depersonalize \
  -H "X-API-Key: Ihr-api-key-hier" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hallo Frau Schmitt, Ihre IBAN lautet DE22200400600056789001."}'

Ohne API-Key können Sie https://api.factsoft.de/v2/depersonalize/test aufrufen – dieser Endpunkt verbraucht keine Credits und erfordert keine Registrierung.

ℹ API-Keys erhalten Sie nach dem Kauf eines Pakets. Test-Endpunkte (/depersonalize/test, /process/test) verbrauchen keine Credits und benötigen keinen API-Key.

🛁 Datenschutz & DSGVO: Personenbezogene Daten verlassen das Depersonalisierungssystem zu keinem Zeitpunkt, werden auf den verarbeitenden Servern nicht gespeichert und bleiben vollständig in der EU. Mit jedem API-Key stellt factsoft AG eine DSGVO-konforme Auftragsverarbeiter-Vereinbarung (AVV) aus.

Credit-System

Credits werden pro API-Aufruf abgezogen:

Endpunkt	Credits
`/depersonalize`, `/depersonalize/json`, `/depersonalize/csv`	1
`/rehydrate`, `/rehydrate/json`	0 (kostenlos)
`/process`, `/process/json`, `/process/csv`	1 (NER) + 1–10 (KI) = 2–11 Credits
`/query`	1–10 Credits (nur KI, kein NER-Schritt)
Test-Endpunkte (`/depersonalize/test`, `/process/test`)	0 (kein Key nötig)

Die KI-Credits bei /process und /query richten sich nach Textlänge und gewähltem Modell. Der exakte Wert wird vor dem Aufruf geprüft – sind nicht genug Credits vorhanden, wird der Aufruf abgelehnt. Jede Antwort enthält credits_used und credits_remaining.

KI-Credits nach Textlänge
Textlänge	Haiku	Sonnet (default)
bis 2.000 Zeichen	1	1
bis 5.000 Zeichen	2	3
bis 10.000 Zeichen	3	5
bis 15.000 Zeichen	4	6
bis 20.000 Zeichen	5	8
bis 30.000 Zeichen	6	9
bis 40.000 Zeichen	7	10
über 40.000 Zeichen	8–10	10

Bei /process kommen zu den KI-Credits immer +1 Credit für den NER-Anonymisierungsschritt hinzu.

Eingabe-Limits

Endpunkt	Feld	Maximum	Fehler bei Überschreitung
`/depersonalize`, `/depersonalize/json`, `/depersonalize/csv`, `/depersonalize/test`	`text`	60.000 Zeichen	`422`
`/process`, `/process/json`, `/process/csv`, `/process/test`, `/query`	`text`	40.000 Zeichen	`422`
`/process`, `/process/json`, `/process/csv`, `/query`	`instruction`	2.000 Zeichen	`422`
`/process`	`max_output_tokens`	8.192 Tokens (Hardcap Claude-API)	wird automatisch auf 8.192 gedeckelt

Wenn max_output_tokens nicht angegeben wird oder 0 ist, berechnet das System den optimalen Wert automatisch (ca. Eingabezeichen ÷ 3 × 1,25, mindestens 512 Tokens). Das verhindert abgeschnittene Antworten bei langen Texten. Der Wert wird in der Antwort als max_tokens_used zurückgegeben.

Funktion A – Depersonalisierung

POST /v2/depersonalize Text depersonalisieren ▶

Erkennt PII im Freitext und ersetzt sie durch typisierte Platzhalter. Gibt anonymisierten Text + Key zurück.

Request Body

Feld	Typ	Pflicht	Beschreibung
`text`	string	✓	Zu anonymisierender Text (max. 60.000 Zeichen)
`language`	string	–	Sprache: `de` (default) oder `en`
`placeholder_style`	string	–	`typed` (default) oder `generic`

// Beispiel-Request
{
  "text": "Hallo Frau Schmitt, IBAN DE22200400600056789001"
}

// Antwort
{
  "anonymized_text": "Hallo PERSON_F_1, IBAN IBAN_1",
  "key": { "PERSON_F_1": "Frau Schmitt", "IBAN_1": "DE222..." },
  "entity_count": 2,
  "credits_used": 2,
  "credits_remaining": 498
}

POST /v2/depersonalize/json JSON-Objekt depersonalisieren ▶

Verarbeitet beliebig verschachtelte JSON-Strukturen. Alle String-Werte werden anonymisiert, Integer und Booleans bleiben unverändert.

Feld	Typ	Pflicht	Beschreibung
`data`	object \| array	✓	JSON-Objekt oder Array
`fields`	string[]	–	Nur diese Top-Level-Felder verarbeiten

{
  "data": { "name": "Thomas Müller", "email": "t.mueller@example.com", "count": 42 }
}
// Antwort:
{
  "anonymized_data": { "name": "PERSON_1", "email": "EMAIL_1", "count": 42 },
  "key": { "PERSON_1": "Thomas Müller", "EMAIL_1": "t.mueller@example.com" },
  "entity_count": 2
}

POST /v2/depersonalize/csv CSV-Datei depersonalisieren ▶

Nimmt eine CSV-Datei (Upload oder Rohtext) und gibt eine anonymisierte CSV zurück. Delimiter wird automatisch erkannt (, oder ;).

Feld	Typ	Beschreibung
`file`	multipart/form-data	CSV-Datei (oder `text`)
`text`	form string	CSV als Rohtext (alternativ zu file)
`columns`	form string	Kommagetrennte Spaltenauswahl (leer = alle)
`has_header`	form bool	Hat die CSV eine Kopfzeile? (default: true)

# curl-Beispiel mit Datei-Upload
curl -X POST https://api.factsoft.de/v2/depersonalize/csv \
  -H "X-API-Key: IhrKey" \
  -F "file=@kunden.csv" \
  -F "columns=name,email"

POST /v2/depersonalize/test Testmodus – kein Credit-Abzug ▶

Ersetzt erkannte PII durch xxxx (keine Reversibilität, kein Key). Ideal zum Testen der Erkennungsleistung. Verbraucht 0 Credits, kein API-Key nötig. Limit: 60.000 Zeichen.

{ "text": "..." }
// Antwort:
{ "masked_text": "Hallo xxxx, IBAN xxxx.", "entity_count": 2, "entities_by_type": { "PERSON_F": 1, "IBAN": 1 } }

Funktion B – Rehydrierung

POST /v2/rehydrate Platzhalter zurücksetzen – kostenlos ▶

Ersetzt alle Platzhalter im Text anhand des Keys aus der Depersonalisierungsantwort. Immer kostenlos.

{
  "text": "Hallo PERSON_F_1, Ihre IBAN ist IBAN_1.",
  "key": { "PERSON_F_1": "Frau Schmitt", "IBAN_1": "DE22200400600056789001" }
}
// Antwort:
{ "result": "Hallo Frau Schmitt, Ihre IBAN ist DE22200400600056789001.", "replacements_made": 2 }

POST /v2/rehydrate/json JSON rehydrieren – kostenlos ▶

Wie /rehydrate, aber für JSON-Objekte. Durchläuft die Struktur rekursiv.

{ "data": { "kunde": "PERSON_1" }, "key": { "PERSON_1": "Max Müller" } }

Funktion C – KI-Verarbeitung

🛁 DSGVO-konform: Der Text wird zunächst auf unseren EU-Servern depersonalisiert. Nur der anonymisierte Text mit Platzhaltern (z.B. PERSON_1, IBAN_1) wird an Claude übertragen. Originaldaten verlassen unser System zu keinem Zeitpunkt und werden nicht gespeichert.

POST /v2/process Depersonalisieren → Claude → Rehydrieren ▶

Vollständiger Durchlauf: Text wird serverseitig anonymisiert, der anonymisierte Text an Claude gesendet, die Antwort rehydriert und zurückgegeben.

Feld	Typ	Pflicht	Beschreibung
`text`	string	✓	Zu verarbeitender Text (max. 40.000 Zeichen)
`instruction`	string	✓	Anweisung an Claude, z.B. "Formuliere eine höfliche Antwort" (max. 2.000 Zeichen)
`model`	string	–	KI-Modell: `claude-haiku-4-5-20251001` oder `claude-sonnet-4-6` (default). Haiku ist günstiger, Sonnet leistungsstärker.
`language`	string	–	Sprache (default: `de`)
`signature`	string	–	Signatur, die Claude am Ende anhängen soll
`max_output_tokens`	integer	–	Maximale Claude-Ausgabe in Tokens (0 = automatisch, max. 8.192). Wird in der Antwort als `max_tokens_used` zurückgegeben.

{
  "text": "Sehr geehrter Herr Maier, ich möchte mein Konto DE89 3704 0044 0532 0130 00 kündigen.",
  "instruction": "Formuliere eine höfliche Kündigungsbestätigung.",
  "signature": "Mit freundlichen Grüßen\nIhr Support-Team"
}
// Intern: Text wird zuerst depersonalisiert (API-Server, EU) → anonymisierter Text an Claude → Antwort rehydriert
// Antwort:
{
  "result": "Sehr geehrter Herr Maier, wir bestätigen die Kündigung Ihres Kontos DE89 3704 0044...\n\nMit freundlichen Grüßen\nIhr Support-Team",
  "entity_count": 2,
  "credits_used": 4,
  "credits_remaining": 496
}

POST /v2/process/test Vorschau – 0 Credits (Claude wird nicht aufgerufen) ▶

Zeigt, welcher anonymisierte Text an Claude übertragen worden wäre. Nützlich zur Prüfung des Erkennungsergebnisses.

POST /v2/process/json JSON-Objekte durch Claude verarbeiten lassen ▶

Anonymisiert alle String-Felder im JSON serverseitig, sendet das anonymisierte JSON an Claude, rehydriert die Antwort.

POST /v2/process/csv CSV-Dateien durch Claude verarbeiten lassen ▶

Wie /process, verarbeitet aber CSV-Dateien. Kleine Batches (<20 Zeilen) werden gebündelt übertragen.

Account – `/v2/me`

GET /v2/me API-Key-Informationen und Guthaben ▶

// Antwort:
{
  "credits": 842,
  "credits_total": 1000,
  "created_at": "2026-04-01T12:00:00Z",
  "last_used_at": "2026-04-12T08:10:00Z",
  "config": {}
}

Modellauswahl – Haiku 4.5 vs. Sonnet 4.6

Alle Endpunkte, die Claude aufrufen (/process, /process/json, /process/csv, /query), akzeptieren einen optionalen model-Parameter. Wird er weggelassen, wird Sonnet 4.6 verwendet.

Modell-ID	Name	Stärken	Credits (KI-Anteil)
`claude-haiku-4-5-20251001`	Haiku 4.5	Schnell, günstig – ideal für CSV, Listen und strukturierte Daten	1–10 (staffelweise)
`claude-sonnet-4-6`	Sonnet 4.6 (default)	Leistungsstark – empfohlen für komplexe Freitexte, juristische Dokumente	1–10 (staffelweise)

Beispiel (curl):

// Mit Haiku:
curl -X POST https://api.factsoft.de/v2/process \
  -H "Content-Type: application/json" \
  -H "X-API-Key: DEIN_API_KEY" \
  -d '{"text": "...", "instruction": "...", "model": "claude-haiku-4-5-20251001"}'

// Mit Sonnet (default – model-Feld kann weggelassen werden):
curl -X POST https://api.factsoft.de/v2/process \
  -H "Content-Type: application/json" \
  -H "X-API-Key: DEIN_API_KEY" \
  -d '{"text": "...", "instruction": "...", "model": "claude-sonnet-4-6"}'

Ungültige Modell-IDs werden mit HTTP 422 abgewiesen. Die genaue Credit-Staffelung nach Textlänge finden Sie auf der Preisseite.

Erkennungs-Engine & Platzhalter-Stile

Alle Endpunkte verwenden ausschließlich Regex + NER kombiniert – es gibt keinen separaten Modus-Parameter mehr.

Layer	Technologie	Erkennt
Layer 1	Regex (Pattern-Matching)	IBAN, E-Mail, Telefon, Datum, IP, URL, Kreditkarte u. v. m.
Layer 2	NER via spaCy (`de_core_news_lg`)	Personennamen, Organisationen, Orte – auch Freinamen

Platzhalter-Stile

Stil	Beispiel	Beschreibung
`typed` (default)	`IBAN_1`, `PERSON_F_2`	Typ + laufende Nummer
`generic`	`ENTITY_1`	Einheitlicher Platzhalter

Funktion D – KI-Direktanfrage

Sendet Text und Anweisung direkt an Claude – ohne vorherige Anonymisierung oder anschließende Rehydrierung. Geeignet für Texte ohne personenbezogene Daten. Kostet 3 Credits.

POST /v2/query 3 Credits · Direktanfrage an Claude

Request-Body (JSON):

Feld	Typ	Pflicht	Beschreibung
`text`	string	ja	Zu verarbeitender Text – max. 40.000 Zeichen
`instruction`	string	ja	Anweisung an Claude – max. 2.000 Zeichen
`model`	string	nein	KI-Modell: `claude-haiku-4-5-20251001` oder `claude-sonnet-4-6` (default)
`max_output_tokens`	int	nein	0 = automatisch (max. 8.192). Rückgabe als `max_tokens_used`
`signature`	string	nein	Wird unverändert ans Ende der Antwort angehängt

Antwort:

{
  "result":            "Antwort von Claude...",
  "credits_used":      3,
  "credits_remaining": 97,
  "max_tokens_used":   512
}

Beispiel:

curl -X POST https://api.factsoft.de/v2/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: DEIN_API_KEY" \
  -d '{
    "text": "Das Quartalsergebnis Q1 liegt bei 2,1 Mio. EUR.",
    "instruction": "Fasse den Text in einem Satz zusammen."
  }'

Erkennungstypen & Platzhalter

Typ	Modus	Beispiel
`IBAN`	Regex	DE89 3704 0044 0532 0130 00
`EMAIL`	Regex	max@example.com
`PHONE_DE`, `PHONE_INTL`	Regex	+49 171 1234567
`IP_ADDRESS`	Regex	192.168.1.1
`DATE`	Regex	12.04.2026 / 2026-04-12
`CREDIT_CARD`	Regex	4111 1111 1111 1111
`STEUER_ID`	Regex	12345678901
`PASSPORT`	Regex	C01X00T47
`LICENSE_PLATE`	Regex	B-AB 1234
`POSTCODE_DE`	Regex	10115
`URL`	Regex	https://example.com
`SV_NUMMER_DE`	Regex	12123456A123
`PASSWORD`	Regex	password: geheim123 → nur Wert
`API_KEY`	Regex	api_key=abc…xyz → nur Wert
`USERNAME`	Regex	username: max → nur Wert
`PERSON_M`, `PERSON_F`	Regex (Anrede)	Herr Müller / Frau Schmidt
`PER`, `ORG`, `LOC`	NER (spaCy)	NLP-erkannte Personen/Org/Orte
`CUSTOM`	alle	Benutzerdefinierte Regex aus Key-Config

Fehlercodes

HTTP	Fehler-Code	Bedeutung
400	`empty_text`	Text ist leer oder fehlt
401	`missing_api_key`	X-API-Key Header fehlt
401	`invalid_api_key`	Ungültiger oder inaktiver API-Key
402	`insufficient_credits`	Nicht genug Credits
422	–	Ungültige Request-Parameter (Pydantic-Validierung)
503	`claude_timeout`	Claude hat nicht innerhalb von 30 s geantwortet
503	`claude_unavailable`	Anthropic-API nicht erreichbar
500	`internal_error`	Unerwarteter Serverfehler

// Fehler-Antwortformat:
{ "detail": { "error": "insufficient_credits", "message": "Nicht genug Credits.", "credits": 0 } }