Reviews (HITL)

The human-in-the-loop (HITL) review queue allows analysts to manually verify, approve, reject, or modify PII findings before final redaction is applied. Reviews are created automatically when a job’s policy requires human review or when a finding’s confidence falls below a configurable threshold.

Review Object

Field	Type	Description
`id`	string	Unique review identifier
`job_id`	string	Associated job ID
`finding`	object	The PII finding under review
`status`	string	One of `pending`, `approved`, `rejected`, `modified`
`reviewer`	string	Reviewer identifier (null if pending)
`comment`	string	Optional reviewer comment
`created_at`	string	ISO 8601 timestamp
`resolved_at`	string	ISO 8601 timestamp (null if pending)

GET /reviews

List pending reviews for the current tenant.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status (default: `pending`)
`job_id`	string	No	Filter by job ID
`limit`	number	No	Max results (default: 50, max: 100)
`offset`	number	No	Pagination offset (default: 0)

Example


curl "https://api.pii-redactor.dev/api/v1/reviews?status=pending&limit=20" \
  -H "X-API-Key: pk_live_abc123"


[
  {
    "id": "rev_x1y2z3",
    "job_id": "job_8f3a1b2c4d5e",
    "finding": {
      "entity_type": "PERSON",
      "text": "Dr. Jane",
      "start": 15,
      "end": 23,
      "score": 0.62
    },
    "status": "pending",
    "reviewer": null,
    "comment": null,
    "created_at": "2026-02-13T10:00:00Z",
    "resolved_at": null
  }
]

GET /reviews/{review_id}

Get details of a specific review.

Example


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

Returns a single review object.

POST /reviews/{review_id}/approve

Approve a finding, confirming it is valid PII and should be redacted.

Request Body

Field	Type	Required	Description
`comment`	string	No	Optional reviewer comment

Example


curl -X POST https://api.pii-redactor.dev/api/v1/reviews/rev_x1y2z3/approve \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Confirmed as patient name"}'


{
  "id": "rev_x1y2z3",
  "status": "approved",
  "reviewer": "user_abc",
  "comment": "Confirmed as patient name",
  "resolved_at": "2026-02-13T10:05:00Z"
}

POST /reviews/{review_id}/reject

Reject a finding, indicating it is a false positive and should not be redacted.

Request Body

Field	Type	Required	Description
`comment`	string	No	Optional reviewer comment

Example


curl -X POST https://api.pii-redactor.dev/api/v1/reviews/rev_x1y2z3/reject \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"comment": "This is a product name, not a person"}'


{
  "id": "rev_x1y2z3",
  "status": "rejected",
  "reviewer": "user_abc",
  "comment": "This is a product name, not a person",
  "resolved_at": "2026-02-13T10:05:00Z"
}

POST /reviews/{review_id}/modify

Modify a finding by changing the entity type, boundaries, or redacted value.

Request Body

Field	Type	Required	Description
`entity_type`	string	No	Corrected entity type
`start`	number	No	Corrected start offset
`end`	number	No	Corrected end offset
`redacted`	string	No	Custom replacement value
`comment`	string	No	Optional reviewer comment

Example


curl -X POST https://api.pii-redactor.dev/api/v1/reviews/rev_x1y2z3/modify \
  -H "X-API-Key: pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "MEDICAL_PROFESSIONAL",
    "comment": "Reclassified from PERSON to MEDICAL_PROFESSIONAL"
  }'


{
  "id": "rev_x1y2z3",
  "status": "modified",
  "reviewer": "user_abc",
  "comment": "Reclassified from PERSON to MEDICAL_PROFESSIONAL",
  "resolved_at": "2026-02-13T10:05:00Z"
}