How a document anonymization engine works under the hood

Most people picture anonymization as a slightly cleverer find-and-replace: locate the ID number, black it out, done. Anyone who has tried it at scale knows better. A real administrative file contains names written four different ways, nine-digit numbers that are sometimes a phone number and sometimes not, references to legislation that must not be touched, and people who are identified without their name appearing anywhere.

This article opens the box and explains what happens between uploading a document and getting the result back. If what you want is the product sheet —which data types, which formats, which guarantees— that lives in the technical specifications.

Why no single technique is enough

There are two families of tools for finding personal data in text, and each fails precisely where the other succeeds.

Deterministic rules —regular expressions, format validators— are surgical with anything structured. A tax ID, an IBAN or an email address can be described exactly and found with no room for doubt. But they know nothing about language: to a regular expression, «Ávila» and «Ana Ávila» are equally opaque.

Language models do the opposite. They recognize that «Ms. Fernández Iglesias» is a person and that «Talarrubias» is a town, because they have seen millions of similar sentences. What they cannot do is divide by 23 to check whether the letter of a Spanish ID number adds up.

The practical conclusion is that a serious engine does not choose: it chains several specialized passes, each contributing candidates with its own confidence score, and leaves the final call to the last step.

The layers, one by one

Layer	What it solves
Extraction and normalization	Pulls the text out of the office document, the cells or the PDF text layer, and records the exact position of every fragment. Without that position, the substitution shifts the rest of the document and breaks the layout
Deterministic recognizers	Locate identifiers with a known structure and check that they are mathematically valid before accepting them
Named entity recognition	A model trained on Spanish finds people, organizations and places in free text; a second model accepts new data types described in plain language
Coreference	Groups together every mention that refers to the same person
Relationships and quasi-identifiers	Detects whoever is identified by their family link, their role or a combination of attributes
Quality control	Measures accuracy in a disaggregated way and corrects the known biases of the models
Decision	Resolves overlaps, applies thresholds, template, allow list and block list, and records the origin of every substitution

Each layer builds on the previous one. If extraction loses the position of the text, the substitution lands in the wrong place no matter how well the entity model performed.

Validate before you redact

Finding a string shaped like a national ID is easy. Checking that it is one requires doing the arithmetic. That is the difference between redacting a case file number because it looks similar and leaving it where it belongs.

Identifier	Check applied
NIF, individuals	Check letter from the remainder of division by 23
NIE	The leading X, Y or Z is replaced by its numeric value before computing the letter
NIF, legal entities	Check digit or letter depending on the type of entity
Social Security number	Check digits by modulo 97
IBAN	ISO 13616, modulo 97 verification
Vehicle registration plate	Current format and historical provincial formats
Código Seguro de Verificación	Configurable pattern, because each issuing body uses its own
Email, IP, URL	Syntactic validation

One case deserves its own paragraph, and it is the one that has ruined the most administrative documents: references to legislation. To a naive detector, «Decreto 45/2019, de 3 de abril» is a date accompanied by two numbers. Redact it and the result is an unreadable decision from which the very rule that justifies it has vanished. That is why citations of laws, decrees and circulars are recognized not in order to anonymize them, but to protect them from anonymization.

On top of that sits contextual boosting. An isolated nine-digit number is ambiguous; the same number preceded by «contact telephone» is not. The words in the immediate surroundings —ID, account, address, case file— raise or lower the candidate’s confidence.

One decision per person

In a long file, the same person appears as «Doña María Luisa Fernández Iglesias» in the heading, as «the applicant» in the background section, as «the interested party» in the legal reasoning and as «Ms. Fernández» in the ruling. A system that treats each mention separately will make you take forty decisions about the same person, and one of them slipping through is enough to spoil the result.

Coreference builds the list of people in the document and hangs every occurrence off each of them. You decide once, and the decision propagates. It is also what makes tokenization stable: if all the mentions of someone are grouped, they can all receive the same label, and [PER_1] is still the same person forty pages later.

The people identified without being named

«The applicant’s brother» is personal data. So is «the mayor of a town of 3,000 inhabitants». Neither contains a name, and both lead to a specific person in two clicks.

The European Data Protection Board calls it singling out when a record can be isolated within a set, and treats it as one of the three risks you must rule out before claiming that data is anonymous. The other two are linkability and inference, and we go into them in the guide on anonymization and pseudonymization.

Detecting those links is not enough: you have to decide what to do with them, and the answer depends on where the document is going. Generalizing the link («sister of [PER_2]») is usually enough to publish a decision on a transparency portal. Neutralizing the role turns «mayor of Santa Cruz de la Palma» into a generic category. And to share a set of files for statistical purposes, deleting the whole phrase is safer than any cosmetic fix.

The two errors do not cost the same

There is a design decision here worth understanding, because it explains how the system behaves.

