A community repair workshop wants to share aggregate volunteer interests with a partner organization. Its intake notes also contain phone numbers, addresses, emergency contacts, and occasional free-text medical details. Amazon Comprehend DetectPiiEntities can identify candidate sensitive spans in text, but it does not decide what the partner is entitled to receive. This guide follows a fictional intake message to build an auditable redaction workflow rather than claiming a live AWS test.
Decide what the partner actually needs
Start with an export specification, not with an entity detector. The partner may need a count of people interested in bicycle repair and the number of morning shifts requested; it does not need volunteers’ names, contact numbers, personal circumstances or emergency contact notes. Keep that minimum dataset as the target. A perfectly redacted original intake form may still expose more context than the partner should see.
Map each source field to an allowed output column, a restricted staff-only column or a discard category. Draft the rule with an authorized program manager and privacy reviewer. If a sentence is necessary only for operational follow-up, exclude it instead of relying on software to remove every sensitive expression. Use synthetic records for trial runs, and retain the original in a separate permission-controlled location.
Prepare text without changing the character offsets
DetectPiiEntities returns entity type, confidence score and BeginOffset/EndOffset positions for recognized spans. AWS documents real-time analysis for a single UTF-8 text input with a 100 KB maximum. Pass the exact normalized text that you intend to mask, and record its encoding, version and source identifier. Do not silently change whitespace or Unicode normalization after collecting offsets.
A common implementation mistake is to treat a character offset as a byte offset when slicing text that contains accented names, smart quotes or emoji. Another is to redact after converting line endings, which shifts every later position. Confirm offset semantics against the AWS SDK and input language, then create test strings with multibyte characters. When a document is too large, segment it with clear boundaries rather than truncating the confidential tail.
Choose entity categories and review confidence
AWS identifies classes including names, addresses and various identifying numbers. Its returned Score estimates model confidence for the predicted type; it is not a probability that sharing the span is lawful. Choose a policy for masking high-risk categories, and send ambiguous classifications to a reviewer. Do not use a single permissive score threshold to decide whether a sensitive address should remain visible.
For a fictional note such as “Call Morgan at 555-0123 about the repair shift,” the desired public extract might contain only the repair activity and shift interest. Reviewers should identify cases where a location is the venue rather than a home address, and where a technical part number resembles a personal identifier. Record why each exception is retained, and do not use a real contact number in diagrams or training screenshots.
Apply offsets safely and handle overlap
A safe masking implementation sorts spans, resolves overlaps and replaces them without invalidating later positions. One straightforward design walks the original string from left to right and copies only approved non-sensitive segments. Alternative code may apply replacement spans in descending offset order. Whichever method is chosen, fail if offsets lie outside the input or map to unexpected text.
Do not use ordinary global search-and-replace for a detected name: it can alter unrelated words or miss a variant that was not returned by the detector. Use clear labels, such as “[PHONE REDACTED],” only when the receiving format allows them; for aggregate reports, omit entire restricted fields instead. Review the redacted copy visually to catch punctuation that accidentally reconnects hidden information.
Compare three meaningful export states
The comparison drawing distinguishes the source note, candidate PII spans and an approved partner-facing summary. These are conceptual examples, not recorded outputs from Comprehend. The decisive change is not a highlighted name becoming asterisks; it is the removal of unnecessary personal context while the legitimate workshop count remains available. A reviewer should be able to explain every field that survived.
Create synthetic positive and negative examples: a private home address, a public workshop location, an inventory serial number, and a phone number written with spaces. Test both obvious and subtle misses. An automatic detection score can help prioritize review, but the release gate is a comparison with the predefined export schema and authorization, not the absence of highlighted entities.
Separate detection from retention and deletion
The real-time DetectPiiEntities operation returns span metadata; AWS also describes separate asynchronous PII-redaction workflows. Do not assume that calling the detector writes a sanitized copy or erases the supplied text. Keep the source system’s permissions, retention schedule, encryption and access logs independent of the NLP step. Confirm regional service availability and any cross-border handling requirements before processing actual volunteer notes.
Avoid writing full input strings to debugging consoles, exception traces or analytics events. When staff need to investigate a missed field, use a restricted case ID and an approved inspection environment. Protect any human-review queue with the same care as the original intake records. A redacted export is not a substitute for deleting unnecessary raw data according to the organization’s retention policy.
Run a release checklist against the actual output
Have a staff reviewer confirm that the character positions still match, that common identifier formats were tested, and that every retained field has a legitimate reason. Inspect the output as a complete document, since two innocuous fragments together may reveal a person’s identity. Recheck tables, headers and filenames for personal data; masking only the paragraph body leaves several common leakage paths open.
Compare the final export schema against the partner’s approved data request, and require human approval for exceptions. Record the policy version, source revision and timestamp without copying sensitive source text into the audit note. If the reviewer finds one address in a supposedly anonymous export, halt the transfer, correct the transformation and regenerate the whole file rather than patching an attachment after it has been sent.
Deploy cautiously and measure missed cases
Begin with a shadow run using synthetic and appropriately authorized historical examples, with a human independently classifying the spans. Track missed sensitive content and incorrect masking of important operational fields separately; a combined accuracy percentage hides the risk of a single serious disclosure. Revisit the test set after intake forms, languages or volunteer programs change.
Comprehend can speed up the first pass over text, especially when many notes arrive in inconsistent formats. It cannot define your sharing agreement, detect every identifying clue or provide consent. The practical goal is a minimal, comprehensible export that staff can inspect and reproduce, with the underlying personal records protected by ordinary organizational controls.
How We Research
For this November 2026 editorial review, we consulted official vendor references: Amazon Comprehend detecting PII entities; DetectPiiEntities API reference; Amazon Comprehend security guidance. We mapped feature scope, input/output rules, failure conditions and developer guidance to a hypothetical community-service scenario. We did not execute paid API requests, upload private personal data, publish a real catalog record, run a security attack or measure service performance. The diagrams show original educational examples, not screenshots or recorded service results. Documentation, permissions, regional availability and service configuration can change; verify them in the current official reference and an authorized test before deployment.
Frequently Asked Questions
No. The real-time API returns entity spans and types; application-side masking or a separate supported redaction workflow is needed.
No. A high score does not prove completeness, and a low score does not authorize revealing a plausible identifier.
Do not assume so. Use the documented character-offset convention and test Unicode handling in the exact implementation.
Usually a minimal approved summary is safer; remove fields that were not requested rather than forwarding unnecessary prose.
No. All examples are fictional and the article reports no live AWS output.