PiiBlur

How to Automate PII Redaction with a REST API

PiiBlur Team6 min read

If your application handles user-uploaded photos, fleet footage, or visual content containing faces, license plates, or documents, you need a redaction step in your pipeline. Building PII detection from scratch means training models, managing infrastructure, and maintaining accuracy across 13+ categories. Or you call an API.

This guide covers integrating the PiiBlur REST API: uploading media, checking status, downloading results, setting up webhooks, and building a batch pipeline. All examples use cURL to stay language-agnostic. For the full endpoint reference, see the API documentation.

Authentication and Base URL

Every request requires a Bearer token. Generate an API key from your PiiBlur dashboard under Settings > API Keys.

curl -X GET https://api.piiblur.com/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response confirms your key and returns current usage and plan limits. All endpoints live under https://api.piiblur.com/v1/.

Uploading Media for PII Redaction

Submit an image or video with a multipart POST request. Specify which PII categories to redact, or omit the parameter to redact all detected categories.

curl -X POST https://api.piiblur.com/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=faces" \
  -F "categories[]=license_plates"

The response returns a job object with an id and a status of processing:

{
  "id": "job_8xKp2mNq",
  "status": "processing",
  "categories": ["faces", "license_plates"],
  "created_at": "2026-03-11T14:30:00Z"
}

Specify the redaction method — blur or pixelation — per category:

curl -X POST https://api.piiblur.com/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=faces" \
  -F "categories[]=documents" \
  -F "method=pixelation"

Images process in seconds. Video processing time depends on duration and resolution.

Checking Job Status

Poll the status endpoint to check completion:

curl -X GET https://api.piiblur.com/v1/media/job_8xKp2mNq \
  -H "Authorization: Bearer YOUR_API_KEY"

A completed job returns a download_url:

{
  "id": "job_8xKp2mNq",
  "status": "completed",
  "categories": ["faces", "license_plates"],
  "detections": {
    "faces": 3,
    "license_plates": 1
  },
  "download_url": "https://api.piiblur.com/v1/media/job_8xKp2mNq/download",
  "created_at": "2026-03-11T14:30:00Z",
  "completed_at": "2026-03-11T14:30:04Z"
}

The detections object reports how many instances of each category were found and redacted — useful for logging and audit trails.

Downloading Redacted Output

Fetch the redacted file with a GET request to the download URL:

curl -X GET https://api.piiblur.com/v1/media/job_8xKp2mNq/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o redacted_photo.jpg

Download URLs expire after 24 hours. Store the redacted file in your own storage as part of your pipeline.

Using Webhooks Instead of Polling

Polling works for simple integrations, but webhooks suit production systems better. Register a webhook URL, and PiiBlur POSTs to your endpoint when a job completes.

Configure your webhook URL in the dashboard under Settings > Webhooks, or pass it per request:

curl -X POST https://api.piiblur.com/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=faces" \
  -F "categories[]=license_plates" \
  -F "webhook_url=https://your-app.com/webhooks/piiblur"

The webhook payload matches the job status response, so your handler uses the same parsing logic. Verify the X-PiiBlur-Signature header to confirm the request originated from PiiBlur. Signature verification details are in the API documentation.

Building a Batch Processing Pipeline

Most production workloads process many files, not one at a time. A batch pipeline submits jobs in parallel and collects results via webhooks.

The workflow:

  1. Queue files. Your application collects files — from user uploads, a storage bucket, or a scheduled scan — and places them in a processing queue.
  2. Submit jobs in parallel. POST each file to the media endpoint. The API accepts concurrent requests within your plan's rate limits.
  3. Receive webhook callbacks. As each job completes, PiiBlur sends the result to your webhook endpoint.
  4. Store redacted output. Your webhook handler downloads the redacted file and writes it to storage.
  5. Handle failures. If a job fails, the webhook payload includes an error message. Retry with exponential backoff.

This pattern scales to any volume. A pipeline processing 10,000 images per day follows the same logic as one processing 10 — only concurrency and queue management differ.

For high-throughput integrations, see the API documentation for rate limits and recommended concurrency settings per plan tier.

Choosing PII Categories for Your Use Case

PiiBlur detects 13 PII categories: faces, license plates, screens, documents, street signs, ID cards, passports, credit cards, name badges, QR codes, barcodes, and tattoos. Not every use case requires all of them.

Select categories based on your data and compliance requirements:

  • User-uploaded photos — faces and documents are usually the priority
  • Street-level imagery — faces, license plates, and street signs
  • Fleet dashcam footage — faces, license plates, and screens
  • Real estate photography — faces, screens, and name badges
  • Healthcare facility footage — faces, ID cards, name badges, and documents

Specifying only the categories you need keeps processing fast and avoids over-redaction.

For large batch workflows, category selection also affects cost — fewer categories mean faster processing and lower per-image compute.

Error Handling

The API returns standard HTTP status codes. Handle these in your integration:

  • 400 — invalid request (missing file, unsupported format, or invalid category)
  • 401 — invalid or expired API key
  • 413 — file exceeds your plan's size limit
  • 429 — rate limit exceeded; back off and retry
  • 500 — server error; retry with exponential backoff

Check the response status before assuming success. In production, log the full response body on errors to aid debugging.

Pricing and Rate Limits

PiiBlur's free tier includes 100 images and 5 minutes of video per month — enough to build and test your integration. Paid plans start at $49/month and scale to $499/month for high-volume operations. Each tier increases rate limits, file size caps, and monthly quotas.

Full plan details are on the pricing page.

Start Building

The fastest way to evaluate the API: process a few of your own images. Grab an API key from the dashboard, run the upload cURL example above, and inspect the output. Then wire up webhooks, build your batch queue, and deploy. The API documentation covers every endpoint, parameter, and response format.