A false positive —redacting something that was not personal data— costs readability and is fixed in two clicks on the review screen. A false negative —leaving personal data in plain sight— is an unauthorized disclosure of personal data, with everything that implies before a supervisory authority.

Since the two errors are not symmetrical, neither is the calibration: when in doubt, it flags. Precision is recovered afterwards, in human review, which is quick because it consists of dismissing extras rather than hunting for what is missing. If your case calls for a different balance, confidence thresholds are adjustable per data type.

Why each item was replaced

An anonymization you cannot explain is an anonymization you cannot defend. For every substitution applied you should be able to answer four questions: which layer produced it, which data type it was assigned, with exactly what confidence —the number, not a «high» or «medium»— and what triggered the detection.

It is useful for three very practical things: understanding a result that surprised you, tuning the configuration deliberately instead of by trial and error, and documenting to a third party how an automated decision about a document was reached. The third stops being optional the moment the document goes into a public file.

Bias is a protection problem too

Entity recognition models are trained on public text, and public text is not balanced. It is measured and documented that name recognition systems perform worse on female names than on male ones, and worse on surnames of non-Spanish origin than on Spanish ones.

In almost any other application that would be a quality problem. In anonymization it is a rights problem: it means some people would end up better protected than others simply because of what they are called. The reasonable countermeasures are four, and none of them is exotic:

1. Measure separately, not in aggregate. A high average can hide a poorly covered subgroup.
2. Cover inflection: brother and sister, mayor in both grammatical genders, the full range of honorifics.
3. Adjust the threshold of the subgroup recognized with lower confidence, instead of applying a single one that would leave it out.
4. Extend the lexical resources wherever the measurements point.

None of this eliminates bias; it makes it measurable and reduces it. Human review remaining part of the recommended procedure is not boilerplate: it is the logical consequence of admitting that no model is right every time.

When the document is a scan

If the file has no text layer —a scan, a photograph, a digitized fax— optical recognition stops being an accessory and starts determining the quality of everything else. A good process does four things: it preprocesses the image adaptively (deskewing, noise, perspective, binarization), transcribes with tolerance for overlaid stamps and typewriter fonts, analyses the page structure so that two adjacent columns are not mixed together, and feeds back: when a low-confidence candidate appears on optically recognized text —an ID whose letter does not add up, an impossible date— that region is re-examined with different parameters.

One detail makes a real difference in archival documentation: optical recognition frequently loses accents, and text where «Fernández» comes out as «Fernandez» degrades the detection of proper names. That is why comparison has to be accent-insensitive from the normalization layer onwards.

And a warning about the output: on an image, the substitution must be applied to the pixels. A black PDF annotation rectangle or an overlaid layer can be removed with any viewer, and the data is still underneath.

Spreadsheets: the column rules

In a spreadsheet or a database dump, analysing each cell on its own is a serious mistake. The right approach is to infer the data type of the entire column, from the set of its values and from the header, and apply it to every cell including the outliers: the one with an extra space, the one with a lowercase letter, the one left empty.

And structured data carries a risk you cannot see by looking at columns one at a time. Postcode, year of birth, sex and job category are four innocent fields that, combined, can leave a single person alone in their group. Verifying k-anonymity means setting a value of k and checking which combinations fall below that threshold. The Spanish data protection authority covers it in its technical note on k-anonymity, and ISO/IEC 20889:2018 lists it among the recognized de-identification techniques. It is the check to run before a statistical transfer or an open data release, where deleting the name column is not enough.

Frequently asked questions

Why aren’t regular expressions enough to anonymize documents?

Because they only find what has a fixed structure. A tax ID or an IBAN, yes; a proper name, an address written in prose or «the applicant’s brother», no. And without check-digit validation, a regular expression redacts any number that resembles an ID, case file numbers included.

What is coreference and why does it matter when anonymizing?

It is the grouping of every way a document names the same person: full name, surname with an honorific, and role-based references such as «the interested party». It matters because it lets you take one decision per person instead of one per mention, which is where omissions creep into long documents.

Can a scanned PDF with no text layer be anonymized?

Yes, through optical recognition, but on two conditions. First, the process must correct the image before transcribing it and be insensitive to missing accents. Second, the substitution must be applied to the pixels and not as an overlaid layer, which any PDF viewer can remove.

What is k-anonymity and when should it be checked?

It is the guarantee that any combination of attributes in a table is shared by at least k people, so nobody is left alone in their group. It is worth checking whenever you are about to share a dataset for statistical purposes or publish it as open data.

In short

A solid anonymization engine is not a pattern matcher with better aim. It is a chain of decisions where each step covers the blind spot of the previous one, calibrated in the knowledge that missing one item costs far more than redacting one too many, and able to explain why it did what it did.

If you want the detail of what anonimiza.do detects, in which formats and under what guarantees, it is in the technical specifications. And if you would rather see it running, try it on your own documents.