Pseudonymize mode
Redaction draws black boxes. Pseudonymization replaces each person, company and address with a consistent tag such as [Person 1], so the document stays readable: you can still tell who did what. Use it before sharing a document for review, before an AI works on it, or when a recipient needs the structure but not the identities.
Turn it on
Send mode=pseudonymize with the job. Everything else (files, pii_categories, redaction rules, retention) works as in redact mode.
curl -sS -X POST "https://www.redact-pdf.ai/v1/jobs" \
-H "X-API-Key: YOUR_API_KEY" \
-F "files=@tenancy-agreement.pdf;type=application/pdf" \
-F "mode=pseudonymize"
The output is still a flattened PDF: the original text is removed from the file, and each tag is drawn in a light coloured box.
The tags
| Category | Tag |
|---|---|
| Person | [Person 1] |
| Organization | [Org 1] |
| Address | [Address 1] |
[Email 1] | |
| Phone number | [Phone 1] |
| Date | [Date 1] |
| IBAN or bank account | [Account 1] |
| Card number | [Card 1] |
- Tags are numbered in order of first appearance and are the same on every page.
- Variants of the same entity share one tag: "Anna Keller", "Ms Keller" and "A. Keller" are all
[Person 1]. - The tag words follow the document's language:
[Personne 1]in French,[Persona 1]in Spanish, English for languages without a translation. - National ID numbers and your always-redact terms stay black.
- In the Studio you can rename a tag, for example
[Person 1]to[Seller].
Get the document as text
GET /v1/documents/{doc_id}/output.md returns the pseudonymized document as Markdown, one ## Page N section per page, with every tag in place. It is what the PDF shows, so an agent can work on it without running OCR on a PDF that has no text layer.
curl -sS -D headers.txt "https://www.redact-pdf.ai/v1/documents/DOC_ID/output.md" \
-H "X-API-Key: YOUR_API_KEY" \
-o document.md
## Page 1
[Person 1] rents the flat at [Address 1] from [Org 1].
The X-Text-Version response header identifies the output this text describes. Keep it if you will put the names back later.
Get the correspondence table
GET /v1/documents/{doc_id}/correspondence returns a CSV with one row per tag: the placeholder, your rename (if any), the category and the original text.
placeholder,label,category,original
[Person 1],[Seller],Person,Anna Keller
[Org 1],,Organization,Acme AG
This table re-identifies the document. Keep it on your side, and never send it along with the pseudonymized PDF.
Put the names back
- Fetch
output.mdand note itsX-Text-Version. - Work on the text, or let an AI work on it. Keep the tags exactly as written, brackets included.
- Fetch the correspondence table with
?text_version=<that value>and replace each tag with its original.
curl -sS "https://www.redact-pdf.ai/v1/documents/DOC_ID/correspondence?text_version=TEXT_VERSION" \
-H "X-API-Key: YOUR_API_KEY" \
-o correspondence.csv
Passing text_version protects you from a changed document. If someone edited the document or ran detection again in the Studio after you fetched the text, a tag may now stand for a different name, so the API answers 412 (text_changed) instead of returning a table that no longer matches. Fetch output.md again and redo the work from the current text.
With an AI assistant, the MCP tools do this for you: restore_names puts the names back on your computer (local server) or on our side (connector), and returns a file path or a download link, never a name. See AI assistants.
Errors
| Status | Meaning |
|---|---|
402 | Not enough credits. Same gate as the redacted PDF. |
404 | Not found, not redacted yet, or the job did not use mode=pseudonymize. |
409 | The document was edited in the Studio after this output was produced. Download it again from the Studio, which refreshes both the PDF and the table. |
412 | text_version no longer matches the output on file (text_changed). |
422 | Some tags have no stored original: the document was analysed in redact mode before it was pseudonymized. |
The text version and the table are deleted when you delete the job, or when your account's retention window ends.