Search and redact PDFs

Document Engine lets you create redactions using simple text search rules. Any piece of text matching a provided query will be covered by redaction annotations. To create redactions, use the createRedactions action with a text strategy.

To learn more about redaction strategies, go to the API reference.

You can configure some visual aspects of the redaction annotation, including its background color and overlay text, by passing an optional content object to the createRedactions action. To learn more about all configurable options, refer to the API reference.

The following example redacts any occurrence of the phrase ACME Bank:

{
  type: "createRedactions",
  strategy: "text",
  strategyOptions: {
    text: "ACME Bank"
  }
}

Matching wrapped text with word_based

Use the word_based strategy when the text you want to redact may wrap across line breaks, tables, or columns. This strategy ignores whitespace between characters — including spaces, tabs, newlines, and Unicode space variants — but punctuation must still match exactly. Queries must be at least three characters long.

For example, a query for Smith, John matches Smith,\nJohn, but it won’t match Smith John because the comma is missing in the document text:

{
  type: "createRedactions",
  strategy: "word_based",
  strategyOptions: {
    word_based: "Smith, John"
  }
}

Applying redactions

After redaction annotations are created, they need to be applied to the document to effectively and permanently remove the covered content. You can achieve this by adding the applyRedactions action to the /build instructions.

• Ensure Document Engine is up and running.
• Send a multipart POST request(opens in a new tab) with instructions to Document Engine’s /api/build endpoint.

For more information, refer to the API reference to learn about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

For an overview of multipart requests, refer to the brief tour of multipart requests blog post.

Creating and Applying Redactions in a File on Disk

Send a multipart request to the /api/build endpoint attached with the input file and the instructions JSON:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F file=@/path/to/example-document.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "actions": [
        {
          type: "createRedactions",
          strategy: "text",
          strategyOptions: {
            text: "ACME Bank"
          }
        },
        {
          "type": "applyRedactions"
        }
      ]
    }
  ]
}' \
  -o result.pdf

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="file"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "document",
      "actions": [
        {
          type: "createRedactions",
          strategy: "text",
          strategyOptions: {
            text: "ACME Bank"
          }
        },
        {
          "type": "applyRedactions"
        }
      ]
    }
  ]
}
--customboundary--

This creates redaction annotations and applies them to the file, removing the content beneath them.

Creating and Applying Redactions in a File from a URL

Send a request to the /api/build endpoint and include a URL pointing to the file you want to redact:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F instructions='{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/credit-card-application.pdf"
      },
      "actions": [
        {
          type: "createRedactions",
          strategy: "text",
          strategyOptions: {
            text: "ACME Bank"
          }
        },
        {
          "type": "applyRedactions"
        }
      ]
    }
  ]
}' \
  -o result.pdf

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/credit-card-application.pdf"
      },
      "actions": [
        {
          type: "createRedactions",
          strategy: "text",
          strategyOptions: {
            text: "ACME Bank"
          }
        },
        {
          "type": "applyRedactions"
        }
      ]
    }
  ]
}
--customboundary--

This creates redaction annotations and applies them to the file, removing the content beneath them.