Configuration

Manage custom recognizers, webhooks, and allowlists/blocklists to fine-tune PII detection behavior.

Custom Recognizers

Custom recognizers extend the built-in PII detection with your own patterns. Useful for detecting organization-specific identifiers such as internal employee IDs, account numbers, or proprietary codes.

Recognizer Object

Field	Type	Description
`id`	string	Unique recognizer identifier
`name`	string	Human-readable name
`type`	string	`regex` or `phrase_list`
`entity_type`	string	Entity type label to assign
`patterns`	string[]	Regex patterns (for `regex` type)
`phrases`	string[]	Exact phrases (for `phrase_list` type)
`score`	number	Confidence score to assign (0.0-1.0)
`created_at`	string	ISO 8601 timestamp

POST /config/recognizers

Create a custom recognizer.


curl -X POST https://api.pii-redactor.dev/api/v1/config/recognizers \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employee ID",
    "type": "regex",
    "entity_type": "EMPLOYEE_ID",
    "patterns": ["EMP-\\d{6}"],
    "score": 0.95
  }'


{
  "id": "rec_a1b2c3",
  "name": "Employee ID",
  "type": "regex",
  "entity_type": "EMPLOYEE_ID",
  "patterns": ["EMP-\\d{6}"],
  "score": 0.95,
  "created_at": "2026-02-13T10:00:00Z"
}

GET /config/recognizers

List all custom recognizers for the current tenant.


curl https://api.pii-redactor.dev/api/v1/config/recognizers \
  -H "X-API-Key: pk_live_abc123"

GET /config/recognizers/{id}

Get a specific recognizer.


curl https://api.pii-redactor.dev/api/v1/config/recognizers/rec_a1b2c3 \
  -H "X-API-Key: pk_live_abc123"

PUT /config/recognizers/{id}

Update a recognizer. Only provided fields are updated.


curl -X PUT https://api.pii-redactor.dev/api/v1/config/recognizers/rec_a1b2c3 \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"patterns": ["EMP-\\d{6}", "EMPL-\\d{8}"]}'

DELETE /config/recognizers/{id}

Soft-delete a recognizer. It will no longer be used in detection but remains in audit logs.


curl -X DELETE https://api.pii-redactor.dev/api/v1/config/recognizers/rec_a1b2c3 \
  -H "X-API-Key: pk_live_abc123"


{
  "detail": "Recognizer deleted"
}

Webhooks

Configure webhook endpoints to receive notifications when events occur, such as job completion or failure.

Webhook Object

Field	Type	Description
`id`	string	Unique webhook identifier
`url`	string	HTTPS endpoint to receive POST requests
`events`	string[]	Events to subscribe to
`secret`	string	Signing secret for payload verification
`active`	boolean	Whether the webhook is active
`created_at`	string	ISO 8601 timestamp

Supported Events

Event	Description
`job.completed`	A redaction job finished successfully
`job.failed`	A redaction job failed

POST /config/webhooks

Create a webhook.


curl -X POST https://api.pii-redactor.dev/api/v1/config/webhooks \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/pii-redactor",
    "events": ["job.completed", "job.failed"]
  }'


{
  "id": "wh_d4e5f6",
  "url": "https://example.com/webhooks/pii-redactor",
  "events": ["job.completed", "job.failed"],
  "secret": "whsec_a1b2c3d4e5f6",
  "active": true,
  "created_at": "2026-02-13T10:00:00Z"
}

The secret is returned only on creation. Use it to verify webhook payloads by computing an HMAC-SHA256 of the request body and comparing it to the X-Webhook-Signature header.

GET /config/webhooks

List all webhooks.


curl https://api.pii-redactor.dev/api/v1/config/webhooks \
  -H "X-API-Key: pk_live_abc123"

PUT /config/webhooks/{id}

Update a webhook.


curl -X PUT https://api.pii-redactor.dev/api/v1/config/webhooks/wh_d4e5f6 \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"events": ["job.completed"]}'

DELETE /config/webhooks/{id}

Soft-delete a webhook. It will stop receiving events.


curl -X DELETE https://api.pii-redactor.dev/api/v1/config/webhooks/wh_d4e5f6 \
  -H "X-API-Key: pk_live_abc123"

Allowlist / Blocklist

Control which terms are always allowed (never redacted) or always blocked (always redacted), regardless of detection confidence.

Allowlist/Blocklist Object

Field	Type	Description
`id`	string	Unique entry identifier
`type`	string	`allow` or `block`
`value`	string	The term or pattern
`entity_type`	string	Applicable entity type (or `*` for all)
`created_at`	string	ISO 8601 timestamp

POST /config/allowlist

Create an allowlist entry.


curl -X POST https://api.pii-redactor.dev/api/v1/config/allowlist \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "Acme Corporation",
    "entity_type": "ORGANIZATION"
  }'


{
  "id": "al_g7h8i9",
  "type": "allow",
  "value": "Acme Corporation",
  "entity_type": "ORGANIZATION",
  "created_at": "2026-02-13T10:00:00Z"
}

GET /config/allowlist

List all allowlist and blocklist entries.


curl https://api.pii-redactor.dev/api/v1/config/allowlist \
  -H "X-API-Key: pk_live_abc123"

PUT /config/allowlist/{id}

Update an entry.


curl -X PUT https://api.pii-redactor.dev/api/v1/config/allowlist/al_g7h8i9 \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"value": "Acme Corp"}'

DELETE /config/allowlist/{id}

Soft-delete an entry.


curl -X DELETE https://api.pii-redactor.dev/api/v1/config/allowlist/al_g7h8i9 \
  -H "X-API-Key: pk_live_abc123"


{
  "detail": "Entry deleted"
}