API Reference

PII detection and redaction

Detect personal data, replace it with reversible placeholders, and restore matched values after processing.

Detection is best-effort

Statistical detection can miss personal data. Do not treat it as a complete compliance boundary. If data must not reach an external provider, route the workload to an upstream classified as local. Use redaction to reduce identifiable data when external processing is allowed, and use /v1/pii/analyse when your application needs to choose a path before processing.

Redact and restore a value

Combine the redact and restore endpoints when another service must process text without receiving the detected values:

Call /v1/pii/redact on the input text. Keep the mapping.
Send the redacted text to the service that needs to process it.
Call /v1/pii/restore with the response and the mapping to get the original values back.

Use /v1/pii/analyse to inspect text without changing it.

If you're using our chat completions, the anonymise processor performs this round trip for chat completions. For structured request context such as customer profiles, orders, or account state, use haystack with redact: true: it walks the JSON tree leaf-by-leaf and uses your schema flags before falling back to detection. You can enable both processors on one request. They use separate placeholder namespaces (<INF_TYPE_N> for free text and <INF_HAY_TYPE_N> for haystack).

Analyse text for PII

POST/v1/pii/analyse

Scopepii

Detect PII entities and return their types, text spans, and confidence scores.

Request

textrequiredstring: Text to analyse.
languagestring: Language code. Defaults to service default or "nl".
score_thresholdnumber: Minimum confidence (0-1). Defaults to 0.7.
service_idstring: Optional. Route to a specific PII service (see GET /v1/services). Falls back to the org’s default PII service when omitted.

json

{
  "text": "Jan Jansen woont in Amsterdam.",
  "language": "nl",
  "score_threshold": 0.7
}

Response · 200

has_piiboolean: True when at least one entity was found above the threshold.
entitiesarray: Entities with type, text, start, end (character offsets) and score.
entity_types_foundstring[]: Distinct entity types present in the result.

json

{
  "has_pii": true,
  "entities": [
    { "type": "PERSON", "text": "Jan Jansen", "start": 0, "end": 10, "score": 0.95 },
    { "type": "LOCATION", "text": "Amsterdam", "start": 20, "end": 29, "score": 0.92 }
  ],
  "entity_types_found": ["PERSON", "LOCATION"]
}

Redact PII

POST/v1/pii/redact

Scopepii

Replace detected entities with numbered placeholders and return the mapping needed to restore them.

Request

Same body as /v1/pii/analyse, including the optional service_id routing override.

json

{
  "text": "Jan Jansen woont in Amsterdam.",
  "language": "nl"
}

Response · 200

redacted_textstring: Original text with entities replaced by <TYPE_N> placeholders.
mappingobject: Object mapping each placeholder back to the original value. Keep this if you want to restore later.
entities_redactednumber: Number of entities replaced.

json

{
  "redacted_text": "<PERSON_1> woont in <LOCATION_1>.",
  "mapping": {
    "<PERSON_1>": "Jan Jansen",
    "<LOCATION_1>": "Amsterdam"
  },
  "entities_redacted": 2
}

Restore PII

POST/v1/pii/restore

Scopepii

Replace matching placeholders with their original values from a prior mapping.

Request

textrequiredstring: Text containing placeholders, typically output from another service that you want to de-anonymise.
mappingrequiredobject: Placeholder → original-value map, from a prior /v1/pii/redact response.

json

{
  "text": "<PERSON_1> woont in <LOCATION_1>.",
  "mapping": {
    "<PERSON_1>": "Jan Jansen",
    "<LOCATION_1>": "Amsterdam"
  }
}

Response · 200

restored_textstring: Text with all matched placeholders replaced.
replacements_madenumber: Number of placeholders successfully replaced.

json

{
  "restored_text": "Jan Jansen woont in Amsterdam.",
  "replacements_made": 2
}