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 with a controlled preview step before permanent removal.

This separation makes every proposed match visible before the source text is removed. A person or an automated approval rule can advance the preview into the apply step, while the distinct endpoints keep preview files clearly separated from finished redacted documents.

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 displays 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. Literal values provide exact matching, custom regular expressions address organization-specific formats, and pdfRest's maintained presets cover common sensitive-data patterns without requiring teams to build and maintain those expressions themselves. Approved rules can then be reused consistently across recurring document workflows.

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 the matching results are visible. 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. Workflows can also pause between the calls when an authorized approval step is part of the organization's redaction policy. Once a rule set is approved, the same resource-ID chain supports automatic processing at scale.

Apply and Protect the Final PDF

The apply endpoint permanently removes the approved content from the PDF rather than covering it with a visual overlay. The resulting resource ID can move directly into encryption, permission restriction, archival, or delivery steps, allowing the redacted document to remain inside one controlled API workflow.

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 repeatable automation with controlled approvals. Review the current matching options and endpoint schemas in the Redact PDF API reference, or configure 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.