**Source URL:** https://limited.veevavault.dev/quality/vault-api/guides/document-redactions

# 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](https://platform.veevavault.help/en/lr/11989742).

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](https://platform.veevavault.help/en/lr/11989742).

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](https://platform.veevavault.help/en/lr/11989742).

## Create a Redaction Annotation

Use the [Create Multiple Annotations](/quality/vault-api/api-reference/26.3/documents/document-annotations/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](/quality/vault-api/api-reference/26.3/documents/document-annotations/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.

```json
[
  {
    "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:

```sql
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](/quality/vault-api/api-reference/26.3/object-lifecycle-workflows/object-record-user-actions/generate-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](/quality/vault-api/api-reference/26.3/vault-objects/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](https://platform.veevavault.help/en/lr/23833) 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:

<Steps>
1.  **Export Annotations:** Use [Export Document Annotations to PDF](/quality/vault-api/api-reference/26.3/documents/document-annotations/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.
2.  **Mark Up Offline:** Open the exported PDF in a supported PDF editor. Redaction annotations are preserved as PDF annotation objects.
3.  **Import Annotations:** Use [Import Document Annotations from PDF](/quality/vault-api/api-reference/26.3/documents/document-annotations/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).
4.  **Generate the Redacted Document:** After import, use [Generate or Update Redacted Copy](/quality/vault-api/api-reference/26.3/object-lifecycle-workflows/object-record-user-actions/generate-redacted-copy) to produce the redacted document.
</Steps>

### Document Triggers for Redacted Document Versions

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

Use a [Doctype trigger](/quality/vault-sdk/entry-points/triggers/doctype-triggers/) instead of an entry action for any logic that must run when a redacted document version is created.

---

**Previous:** [Creating & Downloading Documents in Bulk](/quality/vault-api/guides/creating-documents-bulk)  
**Next:** [Postman Collection](/quality/vault-api/guides/postman-collection)