Pseudonymization

When a redaction policy uses the pseudonymize method, PII values are replaced with reversible pseudonyms (e.g. Person_7f3a). The de-pseudonymization endpoint allows you to reverse a pseudonym back to its original value.

How It Works

A redaction job processes text with a policy where redaction_method is set to pseudonymize.
Each detected PII value is replaced with a deterministic, tenant-scoped pseudonym.
The mapping between pseudonym and original value is stored securely.
Use the de-pseudonymization endpoint to look up the original value when needed.

Pseudonyms are deterministic within a tenant: the same input value always produces the same pseudonym. Different tenants produce different pseudonyms for the same input, ensuring cross-tenant isolation.

POST /depseudonymize

Reverse a pseudonym back to its original value.

Request Body

Field	Type	Required	Description
`pseudonym`	string	Yes	The pseudonym to reverse (e.g. `Person_7f3a`)
`tenant_id`	string	Yes	Tenant ID that owns the pseudonym mapping

Response

Field	Type	Description
`pseudonym`	string	The input pseudonym
`original_value`	string	The original PII value
`entity_type`	string	The PII entity type

Example


curl -X POST https://api.pii-redactor.dev/api/v1/depseudonymize \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "pseudonym": "Person_7f3a",
    "tenant_id": "tenant_xyz"
  }'


{
  "pseudonym": "Person_7f3a",
  "original_value": "John Smith",
  "entity_type": "PERSON"
}

Error Cases

If the pseudonym is not found or was not generated using the pseudonymize method:


{
  "detail": "Pseudonym not found or not associated with this tenant"
}

Status: 404 Not Found

Security Considerations

De-pseudonymization requires the same API key scope as the original redaction.
All de-pseudonymization requests are recorded in the audit log.
Consider restricting access to this endpoint to authorized personnel only.