DeepRead PII — Document Redaction API

Your agent processes documents. Some of those documents contain names, SSNs, medical records, credit card numbers. Before that data flows to another API, a database, a teammate, or an LLM — it needs to be clean.

Input:  "Invoice to: John Smith, 123 Oak St, SSN: 456-78-9012, Card: 4532-1234-5678-9012"
Output: "Invoice to: ██████████, ██████████, SSN: ███████████, Card: ███████████████████"

One API call. Document in, redacted copy + detection report back.

DeepRead PII detects 14 types of personally identifiable information using context-aware AI — not regex. It knows "Dr. Sarah Chen" on a hospital letterhead is the physician (skip), but "Sarah Chen" on a patient intake form is the patient (redact). No regex rules to write. No word lists to maintain. No false positive floods.

> This skill instructs the agent to POST your file to https://api.deepread.tech, poll for results, and download the redacted copy. No system files are modified and no elevated permissions are requested.

What This Skill Does

• 14 PII types detected: Names, SSNs, credit cards, emails, phones, addresses, dates of birth, passport numbers, driver's licenses, bank accounts, IBANs, IPs, URLs, medical record numbers
• Black bar redaction: PII replaced with solid black bars — text physically removed from the PDF content stream, irreversible, not just a visual overlay
• Any document format: PDF (digital + scanned), PNG, JPEG, plain text
• Context-aware: AI distinguishes personal vs. institutional, patient vs. provider, form labels vs. actual values
• Audit trail: Every redaction logged with detection counts per type. See DeepRead's privacy policy for data handling details.
• Copy-paste proof: Redacted text cannot be recovered via copy-paste, text selection, or PDF parsing
• Free tier: 2,000 pages/month (no credit card required)
• Works with other DeepRead skills: Extract data with deepread-ocr, fill forms with deepread-form-fill, then redact the originals

Setup

1. Get Your API Key

Sign up and create an API key:

bash
# Visit the dashboard
https://www.deepread.tech/dashboard

# Or use this direct link
https://www.deepread.tech/dashboard/?utm_source=clawhub

Save your API key:

bash
export DEEPREAD_API_KEY="sk_live_your_key_here"

2. Configuration (Optional)

Add to your clawdbot.config.json5:

json5
{
  skills: {
    entries: {
      "deepread-pii": {
        enabled: true
        // API key is read from DEEPREAD_API_KEY environment variable
        // Do NOT hardcode your API key here
      }
    }
  }
}

3. Redact Your First Document

Option A: With Webhook (Recommended)

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@document.pdf" \
  -F "webhook_url=https://your-app.com/webhooks/pii"

# Returns immediately:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

# Your webhook receives results when processing completes

Option B: Poll for Results

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@patient_record.pdf"

# Returns immediately:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

# Poll until completed:
curl https://api.deepread.tech/v1/pii/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $DEEPREAD_API_KEY"

Usage Examples

Redact a PDF

Replaces all detected PII with solid black bars. Text is physically removed from the PDF content stream. Copy-paste cannot recover it.

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@contract.pdf"

Response when completed:

json
{
  "id": "550e8400-...",
  "status": "completed",
  "progress_percent": 100,
  "redacted_file_url": "https://...(signed URL)...",
  "report": {
    "id": "550e8400-...",
    "page_count": 5,
    "processing_time_ms": 3421,
    "pii_detected": {
      "NAME": {
        "count": 3,
        "pages": [1, 2],
        "confidence_avg": 0.92
      },
      "PHONE": {
        "count": 2,
        "pages": [1],
        "confidence_avg": 0.89
      },
      "EMAIL": {
        "count": 1,
        "pages": [2],
        "confidence_avg": 0.97
      }
    },
    "total_redactions": 6,
    "redaction_policy": "black_bar",
    "confidence_threshold_used": 0.85,
    "below_threshold_count": 0
  }
}

Redact an Image

Works on scanned documents, photos of IDs, screenshots — any PNG or JPEG.

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@drivers_license.png"

Vision AI detects PII in the image, locates exact positions, and draws black bars over the text.

Redact Plain Text

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@notes.txt"

Before: Patient John Smith, SSN 456-78-9012, called from (555) 867-5309 After: Patient ██████████, SSN ███████████, called from ██████████████

Multi-Language Support

Supports documents in English, Chinese, Spanish, Hindi, and Arabic.

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@documento.pdf" \
  -F "language=es"

