> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHI Guard

> PHI detection modes (redact / block), what's enforced in every mode, and where audit events land.

Every AI request on the HASP platform flows through PHI Guard before it reaches an upstream model. PHI Guard is a mandatory compliance layer — it cannot be disabled — and it operates on the raw message content before any inference is performed.

## What it does

PHI Guard scans outbound messages for Protected Health Information (PHI) using a combination of statistical NER and rule-based detectors (powered by Microsoft Presidio). On detection, it applies your org's configured `phi_mode`.

## phi\_mode values

| Mode               | Behavior                                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redact` (default) | Detected PHI entities are replaced with placeholders (e.g., `[PERSON]`, `[US_SSN]`) before the message is sent upstream. The response streams normally. The stored message row contains both the original encrypted content and the redaction metadata. |
| `block`            | Any message containing PHI returns `403 PHI_BLOCKED` immediately — no inference is performed. The error response includes `details.entity_types` listing what was detected.                                                                             |

`phi_mode=off` is not a valid state. Every organization operates under a compliance posture.

Configure `phi_mode` in **Settings → AI Workspace → PHI Mode**.

## What counts as PHI

The scanner detects the 18 HIPAA identifier categories, including:

* Names, geographic data, dates (other than year), phone numbers, fax numbers
* Email addresses, SSNs, medical record numbers, account numbers
* Certificate/license numbers, vehicle identifiers, device identifiers
* URLs, IP addresses, biometric identifiers, full-face photos

## PHI\_BLOCKED error (phi\_mode=block)

```json theme={null}
{
  "success": false,
  "error": {
    "code": "PHI_BLOCKED",
    "type": "forbidden",
    "message": "Message contains PHI that cannot be sent without redaction.",
    "param": "messages[0].content",
    "details": {
      "entity_types": ["US_SSN", "PERSON"]
    },
    "retryable": false,
    "request_id": "req_01JQREQ000000000000000000",
    "docs_hint": "https://docs.usehasp.com/ai-api/concepts/phi-guard"
  },
  "meta": { "request_id": "req_01JQREQ000000000000000000" }
}
```

## Tool schema scanning

PHI Guard also scans tool definitions (function schemas) passed in the request. If a tool name, description, or parameter description contains PHI, the request is rejected with `400 PHI_IN_TOOL_SCHEMA` regardless of `phi_mode`. This rule cannot be relaxed — tool schemas are stored in plaintext in the model provider's infrastructure and are not subject to the redaction pipeline.

## PHI Guard on /v1/messages (Anthropic-compat)

PHI Guard applies identically on the Anthropic-compat endpoint. The error shape uses the HASP envelope with Anthropic-compatible `type: "invalid_request_error"` for `PHI_IN_TOOL_SCHEMA`; `PHI_BLOCKED` returns `403` using the standard HASP error envelope (not Anthropic's shape, since Anthropic has no equivalent concept).

## Audit trail

Every PHI scan result — regardless of whether PHI was found — is recorded in the HIPAA audit log. The AI gateway writes an audit event for each of the three pipeline phases: pre-flight, scan, and post-stream credit deduction. Audit records are available via [GET /v1/audit](/ai-api/control/audit) and in **Settings → Compliance → Audit Log**.