{"name":"Patient Vault","tagline":"The patient database for your healthcare app.","summary":"A canonical, HIPAA-compliant patient record exposed as a simple REST API. Speaks FHIR (R4/R5) on the wire; adds identity, audit, BAA, and per-tenant isolation. The developer-facing patient database service of 1health.","baseUrl":"https://api.1health.io/v2","auth":{"type":"bearer","header":"Authorization: Bearer <YOUR_API_KEY>","howToGetKey":"Create a key at signup (no card required). Headless/programmatic signup is supported for agents — no browser, no human."},"model":{"name":"SAFE","description":"Four primitives cover the entire surface.","primitives":[{"letter":"S","name":"Store","description":"Create a patient. Returns a server-assigned patientId."},{"letter":"A","name":"Attach","description":"Attach documents, observations, wearables, structured data, addresses, aliases, identifiers, and contacts."},{"letter":"F","name":"Find","description":"Match a patient by demographics (exact or scored candidates)."},{"letter":"E","name":"Echo","description":"Read the full patient record with all attached data."}]},"conventions":{"idShape":"Patient ids are opaque strings, e.g. \"pt_a8f3c2b9d4e7\". Always use the server-assigned id.","writes":"Writes return the created/updated resource as JSON.","reads":"Reads on existing patients always succeed, even past the free tier.","dates":"Dates are ISO 8601 (YYYY-MM-DD).","contentType":"POST bodies are application/json."},"errors":{"shape":{"error":"string","message":"string","fields":"string[] (present on validation errors)"},"examples":[{"status":400,"error":"missing_required_fields","message":"Required field \"dob\" is missing.","fields":["dob"]},{"status":401,"error":"unauthorized","message":"Missing or invalid API key."}]},"limits":{"freeTier":"First 1,000 patients are free forever, no card required.","pricing":"$1 per patient per year after 1,000.","storage":"1 GB attached data per patient included.","files":"Any type, virus-scanned, 50 MB max each."},"export":{"description":"Export anytime in FHIR R4 or R5 with full provenance.","example":"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/export?format=fhir-r4"},"endpoints":[{"key":"patient","name":"Patient (Store)","safeLetter":"S","method":"POST","path":"/patient","needsPatient":false,"description":"Create a patient. Returns a server-assigned patientId.","fields":[{"name":"firstName","required":true,"in":"body","type":"string","example":"Maria"},{"name":"lastName","required":true,"in":"body","type":"string","example":"Santos"},{"name":"dob","required":true,"in":"body","type":"string (ISO 8601 date)","example":"1988-04-12","description":"ISO 8601 (YYYY-MM-DD)."},{"name":"sex_at_birth","required":true,"in":"body","type":"string","enum":["female","male","other","unknown"],"example":"female"},{"name":"middleName","required":false,"in":"body","type":"string","example":"Anne"},{"name":"prefix","required":false,"in":"body","type":"string","example":"Ms."},{"name":"suffix","required":false,"in":"body","type":"string","example":"Jr."}],"examplePath":"/patient","exampleCurl":"curl -X POST \"https://api.1health.io/v2/patient\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\",\n    \"dob\": \"1988-04-12\",\n    \"sex_at_birth\": \"female\"\n  }'"},{"key":"address","name":"Address","safeLetter":null,"method":"POST","path":"/patient/{id}/address","needsPatient":true,"description":"Attach a postal address to a patient.","fields":[{"name":"line1","required":true,"in":"body","type":"string","example":"742 Evergreen Terrace"},{"name":"city","required":true,"in":"body","type":"string","example":"Chicago"},{"name":"state","required":true,"in":"body","type":"string","example":"IL"},{"name":"postalCode","required":true,"in":"body","type":"string","example":"60614"},{"name":"line2","required":false,"in":"body","type":"string","example":"Apt 4B"},{"name":"country","required":false,"in":"body","type":"string","example":"US"},{"name":"use","required":false,"in":"body","type":"string","enum":["home","work","temp"]}],"examplePath":"/patient/pt_a8f3c2b9d4e7/address","exampleCurl":"curl -X POST \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/address\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"line1\": \"742 Evergreen Terrace\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"postalCode\": \"60614\"\n  }'"},{"key":"alias-list","name":"List aliases","safeLetter":null,"method":"GET","path":"/patient/{id}/alias","needsPatient":true,"description":"List all active name aliases for a patient.","fields":[],"examplePath":"/patient/pt_a8f3c2b9d4e7/alias","exampleCurl":"curl \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/alias\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\""},{"key":"alias","name":"Alias","safeLetter":null,"method":"POST","path":"/patient/{id}/alias","needsPatient":true,"description":"Attach an alternate patient name. Type and at least one name field are required.","fields":[{"name":"type","required":true,"in":"body","type":"string","enum":["maiden","nickname","preferred","previous","legal_change","alias"],"example":"alias"},{"name":"alias","required":false,"in":"body","type":"string","example":"Mari"},{"name":"firstName","required":false,"in":"body","type":"string","example":"Maria"},{"name":"lastName","required":false,"in":"body","type":"string","example":"Gutierrez"},{"name":"fullName","required":false,"in":"body","type":"string"},{"name":"effectiveFrom","required":false,"in":"body","type":"string"},{"name":"effectiveTo","required":false,"in":"body","type":"string"}],"examplePath":"/patient/pt_a8f3c2b9d4e7/alias","exampleCurl":"curl -X POST \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/alias\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"alias\"\n  }'"},{"key":"identifier-list","name":"List identities","safeLetter":null,"method":"GET","path":"/patient/{id}/identifier","needsPatient":true,"description":"List external identities for a patient.","fields":[{"name":"active","required":false,"in":"query","type":"string","enum":["true","false","all"],"example":"true"}],"examplePath":"/patient/pt_a8f3c2b9d4e7/identifier","exampleCurl":"curl \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/identifier\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\""},{"key":"identifier","name":"Identifier","safeLetter":null,"method":"POST","path":"/patient/{id}/identifier","needsPatient":true,"description":"Attach an external identity. Authority is optional; the API uses CONEXT and Unknown defaults when omitted.","fields":[{"name":"value","required":true,"in":"body","type":"string","example":"MRN-449120"},{"name":"type","required":false,"in":"body","type":"string","example":"mrn"},{"name":"authority_organization_id","required":false,"in":"body","type":"string"},{"name":"authority_organization_name","required":false,"in":"body","type":"string"},{"name":"authority_external_system_id","required":false,"in":"body","type":"string"},{"name":"authority_external_system_name","required":false,"in":"body","type":"string"},{"name":"source_name","required":false,"in":"body","type":"string"},{"name":"active_from","required":false,"in":"body","type":"string"},{"name":"active_until","required":false,"in":"body","type":"string"}],"examplePath":"/patient/pt_a8f3c2b9d4e7/identifier","exampleCurl":"curl -X POST \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/identifier\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"value\": \"MRN-449120\"\n  }'"},{"key":"contact","name":"Contact","safeLetter":null,"method":"POST","path":"/patient/{id}/contact","needsPatient":true,"description":"Attach a phone or email contact point.","fields":[{"name":"system","required":true,"in":"body","type":"string","enum":["phone","email"],"example":"phone"},{"name":"value","required":true,"in":"body","type":"string","example":"+1-312-555-0142"},{"name":"use","required":false,"in":"body","type":"string","enum":["mobile","home","work"]}],"examplePath":"/patient/pt_a8f3c2b9d4e7/contact","exampleCurl":"curl -X POST \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/contact\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"system\": \"phone\",\n    \"value\": \"+1-312-555-0142\"\n  }'"},{"key":"find","name":"Find","safeLetter":"F","method":"GET","path":"/patient/find","needsPatient":false,"description":"Match a patient by demographics.","fields":[{"name":"firstName","required":false,"in":"query","type":"string","example":"Maria"},{"name":"lastName","required":false,"in":"query","type":"string","example":"Santos"},{"name":"dob","required":false,"in":"query","type":"string (ISO 8601 date)","example":"1988-04-12"},{"name":"sexAtBirth","required":false,"in":"query","type":"string","enum":["female","male","intersex","unknown"]},{"name":"exact","required":false,"in":"query","type":"string","enum":["true","false"],"description":"true returns only full matches."}],"examplePath":"/patient/find?firstName=Maria&lastName=Santos&dob=1988-04-12","exampleCurl":"curl \"https://api.1health.io/v2/patient/find?firstName=Maria&lastName=Santos&dob=1988-04-12\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\""},{"key":"attach","name":"Attach","safeLetter":"A","method":"POST","path":"/patient/{id}/document","needsPatient":true,"description":"Attach a document, observation, wearable, or structured payload to a patient.","fields":[{"name":"type","required":true,"in":"body","type":"string","enum":["document","observation","wearable","structured"],"example":"document","description":"The kind of thing you are attaching. Distinct from Content type (the MIME type of an uploaded file)."},{"name":"contentType","required":false,"in":"body","type":"string","example":"application/pdf","description":"MIME type. Auto-filled from the file; editable for files the browser cannot detect (e.g. DICOM, which often reports blank or application/octet-stream)."},{"name":"payload","required":false,"in":"body","type":"string","description":"The structured body for this observation, wearable reading, or structured record."},{"name":"title","required":false,"in":"body","type":"string","example":"Intake form"}],"examplePath":"/patient/pt_a8f3c2b9d4e7/document","exampleCurl":"curl -X POST \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/document\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"document\"\n  }'"},{"key":"document-search","name":"Document Search","safeLetter":null,"method":"GET","path":"/patient/{id}/document","needsPatient":true,"description":"List documents attached to a patient, optionally filtered by kind.","fields":[{"name":"type","required":false,"in":"query","type":"string","enum":["document","observation","wearable","structured"],"description":"Filter by attachment kind. \"Any\" returns all kinds."},{"name":"createdAfter","required":false,"in":"query","type":"string (ISO 8601 date)","description":"Only documents created on or after this date."},{"name":"filename","required":false,"in":"query","type":"string","description":"Match documents whose title/filename contains this text."}],"examplePath":"/patient/pt_a8f3c2b9d4e7/document","exampleCurl":"curl \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7/document\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\""},{"key":"echo","name":"Echo","safeLetter":"E","method":"GET","path":"/patient/{id}","needsPatient":true,"description":"Read the full patient record with all attached data.","fields":[],"examplePath":"/patient/pt_a8f3c2b9d4e7","exampleCurl":"curl \"https://api.1health.io/v2/patient/pt_a8f3c2b9d4e7\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\""}],"specs":{"llmsTxt":"/llms.txt","openapi":"/openapi.json","agentBrief":"/agent-brief"},"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."}],"links":{"platform":"https://dev.1health.io","baa":"https://pv.1health.io/baa"}}