{"openapi":"3.0.0","info":{"title":"PII Anonymization API","version":"1.1.0","description":"Fast API for pseudonymizing personally identifiable information (PII). Combines parallel detection methods: pattern detection (emails, phones, IBANs, crypto wallets, EU IDs, German social/financial data, profile URLs on 35+ platforms), GLiNER NER (names, organizations), address detection (29 countries) and URL cross-referencing. Detection runs on our servers in Germany. The mapping is kept in memory until 30 minutes after its last use, at the latest 8 hours after its first use, so values can be restored. Values only come back with the session_id, and only with the API key that created it if one was used. Text from calls without an API key, or with a key that is not flagged for the nightly check, is not stored and not passed on. Only the operator can flag a key for the nightly check (today only our own instance); its pseudonymized texts are kept for 48 hours, 30 days on a finding, and checked by a model on rented GPU servers (RunPod or IONOS). An invalid or revoked API key is refused with HTTP 401. Each call that replaces something writes an audit entry without plain text (time, a keyed digest of the session ID, the number of detected values and keyed digests of them), kept for 7 days.","contact":{"name":"Michael SCHILLER - Organisation. Digital.","url":"https://schiller-partners.de"}},"servers":[{"url":"https://api.schiller-partners.de/v1","description":"Current server"}],"paths":{"/pii/anonymize":{"post":{"summary":"Anonymize text","description":"Detects PII in the provided text and replaces it (pseudonymization) using parallel detection methods. Returns the text with placeholders and a session_id to restore the original values later. Use marker_format=tagged (default) for parseable bracket tokens like [PERSON:a1b2c3d4], or marker_format=faker for natural-looking pseudonyms suitable for downstream LLMs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The text to anonymize (UTF-8)","maxLength":50000,"example":"Dr. Anna Müller (anna.mueller@firma.de, +49 231 5678900) wohnt in der Hauptstraße 42, 44137 Dortmund."},"session_id":{"type":"string","description":"Session ID for restoring the values. Without an API key, only a session_id this API returned is accepted; any other is replaced by a new signed one. With an API key you may name your own sessions, they only work with that key. Reuse the session_id across related texts to get the same placeholder for the same value."},"compact":{"type":"boolean","description":"Returns a compact response format (40-50% smaller JSON). Keys are shortened: anonymized_text→txt, entities→ent, session_id→sid, stats→st, performance→perf. Entity keys: text→t, label→l, start→s, end→e, placeholder→p. Useful for high-throughput scenarios or bandwidth-constrained environments.","default":false},"marker_format":{"type":"string","enum":["tagged","faker"],"default":"tagged","description":"Output format. \"tagged\" emits clearly-marked placeholders like [PERSON:abc12345] (parseable by API consumers). \"faker\" emits plausible pseudonyms like \"Markus Weber\" (for downstream LLM consumers that need natural-looking input)."}}}}}},"responses":{"200":{"description":"Successful anonymization","content":{"application/json":{"schema":{"type":"object","properties":{"anonymized_text":{"type":"string","description":"Text with PII replaced. Shape depends on marker_format: \"tagged\" (default) yields bracket tokens like [PERSON:a1b2c3d4]; \"faker\" yields plausible pseudonyms like \"Markus Weber\".","example":"[PERSON:a1b2c3d4] ([EMAIL:b2c3d4e5], [PHONE:c3d4e5f6]) wohnt in der [ADDRESS:d4e5f6a7]."},"entities":{"type":"array","description":"List of detected PII entities with their original values and placeholders","items":{"type":"object","properties":{"text":{"type":"string","description":"Original PII text that was detected","example":"Erika Mustermann"},"label":{"type":"string","description":"Entity type","enum":["person","email","phone","address","iban","credit_card","crypto","url_pii","abbreviation","birth_date","organization","location","postal_code","ip_address","de_social_security_number","de_tax_id","de_id_card","de_child_benefit_number","de_health_insurance_number","de_commercial_register","eu_vat","bic_swift","es_dni","es_nie","ch_ahv","fr_insee","nl_bsn","be_rijksregister","at_social_security_number"],"example":"person"},"start":{"type":"integer","description":"Start position in original text (0-indexed)","example":0},"end":{"type":"integer","description":"End position in original text (exclusive)","example":16},"placeholder":{"type":"string","description":"Anonymization placeholder used in output","example":"[PERSON:a1b2c3d4]"}}}},"session_id":{"type":"string","description":"Session ID to restore the original values (valid until 30 minutes after its last use, at the latest 8 hours after its first use)"},"stats":{"type":"object","properties":{"original_length":{"type":"integer","description":"Character count of input text"},"anonymized_length":{"type":"integer","description":"Character count of anonymized text"},"entities_found":{"type":"integer","description":"Total number of PII entities detected"},"entity_types":{"type":"object","description":"Count of entities per type (e.g., {\"person\": 2, \"email\": 1})","additionalProperties":{"type":"integer"}}}},"performance":{"type":"object","properties":{"detection_ms":{"type":"number","format":"float","description":"PII detection time in milliseconds"},"anonymization_ms":{"type":"number","format":"float","description":"Text anonymization time in milliseconds"},"total_processing_ms":{"type":"number","format":"float","description":"Total processing time in milliseconds"}}}}}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}},"400":{"description":"Bad request (missing/empty text, text too long, or invalid JSON)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}},"503":{"description":"Name detection unavailable, nothing was processed; retry later (code: pii_protection_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}}}}},"/pii/deanonymize":{"post":{"summary":"De-anonymize text","description":"Restores original PII values in pseudonymized text using the session ID returned by POST /pii/anonymize. The session mapping is kept until 30 minutes after its last use, at the latest 8 hours after its first use. Pass the marker_format the text was created with; stand-in names from marker_format=faker are only restored with marker_format=faker.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","session_id"],"properties":{"text":{"type":"string","description":"Anonymized text containing placeholders (e.g., [PERSON:a1b2c3d4], [EMAIL:b2c3d4e5])","example":"[PERSON:a1b2c3d4] ([EMAIL:b2c3d4e5]) wohnt in der [ADDRESS:c3d4e5f6]."},"session_id":{"type":"string","description":"Session ID from the anonymize response"},"marker_format":{"type":"string","enum":["tagged","faker"],"default":"tagged","description":"The marker_format the text was pseudonymized with"}}}}}},"responses":{"200":{"description":"Successful de-anonymization","content":{"application/json":{"schema":{"type":"object","properties":{"original_text":{"type":"string","description":"Text with placeholders replaced by original PII values","example":"Dr. Anna Müller (anna.mueller@firma.de) wohnt in der Hauptstraße 42, 44137 Dortmund."},"session_id":{"type":"string"}}}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}},"400":{"description":"Bad request (missing text or session_id, or invalid JSON)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"error_id":{"type":"string","description":"Reference for support, only on 500. The response never repeats the text."},"code":{"type":"string","description":"Machine-readable cause, e.g. pii_protection_unavailable on 503"}},"required":["error"]}}}}}}},"/pii/schema":{"get":{"summary":"OpenAPI Schema","description":"Returns this OpenAPI 3.0 schema document describing all PII API endpoints.","responses":{"200":{"description":"OpenAPI schema","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"EntityLabel":{"type":"string","description":"All possible PII entity types detected by the API","enum":["person","email","phone","address","iban","credit_card","crypto","url_pii","abbreviation","birth_date","organization","location","postal_code","ip_address","de_social_security_number","de_tax_id","de_id_card","de_child_benefit_number","de_health_insurance_number","de_commercial_register","eu_vat","bic_swift","es_dni","es_nie","ch_ahv","fr_insee","nl_bsn","be_rijksregister","at_social_security_number"],"x-categories":{"Personal":["person","email","phone","address","birth_date"],"Financial":["iban","credit_card","crypto","bic_swift"],"Government IDs (DE)":["de_social_security_number","de_tax_id","de_id_card","de_child_benefit_number","de_health_insurance_number","de_commercial_register"],"Government IDs (EU)":["eu_vat","es_dni","es_nie","ch_ahv","fr_insee","nl_bsn","be_rijksregister","at_social_security_number"],"Digital":["url_pii","ip_address"],"Context":["abbreviation","organization","location","postal_code"]}}}}}