Supported languages: en (default), zh, es, hi, ar

When to Use This Skill

Use DeepRead PII For:

• Before sharing documents externally — redact before sending to vendors, partners, opposing counsel
• Before feeding documents to LLMs — strip PII before sending content to any AI model
• Compliance workflows — GDPR right to erasure, HIPAA de-identification, CCPA requests
• Training data preparation — create clean datasets from real documents
• Insurance claims — redact claimant PII before adjuster handoff
• Legal discovery — privilege review with PII protection
• Medical records — de-identify patient data for research or sharing
• Financial documents — mask account numbers, SSNs on statements
• HR documents — clean employee files before audits

Don't Use For:

• Real-time processing — async workflow, not instant (use webhooks)
• Structured data extraction — use deepread-ocr skill for that, then redact
• Documents with no text — blank images or decorative PDFs

How It Works

3-Layer Detection Pipeline

Document → AI Detection → Threshold Filter → Context Validation → Redact

Layer 1: AI Detection

• Text documents: LLM scans for all 14 PII types with confidence scoring
• Images/scans: Vision model detects PII with precise bounding box coordinates
• Returns type, exact value, and confidence score (0.0–1.0) for each detection

Layer 2: Confidence Threshold

• Default threshold: 0.85
• Detections below threshold are recorded but NOT redacted
• Reported separately as below_threshold_count for manual review

Layer 3: Context-Aware Validation

• Second AI pass with full document context
• Filters false positives that regex-based tools can't handle:
• admissions@university.edu → institutional email, SKIP
• john.smith@gmail.com → personal email, REDACT
• "Dr. Sarah Chen" on letterhead → physician, SKIP
• "Sarah Chen" on intake form → patient, REDACT
• "Name:" (form label) → not PII, SKIP
• "John Smith" (form value) → PII, REDACT
• Invoice dates → not DOB, SKIP
• "Date of Birth: 03/15/1990" → DOB, REDACT

What Gets Detected

| PII Type | Examples | |----------|----------| | SSN | Social Security numbers, national IDs | | CREDIT_CARD | Card numbers, transaction IDs tied to a person | | EMAIL | Personal email addresses (not institutional) | | PHONE | Phone numbers (all country formats) | | NAME | Person names (all cultures/languages) | | ADDRESS | Physical addresses, postal codes | | IP_ADDRESS | IPv4 and IPv6 addresses | | DATE_OF_BIRTH | Birth dates (only when labeled as DOB — not random dates) | | PASSPORT_NUMBER | Passport numbers | | DRIVER_LICENSE | Driver's licenses, registration numbers | | BANK_ACCOUNT | Account numbers, routing numbers | | IBAN | International Bank Account Numbers | | URL | Personal URLs and web addresses | | MEDICAL_RECORD | Medical record numbers, patient IDs, hospital IDs |

PDF Redaction is Irreversible

• Digital PDFs: Text is physically removed from the PDF content stream using redaction annotations — not just covered
• Scanned PDFs: Pages are re-rendered as images with black bars, replacing the original
• All PDFs: Metadata stripped, content streams cleaned and deflated
• Copy-paste, text selection, and PDF parsing cannot recover redacted content

API Reference

POST /v1/pii/redact — Submit Document for Redaction

Auth: X-API-Key: YOUR_KEY Content-Type: multipart/form-data Rate Limit: 10 requests per 60 seconds

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | file | File | Yes | — | PDF, PNG, JPEG, or TXT (max 50MB) | | language | string | No | "en" | "en", "zh", "es", "hi", "ar" | | webhook_url | string | No | — | HTTPS URL for completion notification |

Response (200 OK):

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Errors: | Status | Code | Meaning | |--------|------|---------| | 400 | INVALID_REQUEST | Bad request parameters | | 400 | UNSUPPORTED_FORMAT | File type not supported | | 400 | EMPTY_DOCUMENT | File is empty | | 400 | DOCUMENT_CORRUPTED | File is corrupt or unreadable | | 400 | PASSWORD_PROTECTED | Document is password-protected | | 401 | UNAUTHORIZED | Invalid or missing API key | | 413 | FILE_TOO_LARGE | Exceeds 50MB size limit | | 429 | RATE_LIMITED | Rate limit exceeded | | 500 | INTERNAL_ERROR | Server error (retry or contact support) |

GET /v1/pii/{job_id} — Get Redaction Results

