# Patient Vault

> The patient database for your healthcare app. A canonical, HIPAA-compliant
> patient record exposed as a simple API. SOC 2 Type II. BAA executed at production activation.
> Free for your first 1,000 patients, then $1/patient/year.

Patient Vault is the developer-facing patient database service of 1health.
You build the workflow your users came for; Patient Vault holds the patient
data underneath it. It speaks FHIR (R4/R5) on the wire and adds the parts FHIR
leaves to you: identity, audit, BAA, and isolation.

## Base URL
https://api.1health.io/v2

## Authentication
Bearer token. Pass your API key in the Authorization header:
  Authorization: Bearer <YOUR_API_KEY>
Create a key at signup (no card required). Headless signup is supported for agents.

## The model: SAFE (four primitives)
- Store  — create a patient (POST /patient), returns a server-assigned patientId
- Attach — attach documents, observations, wearables, structured data, addresses,
           aliases, identifiers, and contacts to a patient
- Find   — match a patient by demographics (exact or scored candidates)
- Echo   — read the full patient record with all attached data

## Endpoints
POST /patient — Create a patient. Returns a server-assigned patientId.
    required: firstName, lastName, dob, sex_at_birth
    optional: middleName, prefix, suffix
POST /patient/{id}/address — Attach a postal address to a patient.
    required: line1, city, state, postalCode
    optional: line2, country, use
GET /patient/{id}/alias — List all active name aliases for a patient.
POST /patient/{id}/alias — Attach an alternate patient name. Type and at least one name field are required.
    required: type
    optional: alias, firstName, lastName, fullName, effectiveFrom, effectiveTo
GET /patient/{id}/identifier — List external identities for a patient.
    optional: active
POST /patient/{id}/identifier — Attach an external identity. Authority is optional; the API uses CONEXT and Unknown defaults when omitted.
    required: value
    optional: type, authority_organization_id, authority_organization_name, authority_external_system_id, authority_external_system_name, source_name, active_from, active_until
POST /patient/{id}/contact — Attach a phone or email contact point.
    required: system, value
    optional: use
GET /patient/find — Match a patient by demographics.
    optional: firstName, lastName, dob, sexAtBirth, exact
POST /patient/{id}/document — Attach a document, observation, wearable, or structured payload to a patient.
    required: type
    optional: contentType, payload, title
GET /patient/{id}/document — List documents attached to a patient, optionally filtered by kind.
    optional: type, createdAfter, filename
GET /patient/{id} — Read the full patient record with all attached data.

## Idempotency & errors
- Writes return the created/updated resource. Validation failures return 400 with
  { error, message, fields }. Missing/invalid keys return 401.
- Reads on existing patients always work, even past the free tier.

## Limits & pricing
- Free: first 1,000 patients, forever, no card.
- $1 per patient per year after 1,000. 1 GB attached data per patient included.
- Files: any type, virus-scanned, 50 MB each.

## Data portability
Export anytime in FHIR R4 or R5 with full provenance:
  GET /patient/{id}/export?format=fhir-r4

## Machine-readable specs
- /llms.txt        this file
- /openapi.json    full OpenAPI 3.1 spec (generated from the same definitions)
- /agent-brief     structured JSON brief: model, auth, endpoints, examples

## FAQ
Q: Can't I just use FHIR?
A: FHIR is the wire format. Patient Vault is the record. Building on raw FHIR means brokering BAAs, building identity infrastructure, instrumenting audit, and chasing endpoints — five months of work before your first feature. Patient Vault speaks FHIR on the wire, but adds the parts FHIR doesn't. If you want to spend your seed round building patient-record infrastructure, FHIR is a fine choice. If you'd rather spend it on the product your users came for, Patient Vault is the substrate.

Q: How does Patient Vault relate to 1health?
A: Patient Vault is the developer-facing patient database service of 1health. The broader 1health platform includes the MCP Explorer, the API Reference, case studies, and other services built on the same canonical data model. Patient Vault is the first service designed for self-serve developer access. Visit dev.1health.io to see the rest of the platform.

Q: How is this different from an EHR?
A: An EHR is a clinical workflow product with a database underneath. Patient Vault is just the database — the canonical record — exposed as an API. You build the workflow your users came for; we hold the patient data underneath it. No clinician UI, no scheduling, no billing — those are your product, not ours.

Q: Is this HIPAA-compliant out of the box?
A: Yes. Sandbox access is instant and requires no BAA. When you activate production, you click to accept the standard Business Associate Agreement. Patient Vault's signature is already on it, so there is no negotiation or countersignature step. Every read and write is logged to an audit trail your compliance reviewer can defend.

Q: How does the BAA work?
A: Sandbox access is instant and requires no BAA. You can start building and make authenticated Sandbox calls right away. When you activate production, you click to accept Patient Vault's standard Business Associate Agreement. Patient Vault's signature is already on it, so your acceptance executes the agreement — no negotiation and no countersignature. The full document is public at /baa, so you and your legal team can review it anytime before production activation. The terms are standard and do not change based on review. After activation, the executed BAA is downloadable as a PDF from your dashboard settings.

Q: What does it cost?
A: Free to start — your first 1,000 patients are free forever, no card required. At patient 1,001 you pay $1 per patient per year. No monthly minimums, no hidden fees. Talk to us when you get past 100K patients for enterprise pricing.

Q: Can I export my data?
A: Yes — portability is a design commitment, not an afterthought. Patient records outlive companies. Export is specified as GET /patient/{id}/export?format=fhir-r4: the full event stream as a FHIR R4 Bundle with provenance intact, not a snapshot. Specified in v1.1 ahead of implementation so you can build against a stable target.

Q: Who's already building on this?
A: Some of the largest payers in the US run critical care transition apps on Patient Vault — that's how the platform reaches 80M Americans today. You're building on the same substrate they trust, and your patient data lives in your own isolated vault alongside that scale.

Q: Does Patient Vault give me access to other developers' patient data?
A: No. Your patients live in your own isolated vault. You see only the patients you create. Cross-vault queries are not included.

Q: Is the free tier a limited version of the product?
A: No — it's the full product, not a stripped-down tier. From your first patient you get every endpoint and full Sandbox API access with no BAA required. The BAA executes when you activate production. Nothing in the API is gated. Your first 1,000 patients are free; at patient 1,001 you start paying $1 per patient per year. It's metered, not freemium — you're never on a lesser Patient Vault. Support moves from community to 1-business-day email once you're on the paid plan. Reads on existing patients keep working even if you stop paying.

Q: What kind of files can I attach?
A: Any file type — PDFs, images, audio, documents, structured data. Files are virus-scanned on upload and limited to 50 MB each. Attach as many as you need to each patient.

## More
Platform: https://dev.1health.io
BAA (public): https://pv.1health.io/baa