Developer docs

Pseudonymize mode

Replace names with consistent tags like [Person 1] instead of black boxes: mode=pseudonymize, the tags, the text version, the correspondence table, restoring names.

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.

Pseudonymize mode: each entity becomes a numbered tag, the same on every page.

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

CategoryTag
Person[Person 1]
Organization[Org 1]
Address[Address 1]
Email[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

  1. Fetch output.md and note its X-Text-Version.
  2. Work on the text, or let an AI work on it. Keep the tags exactly as written, brackets included.
  3. 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

StatusMeaning
402Not enough credits. Same gate as the redacted PDF.
404Not found, not redacted yet, or the job did not use mode=pseudonymize.
409The 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.
412text_version no longer matches the output on file (text_changed).
422Some 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.

Related pages