Auth: X-API-Key: YOUR_KEY Rate Limit: 60 requests per 60 seconds

Poll until status is completed or failed.

Response (completed):

json
{
  "id": "550e8400-...",
  "status": "completed",
  "progress_percent": 100,
  "redacted_file_url": "https://...(signed URL)...",
  "report": {
    "id": "550e8400-...",
    "page_count": 3,
    "processing_time_ms": 4200,
    "pii_detected": {
      "NAME": {
        "count": 4,
        "pages": [1, 2, 3],
        "confidence_avg": 0.93,
        "confidence_min": 0.87,
        "below_threshold": 0,
        "allowed": 0
      },
      "SSN": {
        "count": 1,
        "pages": [1],
        "confidence_avg": 0.98,
        "confidence_min": 0.98,
        "below_threshold": 0,
        "allowed": 0
      }
    },
    "total_redactions": 5,
    "redaction_policy": "black_bar",
    "confidence_threshold_used": 0.85,
    "below_threshold_count": 0
  },
  "error": null
}

Response (failed):

json
{
  "id": "550e8400-...",
  "status": "failed",
  "progress_percent": 0,
  "redacted_file_url": null,
  "report": null,
  "error": {
    "code": "DOCUMENT_CORRUPTED",
    "message": "Unable to process the document"
  }
}

Statuses: queued → processing → completed or failed

Code Examples

Python

python
import requests
import time

API_KEY = "sk_live_YOUR_KEY"
BASE = "https://api.deepread.tech"

# Submit document for redaction
with open("patient_record.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE}/v1/pii/redact",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
    )
job_id = resp.json()["id"]

# Poll with backoff
delay = 3
while True:
    time.sleep(delay)
    result = requests.get(
        f"{BASE}/v1/pii/{job_id}",
        headers={"X-API-Key": API_KEY}
    ).json()

    if result["status"] == "completed":
        # Download redacted file
        redacted_url = result["redacted_file_url"]
        redacted_pdf = requests.get(redacted_url).content
        with open("patient_record_redacted.pdf", "wb") as f:
            f.write(redacted_pdf)

        # Review detection report
        report = result["report"]
        print(f"Redacted {report['total_redactions']} PII instances")
        for pii_type, summary in report["pii_detected"].items():
            print(f"  {pii_type}: {summary['count']} found on pages {summary['pages']}")
        break

    elif result["status"] == "failed":
        print(f"Failed: {result['error']['message']}")
        break

    delay = min(delay * 1.5, 15)

JavaScript / Node.js

javascript
import fs from "fs";

const API_KEY = "sk_live_YOUR_KEY";
const BASE = "https://api.deepread.tech";

// Submit document
const form = new FormData();
form.append("file", fs.createReadStream("contract.pdf"));

const { id: jobId } = await fetch(`${BASE}/v1/pii/redact`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
  body: form,
}).then((r) => r.json());

// Poll with backoff
let delay = 3000;
let result;
do {
  await new Promise((r) => setTimeout(r, delay));
  result = await fetch(`${BASE}/v1/pii/${jobId}`, {
    headers: { "X-API-Key": API_KEY },
  }).then((r) => r.json());
  delay = Math.min(delay * 1.5, 15000);
} while (!["completed", "failed"].includes(result.status));

if (result.status === "completed") {
  console.log(`Redacted file: ${result.redacted_file_url}`);
  console.log(`Total redactions: ${result.report.total_redactions}`);
}

cURL

bash
# Redact a PDF
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@document.pdf"

# Redact a scanned image
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@id_card.png"

# Redact with language hint
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@documento.pdf" \
  -F "language=es"

# Check status
curl https://api.deepread.tech/v1/pii/JOB_ID \
  -H "X-API-Key: $DEEPREAD_API_KEY"

Workflows: Combine with Other DeepRead Skills

Extract Then Redact

Use deepread-ocr to extract data, then redact the original before archiving:

bash
# Step 1: Extract structured data (keeps the data you need)
curl -X POST https://api.deepread.tech/v1/process \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@claim.pdf" \
  -F 'schema={"type":"object","properties":{"claim_number":{"type":"string"},"amount":{"type":"number"}}}'

# Step 2: Redact PII from original (clean copy for filing)
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@claim.pdf"

Redact Before LLM Processing

Strip PII before sending document content to any AI model:

