Working with Document Redactions

Vault supports document redactions, which allow users to mark sensitive content for removal and generate a redacted document from those annotations. Learn more about enabling document redactions.

This guide covers the prerequisites for using redaction annotations using Vault API, how to create redaction annotations, invoke the Generate Redacted Copy action, poll for generation status, and export and import redaction annotations using PDF documents.

Prerequisites

Before you can work with document redactions through the API, an Admin must configure your Vault to use document redactions. Learn more about enabling document redactions.

The user must have the following permissions:

Your user must be in a document role that grants Redact: Creating, updating, moving, and deleting redaction annotations, and invoking the Generate Redacted Copy action.
Your security profile must grant Application: Vault Actions: Manage Redactions: Moving or deleting another user's redaction annotations via API.

Learn more about required document redaction permissions.

Create a Redaction Annotation

Use the Create Multiple Annotations with type__sys set to redaction__sys.

Each redaction annotation requires the redaction_type__sys field, which specifies the redaction type and determines the redaction annotation's appearance on both the source document and the redacted copy.

Use Retrieve Annotation Type Metadata with annotation_type set to redaction__sys to retrieve available redaction types. By default, available redaction types are ppd__sys, cci__sys, and other__sys. There may be other redaction types available in your Vault.

Creating the first redaction annotation on a document version automatically creates a Redaction record (redaction__sys object) in the Redacting Source state. Subsequent annotations on the same document version attach to the existing record.

You cannot create redaction annotations on documents where the redaction__sys document field value is Redacted.

The example below shows the JSON object for a redaction annotation with a rectangle placemark.

[
  {
    "type__sys": "redaction__sys",
    "document_version_id__sys": "102_2_0",
    "redaction_type__sys": "ppd__sys",
    "placemark": {
      "type__sys": "rectangle__sys",
      "x_coordinate__sys": 0.1,
      "y_coordinate__sys": 0.2,
      "width__sys": 0.3,
      "height__sys": 0.05,
      "page_number__sys": 1
    }
  }
]

Retrieve the Redaction Record ID

Creating the first redaction annotation on a document version automatically creates a redaction__sys record. The annotation creation response returns the annotation ID, not the record ID. To invoke the Generate Redacted Copy action and poll for status, you need the record id. Retrieve it using VQL:

SELECT id, name__v, state__v
FROM redaction__sys
WHERE source_document_id__sys = {doc_id}

Replace {doc_id} with the numeric ID of the original document, for example, 1601. The query returns the record id, for example V94000000001001, and its current state__v. Use this id value as {record_id} in subsequent calls.

Invoke the Generate Action

After annotating, invoke the Generate Redacted Copy action on the redaction__sys record to produce the redacted document. Use the Generate or Update Redacted Copy endpoint.

Generation runs asynchronously. After the call returns, the redaction__sys record moves to the generating_redacted_copy__sys state while the job runs. Vault sends a notification on completion or failure.

If any redaction annotation has untraceable placement (page-level displacement), the action returns an error. Correct or remove the displaced annotation before retrying. On failure, the record returns to the Redacting Source (redacting_source__sys) state. Any prior redacted document version remains the current version.

Poll for Generation Status

Use the Retrieve Object Record request on redaction__sys to check the record's state__v field.

The following states indicate progress:

redacting_source__sys: Annotations are being authored, or generation failed. The record returns to this state on failure.
generating_redacted_copy__sys: Generation is in progress.
complete__sys: Generation succeeded.
canceled__sys: The record was cancelled before generation completed.

When state__v is complete__sys, the redacted_document__sys field contains the version-specific reference to the redacted document:

Source: This version produced a Redacted Document.
Redacted: This document is a Redacted Document.

Offline Annotation Editing

Vault's offline annotation feature supports exporting and importing redaction annotations. Users can export a PDF with redaction annotations, modify the redaction annotations, and then import the marked up PDF back into Vault.

To edit redaction annotations outside of Vault:

Export Annotations: Use Export Document Annotations to PDF to download the annotated PDF. Your user must have the View Content permission on the latest document version and the Document: Download Rendition permission.
Mark Up Offline: Open the exported PDF in a supported PDF editor. Redaction annotations are preserved as PDF annotation objects.
Import Annotations: Use Import Document Annotations from PDF to bring the marked-up PDF back into Vault. Your user must be in a document role that grants the Redact permission.
On import, Vault maps each imported annotation to a redaction type by matching the annotation's overlay text against active redaction type names. If no match is found, the annotation resolves to Other. Annotations that fall back to Other and any page-level displacement issues are reported in the response as redaction_fallbacks (redaction type fallback count) and redaction_page_level (page-level displacement count).
Generate the Redacted Document: After import, use Generate or Update Redacted Copy to produce the redacted document.

Document Triggers for Redacted Document Versions

When the system generates a redacted document, entry actions do not execute.

Use a Doctype trigger instead of an entry action for any logic that must run when a redacted document version is created.