PHI Policy
The Decisions API is for de-identified questions. Don't send protected health information or anything that identifies a person.
What not to send
Describe the case, not the person. Leave out, in every field and every image:
- Names of patients, clients, case subjects, or their relatives and contacts (initials included).
- Dates tied to a person that are more precise than a year: birth, admission, discharge, service or death dates.
- Locations more specific than a US state: street addresses, cities, ZIP codes, facility names tied to a person.
- Contact details: phone and fax numbers, email addresses, URLs or handles that identify someone.
- Identifying numbers: Social Security, medical record, health plan, account, license, device or vehicle numbers.
- Ages over 89 (use "90 or older").
- Faces, and visible text in images such as names, dates of birth, record numbers or labels.
This applies to everything you send: input, JSON keys and values, question names and instructions, choice values and descriptions, level labels and descriptions, external_id, image URLs, and every image. Use an opaque external_id, never an MRN or a name.
How screening works
- Every request (preview, single-request escalation, sandbox and playground alike) is screened in full before anything is stored or returned: all text and JSON in every field, and every image.
- Screening is automated and probabilistic. It can miss identifiers and can flag text that isn't identifying (for example an eponym, or a date that refers to a study rather than a person).
- If any category is likely present, the request is rejected with
422 phi_detected. The response lists the categories, never the values it found. - If the screen can't reach a confident result for any reason, the request fails closed with
503 phi_screen_unavailable. Retry later; nothing was accepted. - On a rejection or a screening failure, nothing is stored: no decision, no ID, no images, and the request body isn't logged.
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "phi_detected",
"message": "the request appears to contain identifying information; remove it and retry",
"categories": ["name", "date"]
}
}| Category | Covers |
|---|---|
name | Names of a real person who appears to be a subject of the case, or their relatives or contacts. |
date | Person-linked dates more precise than a year. |
geography | Locations more specific than a US state. |
contact | Phone, fax, email and similar contact details. |
identifier | Record, account, plan, government and device numbers or codes. |
age_over_89 | An exact or inferable age above 89; the grouped category “90 or older” is allowed. |
image | Identifiable faces or identifying text visible in an image. |
New categories may be added; display unknown ones as-is.
If identifying information gets through
If a physician finds identifying information the screen missed, the decision is canceled with cancellation_reason: "phi_detected", any reservation is released, its content becomes unreadable immediately, and its content and images are deleted. Only non-content billing and audit records are kept. The decision.canceled webhook for it omits external_id.
Retention
| Record | What happens |
|---|---|
| Rejected or failed requests | Never stored. |
| Previews that are never escalated | Expire with their quote after 24 hours, then are deleted, with their images, 7 days later. After that the ID returns 404. |
| Canceled decisions | Content (input, questions, images, answers, references, external_id) is kept for 7 days, then deleted. Status, quote and timestamps are kept for billing and audit. |
| Canceled for identifying information | Content is blocked at once and deleted immediately. |
| Answered decisions | Retained as your record of the decision, including the physician's answer. |
Escalation stops the preview clock: an escalated decision is never deleted under the preview rule. See also the Privacy Policy.
Security
Data is encrypted in transit and at rest. Images are stored as normalized copies with all metadata removed, and are shown to the reviewing physician through time-limited signed links. A decision is visible only to the physicians eligible to answer it and to the Appendix staff who support the service.