python
# 1. Redact the document
resp = requests.post(f"{BASE}/v1/pii/redact",
    headers={"X-API-Key": API_KEY},
    files={"file": open("report.pdf", "rb")})
job_id = resp.json()["id"]

# 2. Wait for completion, download redacted version
# 3. Now safe to send to any LLM for analysis

Fill Form Then Redact Copy

Use deepread-form-fill to complete a form, then redact a copy for records:

bash
# Step 1: Fill the form
curl -X POST https://api.deepread.tech/v1/form-fill \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@w4_form.pdf" \
  -F 'form_fields={"full_name":"Jane Smith","ssn":"456-78-9012"}'

# Step 2: Redact the filled form for internal records
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@w4_filled.pdf"

Best Practices

1. Use Webhooks for Production

bash
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: $DEEPREAD_API_KEY" \
  -F "file=@document.pdf" \
  -F "webhook_url=https://your-app.com/webhooks/pii"

Only use polling if you cannot expose a webhook endpoint.

2. Review the Detection Report

The report tells you exactly what was found and where:

python
report = result["report"]

# Check if anything was below confidence threshold
if report["below_threshold_count"] > 0:
    print(f"Warning: {report['below_threshold_count']} detections below threshold")
    print("Consider manual review of the original document")

# See breakdown by type
for pii_type, summary in report["pii_detected"].items():
    print(f"{pii_type}: {summary['count']} on pages {summary['pages']}")

3. Set Language for Non-English Documents

Always specify the language for better detection accuracy:

bash
-F "language=zh"   # Chinese
-F "language=es"   # Spanish
-F "language=hi"   # Hindi
-F "language=ar"   # Arabic

4. Polling Strategy

Poll every 3-5 seconds with backoff:

python
delay = 3
while True:
    time.sleep(delay)
    result = check_status(job_id)
    if result["status"] in ("completed", "failed"):
        break
    delay = min(delay * 1.5, 15)  # cap at 15s

Rate Limits & Pricing

Free Tier (No Credit Card)

• 2,000 pages/month
• 10 requests/minute (redact endpoint)
• 60 requests/minute (status endpoint)
• Full feature access

Paid Plans

• PRO: 50,000 pages/month, 100 req/min @ $99/mo
• SCALE: Custom volume pricing

Upgrade: https://www.deepread.tech/dashboard/billing?utm_source=clawhub

Troubleshooting

Error: UNSUPPORTED_FORMAT

Solution: Only PDF, PNG, JPEG, and TXT are supported. Convert other formats first.

Error: EMPTY_DOCUMENT

Solution: File has no content. Check the file is not corrupted or zero-bytes.

Error: FILE_TOO_LARGE

Solution: Compress the file or split into smaller documents. Max 50MB.

No PII detected in report

Possible causes:

• Document genuinely contains no PII
• PII is in a language not specified (set language parameter)
• Image quality too low for detection (try higher resolution scan)

Redaction missed some PII

Possible causes:

• Value was below the 0.85 confidence threshold (check below_threshold_count)
• Unusual formatting or handwritten text
• Report the issue: https://github.com/deepread-tech/deep-read-service/issues

Security Notes

• This skill only calls https://api.deepread.tech — no other endpoints are contacted
• Documents are uploaded to DeepRead servers for processing and redacted copies are returned via signed URLs
• This skill does not modify any system files, install packages, or request elevated permissions
• Keep DEEPREAD_API_KEY secret — rotate if compromised
• If using webhooks, ensure your receiving endpoint uses HTTPS and is authenticated
• Test with non-sensitive documents first to verify behavior
• Review DeepRead's privacy policy for data retention and handling details

Related DeepRead Skills

DeepRead is three tools with one API key:

| Skill | What it does | Install | |-------|-------------|---------| | deepread-ocr | Extract text + structured JSON from any document. 97%+ accuracy. | clawhub install uday390/deepread-ocr | | deepread-form-fill | Fill any PDF form with AI vision — scanned forms, government PDFs | clawhub install uday390/deepread-form-fill | | deepread-pii | Redact sensitive data. This skill. | You're here |

Common pipeline: Extract data (OCR) → Fill target form (Form Fill) → Redact originals for filing (PII)

Support & Resources

• Dashboard: https://www.deepread.tech/dashboard
• Issues: https://github.com/deepread-tech/deep-read-service/issues
• Email: hello@deepread.tech

Ready to start? Get your free API key at https://www.deepread.tech/dashboard/?utm_source=clawhub