Skip to main content

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.

You are responsible for what you send. By using the Decisions API you agree not to send protected health information or other identifying information (see the Developer Terms). Screening is a safety net, not a substitute for de-identifying your data before it leaves your system.

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.
Rejected request
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"]
  }
}
CategoryCovers
nameNames of a real person who appears to be a subject of the case, or their relatives or contacts.
datePerson-linked dates more precise than a year.
geographyLocations more specific than a US state.
contactPhone, fax, email and similar contact details.
identifierRecord, account, plan, government and device numbers or codes.
age_over_89An exact or inferable age above 89; the grouped category “90 or older” is allowed.
imageIdentifiable 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

RecordWhat happens
Rejected or failed requestsNever stored.
Previews that are never escalatedExpire with their quote after 24 hours, then are deleted, with their images, 7 days later. After that the ID returns 404.
Canceled decisionsContent (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 informationContent is blocked at once and deleted immediately.
Answered decisionsRetained 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.