{"openapi":"3.1.0","info":{"title":"Patient Vault","version":"2.2","description":"The patient database for your healthcare app. A canonical, HIPAA-compliant patient record exposed as a simple REST API, built on four primitives — Store, Attach, Find, Echo (SAFE). SOC 2 Type II; BAA executed at production activation. Free for your first 1,000 patients.","contact":{"name":"1health Developer Relations","url":"https://dev.1health.io","email":"devrel@1health.io"}},"servers":[{"url":"https://api.1health.io/v2","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}}},"paths":{"/patient":{"post":{"operationId":"patient","summary":"Create a patient. Returns a server-assigned patientId.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstName","lastName","dob","sex_at_birth"],"properties":{"firstName":{"type":"string","example":"Maria"},"lastName":{"type":"string","example":"Santos"},"dob":{"type":"string","description":"ISO 8601 (YYYY-MM-DD).","format":"date","example":"1988-04-12"},"sex_at_birth":{"type":"string","enum":["female","male","other","unknown"],"default":"female"},"middleName":{"type":"string","example":"Anne"},"prefix":{"type":"string","example":"Ms."},"suffix":{"type":"string","example":"Jr."}}}}}}}},"/patient/{id}/address":{"post":{"operationId":"address","summary":"Attach a postal address to a patient.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["line1","city","state","postalCode"],"properties":{"line1":{"type":"string","example":"742 Evergreen Terrace"},"city":{"type":"string","example":"Chicago"},"state":{"type":"string","example":"IL"},"postalCode":{"type":"string","example":"60614"},"line2":{"type":"string","example":"Apt 4B"},"country":{"type":"string","default":"US","example":"US"},"use":{"type":"string","enum":["home","work","temp"]}}}}}}}},"/patient/{id}/alias":{"get":{"operationId":"aliasList","summary":"List all active name aliases for a patient.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}]},"post":{"operationId":"alias","summary":"Attach an alternate patient name. Type and at least one name field are required.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["maiden","nickname","preferred","previous","legal_change","alias"],"default":"alias"},"alias":{"type":"string","example":"Mari"},"firstName":{"type":"string","example":"Maria"},"lastName":{"type":"string","example":"Gutierrez"},"fullName":{"type":"string"},"effectiveFrom":{"type":"string"},"effectiveTo":{"type":"string"}}}}}}}},"/patient/{id}/identifier":{"get":{"operationId":"identifierList","summary":"List external identities for a patient.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}},{"name":"active","in":"query","required":false,"schema":{"type":"string","enum":["true","false","all"],"default":"true"}}]},"post":{"operationId":"identifier","summary":"Attach an external identity. Authority is optional; the API uses CONEXT and Unknown defaults when omitted.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"type":"string","example":"MRN-449120"},"type":{"type":"string","example":"mrn"},"authority_organization_id":{"type":"string"},"authority_organization_name":{"type":"string"},"authority_external_system_id":{"type":"string"},"authority_external_system_name":{"type":"string"},"source_name":{"type":"string"},"active_from":{"type":"string"},"active_until":{"type":"string"}}}}}}}},"/patient/{id}/contact":{"post":{"operationId":"contact","summary":"Attach a phone or email contact point.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["phone","email"],"default":"phone"},"value":{"type":"string","example":"+1-312-555-0142"},"use":{"type":"string","enum":["mobile","home","work"]}}}}}}}},"/patient/find":{"get":{"operationId":"find","summary":"Match a patient by demographics.","parameters":[{"name":"firstName","in":"query","required":false,"schema":{"type":"string","example":"Maria"}},{"name":"lastName","in":"query","required":false,"schema":{"type":"string","example":"Santos"}},{"name":"dob","in":"query","required":false,"schema":{"type":"string","format":"date","example":"1988-04-12"}},{"name":"sexAtBirth","in":"query","required":false,"schema":{"type":"string","enum":["female","male","intersex","unknown"]}},{"name":"exact","in":"query","required":false,"schema":{"type":"string","description":"true returns only full matches.","enum":["true","false"]}}]}},"/patient/{id}/document":{"post":{"operationId":"attach","summary":"Attach a document, observation, wearable, or structured payload to a patient.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind of thing you are attaching. Distinct from Content type (the MIME type of an uploaded file).","enum":["document","observation","wearable","structured"],"default":"document"},"contentType":{"type":"string","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).","default":"application/pdf","example":"application/pdf"},"filename":{"type":"string"},"size":{"type":"string"},"payload":{"type":"string","description":"The structured body for this observation, wearable reading, or structured record."},"title":{"type":"string","example":"Intake form"}}}}}}},"get":{"operationId":"documentSearch","summary":"List documents attached to a patient, optionally filtered by kind.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"Filter by attachment kind. \"Any\" returns all kinds.","enum":["document","observation","wearable","structured"]}},{"name":"createdAfter","in":"query","required":false,"schema":{"type":"string","description":"Only documents created on or after this date.","format":"date"}},{"name":"filename","in":"query","required":false,"schema":{"type":"string","description":"Match documents whose title/filename contains this text."}}]}},"/patient/{id}":{"get":{"operationId":"echo","summary":"Read the full patient record with all attached data.","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id.","schema":{"type":"string"}}]}}}}