How to Redact PDF Text with cURL

Learn how to use cURL to redact text on a PDF document with the pdfRest Redact PDF API tool.
Share this page

Permanently Redact PDF Text with cURL

Covering text with a visible box is not sufficient when confidential information must be removed from a PDF. The pdfRest Redact PDF API Tool uses a two-stage workflow: first preview the text that matches your rules, then apply the approved redactions so the selected content is permanently removed. This gives your application an API-driven way to find repeated sensitive values across large document sets while retaining a deliberate validation step before removal.

This separation gives an application a quality-control checkpoint. A person can inspect the preview, or an automated workflow can validate the proposed matches, before the source text is removed. It also prevents a preview file from being mistaken for a finished redacted document.

For example, a legal-records workflow can search a set of documents for email addresses and client identifiers before files are released outside the case team. The preview call lets a reviewer confirm the matches, and the apply call then produces copies in which the approved values are permanently removed.

Define the Text to Redact

The redactions field is a JSON array. Each object uses one of three matching methods:

  • literal finds an exact name, identifier, phrase, or other known string.
  • regex finds text that follows a custom pattern.
  • preset applies a maintained pattern for common data such as email addresses, phone numbers, dates, U.S. Social Security numbers, payment-card numbers, bank-routing numbers, IBANs, SWIFT/BIC numbers, URLs, and IP addresses.

The methods can be combined in the same request. Test literal matching for capitalization and spacing, and test regular expressions against representative documents to avoid missed values or overly broad matches. pdfRest's maintained presets reduce the need to create and maintain regular expressions for common sensitive-data formats yourself, while literal and custom regex rules preserve the flexibility needed for organization-specific data. Every result should still be validated against the documents in your workflow.

cURL Preview-and-Apply Example

The current official sample requires cURL and jq. Replace the API-key and file-path placeholders before running it. The example sends the source PDF and redaction rules to the preview endpoint, reads the returned outputId, and supplies that ID to the applied-redaction endpoint.

#!/bin/sh

# This sample demonstrates the workflow from unredacted document to fully
# redacted document. The output file from the preview tool is immediately
# forwarded to the finalization stage. We recommend inspecting the output from
# the preview stage before utilizing this workflow to ensure that content is
# redacted as intended.

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

API_KEY="xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # place your api key here
REDACTIONS='[{"type":"regex","value":"[Tt]he"}]'
PREVIEW_OUTPUT=$(curl -X POST "$API_URL/pdf-with-redacted-text-preview" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: $API_KEY" \
  -F "file=@/path/to/file" \
  -F "redactions=$REDACTIONS" \
  -F "output=example_out")

PREVIEW_PDF_ID=$(jq -r '.outputId' <<< $PREVIEW_OUTPUT)

echo $PREVIEW_OUTPUT | jq -r '.'

APPLIED_OUTPUT=$(curl -X POST "$API_URL/pdf-with-redacted-text-applied" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: $API_KEY" \
  -F "id=$PREVIEW_PDF_ID" \
  -F "output=example_out")

echo $APPLIED_OUTPUT | jq -r '.'

# All files uploaded or generated are automatically deleted based on the
# File Retention Period as shown on https://pdfrest.com/pricing.
# For immediate deletion of files, particularly when sensitive data
# is involved, an explicit delete call can be made to the API.

# Optional deletion step — OFF by default.
# Deletes all files in the workflow, including outputs. Save all desired files before enabling this step.
# Enable by uncommenting the next line to delete sensitive files
# DELETE_SENSITIVE_FILES=true
if [ "$DELETE_SENSITIVE_FILES" = "true" ]; then
  INPUT_PDF_ID=$(jq -r '.inputId' <<< $PREVIEW_OUTPUT)
  APPLIED_PDF_ID=$(jq -r '.outputId' <<< $APPLIED_OUTPUT)
  curl -X POST "$API_URL/delete" \
    -H "Accept: application/json" \
    -H "Content-Type: multipart/form-data" \
    -H "Api-Key: $API_KEY" \
    -F "ids=$INPUT_PDF_ID, $PREVIEW_PDF_ID, $APPLIED_PDF_ID" | jq -r '.'
fi

Source: pdfRest Redact PDF cURL complex-flow sample on GitHub

If the source PDF already has a pdfRest resource ID, the preview and apply requests can also use JSON payloads. See the redaction preview JSON-payload sample and the applied redaction JSON-payload sample.

Preview Before Applying Permanent Redactions

The first POST request calls /pdf-with-redacted-text-preview. Its output PDF marks the selected areas so you can verify what the rules found. The script captures the JSON response, uses jq to read its outputId, and stores that ID in PREVIEW_PDF_ID. Because both redaction stages use pdfRest resource IDs, your application can complete the workflow without downloading and re-uploading the preview between calls.

The second request sends PREVIEW_PDF_ID to /pdf-with-redacted-text-applied. This is the step that permanently removes the identified text. The applied endpoint can also accept the optional rgb_color parameter when the final redaction blocks should use a color other than the default black.

The official sample immediately forwards the preview into the apply call to demonstrate the complete API chain. For a new rule set, first pause between those calls and inspect the preview PDF. Automate immediate application only after the matching rules have been tested on the layouts, fonts, languages, and data formats the system will process.

Verify and Protect the Final PDF

After applying redactions, download and test the final PDF. Confirm that sensitive values cannot be found through text search, selection, copying, extraction, or downstream processing, and confirm that necessary surrounding content remains readable. Redaction can support an organization's privacy and security controls, but the organization is responsible for defining what must be removed and validating the result.

Keep the API key in an environment variable or secret manager rather than committed source code. Limit access to source and preview files because both can contain unredacted information. The sample also includes an optional call to the Delete Files endpoint; save any required outputs before enabling it, and never delete the preview resource before the applied-redaction call has completed.

With exact matches, custom patterns, maintained presets, a reviewable preview, and permanent application in one API workflow, Redact PDF supports both repeatable automation and careful quality control. Review the current matching options and endpoint schemas in the Redact PDF API reference, or test rules interactively in API Lab.

Generate a self-service API Key now!
Create your FREE API Key to start processing PDFs in seconds, only possible with pdfRest.