{ "openapi": "3.0.1", "info": { "title": "HDIM Patient Service API", "description": "Tenant-scoped patient directory, regional profile foundation, and consent-aware clinical context API for the HealthData-in-Motion platform.\n\n## Route Families\n- `/api/v1/patients` returns the JSON directory/search surface and the canonical regional patient profile foundation route used by Regional Sync.\n- `/patient/*` returns consent-aware FHIR aggregation, timeline, dashboard, provider-panel, and risk-assessment views.\n\n## Current Capabilities\n- **Patient Directory**: Tenant-scoped patient lookup, MRN search, and clinical FHIR patient-id lookup\n- **Regional Profile Foundation**: Canonical identity, demographics, coverage, completeness, provenance, cohort-context placeholder, and location summary contract\n- **Clinical Timeline**: Consent-aware patient history and summary views\n- **FHIR Aggregation**: Allergies, medications, conditions, immunizations, procedures, vitals, labs, encounters, and care plans\n- **Provider Panel & Pre-Visit Views**: Provider roster and pre-visit planning support\n- **Multi-Tenant Isolation**: Automatic tenant-level data isolation\n- **HIPAA Compliance**: Full audit logging and PHI protection\n\n## Branch Closeout Notes\n- The Regional Sync branch depends on `GET /api/v1/patients/{patientId}/regional-profile` as the canonical patient-read seam.\n- This service publishes read surfaces only in the current branch tranche. It does not own write-back into upstream FHIR systems.\n\n## Multi-Tenancy\nAll requests must include the `X-Tenant-ID` header for proper tenant isolation.\nThe system automatically filters all data by tenant to prevent cross-tenant data access.\n", "contact": { "name": "HDIM Development Team", "url": "https://healthdata.com", "email": "dev@healthdata.com" }, "license": { "name": "Proprietary", "url": "https://healthdata.com/license" }, "version": "1.3.0" }, "security": [ { "BearerAuthentication": [] } ], "tags": [ { "name": "Patient Clinical Risk", "description": "Backend-owned acute episode and feature-pipeline surfaces for clinical risk models." }, { "name": "Patient Management", "description": "APIs for managing patient records and clinical data aggregation.\n\nProvides comprehensive patient health record access including:\n- Complete health record (all resources)\n- Allergies and intolerances\n- Immunizations\n- Medications\n- Conditions and diagnoses\n- Procedures\n- Vital signs and lab results\n- Encounters and care plans\n- Patient timeline visualization\n- Health status dashboards\n\nAll endpoints require JWT authentication and X-Tenant-ID header.\nAll responses include Cache-Control: no-store headers for HIPAA compliance.\n" }, { "name": "Pre-Visit Planning", "description": "APIs for pre-visit planning and patient summaries" }, { "name": "Provider Panel", "description": "Manage provider patient panels" } ], "paths": { "/api/v1/providers/{providerId}/panel/patients": { "post": { "tags": [ "Provider Panel" ], "summary": "Assign patient to panel", "description": "Assign a patient to the provider's panel", "operationId": "assignPatient", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderPanelRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderPanelResponse" } } } } } } }, "/api/v1/providers/{providerId}/panel/patients/bulk": { "post": { "tags": [ "Provider Panel" ], "summary": "Bulk assign patients", "description": "Bulk assign multiple patients to the provider's panel (Admin only)", "operationId": "bulkAssignPatients", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignment" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } } } } }, "/patient/vitals": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient vital signs", "description": "Retrieves patient vital signs as a FHIR R4 Bundle (Observation resources).\n\nIncludes blood pressure, heart rate, temperature, weight, height, BMI, O2 saturation.\nUses LOINC codes for standardized observation types.\n\nUse for clinical monitoring, quality measure evaluation, care gap tracking.\n", "operationId": "getVitalSigns", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Vital signs retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Vitals Bundle": { "description": "Vitals Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 8, "entry": [ { "resource": { "resourceType": "Observation", "id": "vitals-1", "status": "final", "category": [ { "coding": [ { "code": "vital-signs" } ] } ], "code": { "coding": [ { "system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure" } ] }, "valueQuantity": { "value": 120, "unit": "mmHg" }, "effectiveDateTime": "2024-01-15" } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/timeline": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient timeline (all events)", "description": "Retrieves complete patient clinical timeline sorted chronologically.\n\nIncludes all clinical events: encounters, procedures, lab results, medications,\nimmunizations, conditions, and vital signs.\n\nReturns simplified timeline view optimized for UI visualization.\n", "operationId": "getPatientTimeline", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } }, "200": { "description": "Timeline retrieved successfully", "content": { "application/json": { "examples": { "Timeline Events": { "description": "Timeline Events", "value": [ { "eventDate": "2024-01-15", "eventType": "Encounter", "title": "Office Visit", "description": "Annual physical examination", "resourceId": "enc-1" }, { "eventDate": "2024-01-10", "eventType": "Observation", "title": "HbA1c Lab Result", "description": "7.2%", "resourceId": "lab-1" } ] } } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/timeline/summary": { "get": { "tags": [ "Patient Management" ], "summary": "Get monthly timeline summary", "description": "Retrieves monthly event count summary for a specific year.\n\nReturns aggregated counts by month for timeline visualization (e.g., bar charts).\nUseful for identifying periods of high clinical activity.\n", "operationId": "getTimelineSummaryByMonth", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "year", "in": "query", "description": "Year to summarize", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2024 } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "400": { "description": "Invalid year", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "200": { "description": "Timeline summary retrieved successfully", "content": { "application/json": { "examples": { "Monthly Summary": { "description": "Monthly Summary", "value": { "2024-01": 12, "2024-02": 8, "2024-03": 15 } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/timeline/by-type": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient timeline by resource type", "description": "Retrieves patient clinical timeline filtered by FHIR resource type.\n\nFilter for specific event types: Encounter, Observation, Procedure, MedicationRequest,\nCondition, Immunization, AllergyIntolerance.\n\nUseful for focused clinical review (e.g., all lab results, all procedures).\n", "operationId": "getPatientTimelineByResourceType", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "resourceType", "in": "query", "description": "FHIR resource type to filter", "required": true, "schema": { "type": "string" }, "example": "Observation" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } }, "200": { "description": "Timeline retrieved successfully", "content": { "application/json": { "examples": { "Timeline Events": { "description": "Timeline Events", "value": [ { "eventDate": "2024-01-10", "eventType": "Observation", "title": "HbA1c", "description": "7.2%" } ] } } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } }, "400": { "description": "Invalid resource type", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/timeline/by-date": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient timeline by date range", "description": "Retrieves patient clinical timeline filtered by date range.\n\nUseful for focused review of specific time periods (e.g., last 6 months, past year).\nIncludes all event types within the specified date range.\n", "operationId": "getPatientTimelineByDateRange", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "startDate", "in": "query", "description": "Start date (ISO 8601 format)", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "endDate", "in": "query", "description": "End date (ISO 8601 format)", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2024-12-31" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } }, "400": { "description": "Invalid date range", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } } } } }, "200": { "description": "Timeline retrieved successfully", "content": { "application/json": { "examples": { "Timeline Events": { "description": "Timeline Events", "value": [ { "eventDate": "2024-01-15", "eventType": "Encounter", "title": "Office Visit", "description": "Follow-up for diabetes" } ] } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/risk-assessment": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient risk assessment", "description": "Retrieves comprehensive risk assessment combining HCC-based RAF scores\nwith care gap data for clinical decision support and risk stratification.\n\nResponse includes:\n- Backend-owned payload metadata (`generatedAt`, `modelVersion`)\n- CMS-HCC RAF scores (V24, V28, and blended)\n- Risk level classification (LOW, MODERATE, HIGH, VERY_HIGH)\n- Top HCC codes and chronic conditions\n- Open care gap counts\n- Documentation gaps and potential RAF uplift opportunities\n- Source provenance and structured explanations for auditability\n\nRisk level thresholds:\n- LOW: RAF < 1.0\n- MODERATE: 1.0 <= RAF < 2.0\n- HIGH: 2.0 <= RAF < 3.5\n- VERY_HIGH: RAF >= 3.5\n\nUse for population health management, risk stratification dashboards,\nand value-based care reporting.\n\nResponse includes Cache-Control: no-store header for HIPAA compliance.\nAll operations are audited for PHI access tracking.\n", "operationId": "getRiskAssessment", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" }, "example": "tenant-123" }, { "name": "patient", "in": "query", "description": "Patient ID (UUID format)", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "404": { "description": "Patient not found or no HCC profile available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientRiskAssessmentResponse" } } } }, "200": { "description": "Risk assessment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientRiskAssessmentResponse" }, "examples": { "Risk Assessment Response": { "description": "Risk Assessment Response", "value": { "patientId": "550e8400-e29b-41d4-a716-446655440000", "generatedAt": "2026-02-02T15:30:00Z", "modelVersion": "patient-risk-assessment-hcc-care-gaps-v1", "rafScoreBlended": 1.892, "rafScoreV24": 1.756, "rafScoreV28": 2.028, "riskLevel": "MODERATE", "riskScore": 68, "hccCount": 5, "topHccs": [ "HCC18", "HCC85", "HCC111" ], "chronicConditions": [ "Diabetes with Chronic Complications", "Congestive Heart Failure", "Chronic Obstructive Pulmonary Disease" ], "openCareGaps": 3, "highPriorityCareGaps": 1, "overdueCareGaps": 1, "potentialRafUplift": 0.234, "documentationGapCount": 2, "recaptureOpportunities": 1, "calculatedAt": "2026-02-02T15:30:00Z", "profileYear": 2026, "provenance": { "assessmentMethod": "Aggregated from the patient HCC profile and patient care gap counts.", "sources": [ { "service": "hcc-service", "endpoint": "/api/v1/hcc/patient/{patientId}/profile", "available": true, "detail": "CMS-HCC RAF profile, documentation gaps, and recapture opportunities were included.", "generatedAt": "2026-02-02T15:25:00Z" }, { "service": "care-gap-service", "endpoint": "/api/v1/patients/{patientId}/gaps/count", "available": true, "detail": "Open, high-priority, and overdue care gap counts were included.", "generatedAt": "2026-02-02T15:30:00Z" } ] }, "explanations": [ { "type": "hcc", "code": "HCC18", "label": "Diabetes with Chronic Complications", "reason": "Included in the active CMS-HCC profile and contributes to the RAF-based risk score." }, { "type": "care-gap", "code": "high-priority-care-gaps", "label": "High-priority care gaps", "reason": "1 high-priority care gap remains open for this patient." } ], "dataAvailability": { "hccDataAvailable": true, "careGapDataAvailable": true, "documentationGapDataAvailable": true } } } } } } }, "403": { "description": "Access denied - insufficient permissions or wrong tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientRiskAssessmentResponse" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/api/v1/risk-stratification/summary": { "get": { "tags": [ "Risk Stratification" ], "summary": "Get the tenant's non-PHI risk-tier distribution", "description": "Aggregate tier counts (HIGH/MEDIUM/LOW) for the Risk Stratification page. Carries no patient identifiers, so analytics-only personas (ANALYST, holding PATIENT_EXPORT) can read the distribution without PATIENT_READ. Resolves finding DMP-AN-03.", "operationId": "getRiskStratificationSummary", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "scoreType", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskStratificationSummaryResponse" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/procedures": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient procedures", "description": "Retrieves patient procedure history as a FHIR R4 Bundle (Procedure resources).\n\nIncludes completed procedures with CPT/HCPCS codes, dates, and providers.\nUse for quality measure evaluation, care gap identification, utilization review.\n", "operationId": "getProcedures", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Procedures retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Procedure Bundle": { "description": "Procedure Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 6, "entry": [ { "resource": { "resourceType": "Procedure", "id": "proc-1", "status": "completed", "code": { "coding": [ { "system": "http://www.ama-assn.org/go/cpt", "code": "99213", "display": "Office visit" } ] }, "performedDateTime": "2024-01-10" } } ] } } } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/medications": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient medications", "description": "Retrieves patient medication list as a FHIR R4 Bundle (MedicationRequest resources).\n\nFilter for active medications only (default) or include historical medications.\nIncludes RxNorm codes, dosage instructions, prescribers, and dates.\n\nUse for medication reconciliation, drug interaction checks, quality measures.\n", "operationId": "getMedications", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "onlyActive", "in": "query", "description": "Return only active medications (default: true)", "required": false, "schema": { "type": "boolean", "default": true }, "example": true } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Medications retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Medication Bundle": { "description": "Medication Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 3, "entry": [ { "resource": { "resourceType": "MedicationRequest", "id": "med-1", "status": "active", "medicationCodeableConcept": { "coding": [ { "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "860975", "display": "Lisinopril 10 MG" } ] }, "dosageInstruction": [ { "text": "Take 1 tablet by mouth daily" } ] } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/medication-summary": { "get": { "tags": [ "Patient Management" ], "summary": "Get medication summary dashboard", "description": "Retrieves medication summary for dashboard display.\n\nIncludes: total active medications, medication classes, adherence status,\nrecent prescriptions, and upcoming refills.\n\nUseful for medication reconciliation and adherence monitoring.\n", "operationId": "getMedicationSummary", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicationSummary" } } } }, "200": { "description": "Medication summary retrieved successfully", "content": { "application/json": { "examples": { "Medication Summary": { "description": "Medication Summary", "value": { "totalActive": 3, "medicationClasses": [ "antihypertensive", "antidiabetic", "statin" ], "adherenceRate": 85, "recentPrescriptions": 2, "upcomingRefills": 1 } } } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicationSummary" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/labs": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient laboratory results", "description": "Retrieves patient lab results as a FHIR R4 Bundle (Observation resources).\n\nIncludes chemistry panels, CBC, lipid panels, HbA1c, and other lab tests.\nUses LOINC codes for standardized lab test identification.\n\nUse for clinical monitoring, diabetes management, quality measure evaluation.\n", "operationId": "getLabResults", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Lab results retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Lab Results Bundle": { "description": "Lab Results Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 12, "entry": [ { "resource": { "resourceType": "Observation", "id": "lab-1", "status": "final", "category": [ { "coding": [ { "code": "laboratory" } ] } ], "code": { "coding": [ { "system": "http://loinc.org", "code": "4548-4", "display": "HbA1c" } ] }, "valueQuantity": { "value": 7.2, "unit": "%" }, "effectiveDateTime": "2024-01-10" } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/immunizations": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient immunization history", "description": "Retrieves patient immunization records as a FHIR R4 Bundle.\n\nFilter for completed immunizations only to exclude declined/not-done records.\nIncludes CVX codes, administration dates, lot numbers, and providers.\n\nUse for immunization compliance, quality measure evaluation (HEDIS).\n", "operationId": "getImmunizations", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "onlyCompleted", "in": "query", "description": "Return only completed immunizations", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Immunizations retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Immunization Bundle": { "description": "Immunization Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 5, "entry": [ { "resource": { "resourceType": "Immunization", "id": "imm-1", "status": "completed", "vaccineCode": { "coding": [ { "system": "http://hl7.org/fhir/sid/cvx", "code": "08", "display": "Hep B" } ] }, "occurrenceDateTime": "2024-01-15" } } ] } } } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/immunization-summary": { "get": { "tags": [ "Patient Management" ], "summary": "Get immunization summary dashboard", "description": "Retrieves immunization summary for dashboard display.\n\nIncludes: total immunizations, up-to-date status, overdue immunizations,\nrecent immunizations, and upcoming recommendations.\n\nUseful for immunization compliance tracking and HEDIS quality measures.\n", "operationId": "getImmunizationSummary", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImmunizationSummary" } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImmunizationSummary" } } } }, "200": { "description": "Immunization summary retrieved successfully", "content": { "application/json": { "examples": { "Immunization Summary": { "description": "Immunization Summary", "value": { "totalImmunizations": 12, "upToDate": true, "overdueImmunizations": 0, "recentImmunizations": 2, "upcomingRecommendations": 1 } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/health-status": { "get": { "tags": [ "Patient Management" ], "summary": "Get comprehensive health status dashboard", "description": "Retrieves aggregated health status summary for dashboard display.\n\nIncludes counts and summaries for: active conditions, medications, allergies,\nrecent vitals, upcoming appointments, care gaps, and risk scores.\n\nOptimized for clinical overview dashboards and patient portals.\n", "operationId": "getHealthStatusSummary", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatusSummary" } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatusSummary" } } } }, "200": { "description": "Health status summary retrieved successfully", "content": { "application/json": { "examples": { "Health Status Summary": { "description": "Health Status Summary", "value": { "activeConditions": 4, "activeMedications": 3, "criticalAllergies": 1, "recentVitals": { "bloodPressure": "120/80", "weight": "180 lbs" }, "upcomingAppointments": 2, "openCareGaps": 3, "riskScore": 72 } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/health-record": { "get": { "tags": [ "Patient Management" ], "summary": "Get comprehensive patient health record", "description": "Retrieves complete patient health record as a FHIR R4 Bundle.\n\nIncludes all clinical resources for the patient:\n- Demographics and identifiers\n- Allergies and intolerances\n- Immunizations\n- Medications (active and historical)\n- Conditions and diagnoses\n- Procedures\n- Vital signs and observations\n- Lab results\n- Encounters\n- Care plans\n\nResponse includes Cache-Control: no-store header for HIPAA compliance.\nAll operations are audited for PHI access tracking.\n", "operationId": "getComprehensiveHealthRecord", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" }, "example": "tenant-123" }, { "name": "patient", "in": "query", "description": "Patient ID (FHIR resource ID or UUID)", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "404": { "description": "Patient not found for the given ID and tenant", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "403": { "description": "Access denied - insufficient permissions or wrong tenant", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Patient health record retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "FHIR Bundle Response": { "description": "FHIR Bundle Response", "value": { "resourceType": "Bundle", "type": "searchset", "total": 45, "entry": [ { "resource": { "resourceType": "Patient", "id": "550e8400-e29b-41d4-a716-446655440000", "name": [ { "family": "Doe", "given": [ "John" ] } ], "birthDate": "1980-05-15" } }, { "resource": { "resourceType": "AllergyIntolerance", "id": "allergy-1", "patient": { "reference": "Patient/550e8400-e29b-41d4-a716-446655440000" }, "code": { "text": "Penicillin" }, "criticality": "high" } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/encounters": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient encounters", "description": "Retrieves patient encounter history as a FHIR R4 Bundle (Encounter resources).\n\nFilter for active encounters only or include finished encounters.\nIncludes visit types, dates, providers, locations, and diagnoses.\n\nUse for utilization tracking, quality measure evaluation, continuity of care.\n", "operationId": "getEncounters", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "onlyActive", "in": "query", "description": "Return only active encounters", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Encounters retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Encounter Bundle": { "description": "Encounter Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 7, "entry": [ { "resource": { "resourceType": "Encounter", "id": "enc-1", "status": "finished", "class": { "code": "AMB", "display": "ambulatory" }, "type": [ { "coding": [ { "code": "99213", "display": "Office visit" } ] } ], "period": { "start": "2024-01-15T09:00:00Z", "end": "2024-01-15T09:30:00Z" } } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/conditions": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient conditions and diagnoses", "description": "Retrieves patient problem list and diagnoses as a FHIR R4 Bundle (Condition resources).\n\nFilter for active conditions only (default) or include resolved/inactive conditions.\nIncludes ICD-10, SNOMED CT codes, onset dates, and clinical status.\n\nUse for risk stratification, care gap identification, HCC coding.\n", "operationId": "getConditions", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "onlyActive", "in": "query", "description": "Return only active conditions (default: true)", "required": false, "schema": { "type": "boolean", "default": true }, "example": true } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Conditions retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Condition Bundle": { "description": "Condition Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 4, "entry": [ { "resource": { "resourceType": "Condition", "id": "cond-1", "clinicalStatus": { "coding": [ { "code": "active" } ] }, "code": { "coding": [ { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9", "display": "Type 2 diabetes mellitus without complications" } ] }, "onsetDateTime": "2020-03-15" } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/condition-summary": { "get": { "tags": [ "Patient Management" ], "summary": "Get condition summary dashboard", "description": "Retrieves condition/diagnosis summary for dashboard display.\n\nIncludes: total active conditions, chronic conditions, condition categories,\nHCC risk scores, and recent diagnoses.\n\nUseful for care management, risk stratification, and HCC coding.\n", "operationId": "getConditionSummary", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionSummary" } } } }, "200": { "description": "Condition summary retrieved successfully", "content": { "application/json": { "examples": { "Condition Summary": { "description": "Condition Summary", "value": { "totalActive": 4, "chronicConditions": 3, "conditionCategories": { "endocrine": 1, "cardiovascular": 2, "respiratory": 1 }, "hccScore": 72, "recentDiagnoses": 1 } } } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionSummary" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/clinical-risk-profiles": { "get": { "tags": [ "Patient Clinical Risk" ], "summary": "Get canonical patient-level clinical-risk profiles for a panel query", "operationId": "getClinicalRiskProfiles", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "measure", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PatientClinicalRiskProfileResponse" } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/clinical-risk-profile": { "get": { "tags": [ "Patient Clinical Risk" ], "summary": "Get canonical patient-level clinical-risk profile", "operationId": "getClinicalRiskProfile", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "measure", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientClinicalRiskProfileResponse" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/clinical-risk-features": { "get": { "tags": [ "Patient Clinical Risk" ], "summary": "Get canonical clinical-risk feature payload for a patient", "operationId": "getClinicalRiskFeatures", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClinicalRiskFeatureResponse" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/care-plans": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient care plans", "description": "Retrieves patient care plans as a FHIR R4 Bundle (CarePlan resources).\n\nFilter for active care plans only (default) or include completed care plans.\nIncludes goals, activities, care team members, and addresses.\n\nUse for care coordination, chronic disease management, transitional care.\n", "operationId": "getCarePlans", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "onlyActive", "in": "query", "description": "Return only active care plans (default: true)", "required": false, "schema": { "type": "boolean", "default": true }, "example": true } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Care plans retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "CarePlan Bundle": { "description": "CarePlan Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 2, "entry": [ { "resource": { "resourceType": "CarePlan", "id": "cp-1", "status": "active", "intent": "plan", "category": [ { "coding": [ { "code": "diabetes-management" } ] } ], "title": "Diabetes Care Plan", "period": { "start": "2024-01-01" } } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/allergy-summary": { "get": { "tags": [ "Patient Management" ], "summary": "Get allergy summary dashboard", "description": "Retrieves allergy summary for dashboard display.\n\nIncludes: total allergies, critical allergies, allergy categories (drug, food, environmental),\nand recent reactions.\n\nUseful for prescribing safety checks and allergy management.\n", "operationId": "getAllergySummary", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllergySummary" } } } }, "404": { "description": "Patient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllergySummary" } } } }, "200": { "description": "Allergy summary retrieved successfully", "content": { "application/json": { "examples": { "Allergy Summary": { "description": "Allergy Summary", "value": { "totalAllergies": 2, "criticalAllergies": 1, "allergyCategories": { "drug": 1, "food": 1 }, "recentReactions": 0 } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/allergies": { "get": { "tags": [ "Patient Management" ], "summary": "Get patient allergies and intolerances", "description": "Retrieves patient allergy and intolerance information as a FHIR R4 Bundle.\n\nCan filter for only critical allergies (e.g., anaphylaxis, severe reactions).\nIncludes coded allergy information (SNOMED CT, RxNorm) and reaction details.\n\nUse for clinical decision support, medication prescribing safety checks.\n", "operationId": "getAllergies", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Patient ID", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "onlyCritical", "in": "query", "description": "Return only critical allergies", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "403": { "description": "Access denied", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "404": { "description": "Patient not found", "content": { "application/fhir+json": { "schema": { "type": "string" } } } }, "200": { "description": "Allergies retrieved successfully", "content": { "application/fhir+json": { "schema": { "type": "object", "description": "FHIR R4 Bundle payload" }, "examples": { "Allergy Bundle": { "description": "Allergy Bundle", "value": { "resourceType": "Bundle", "type": "searchset", "total": 2, "entry": [ { "resource": { "resourceType": "AllergyIntolerance", "id": "allergy-1", "clinicalStatus": { "coding": [ { "code": "active" } ] }, "code": { "coding": [ { "system": "http://snomed.info/sct", "code": "91936005", "display": "Penicillin" } ] }, "criticality": "high", "reaction": [ { "manifestation": [ { "coding": [ { "code": "anaphylaxis" } ] } ] } ] } } ] } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/acute-episodes": { "get": { "tags": [ "Patient Clinical Risk" ], "summary": "Get normalized acute episodes for a patient", "operationId": "getAcuteEpisodes", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AcuteEpisodeResponse" } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/patient/_health": { "get": { "tags": [ "Patient Management" ], "summary": "Service health check", "description": "Simple health check endpoint for monitoring service availability.\n\nReturns service name, status, and timestamp.\nUse for container health checks, load balancer monitoring.\n", "operationId": "healthCheck", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "examples": { "Health Check Response": { "description": "Health Check Response", "value": { "status": "UP", "service": "patient-service", "timestamp": "2024-01-24" } } } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/api/v1/providers/{providerId}/pre-visit-summaries": { "get": { "tags": [ "Pre-Visit Planning" ], "summary": "Get pre-visit summaries for scheduled patients", "description": "Returns pre-visit summaries for all patients scheduled for the specified date. Defaults to tomorrow if no date is provided.", "operationId": "getBatchPreVisitSummaries", "parameters": [ { "name": "providerId", "in": "path", "description": "Provider ID requesting the summaries", "required": true, "schema": { "type": "string" } }, { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant filtering", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "Date to get summaries for (YYYY-MM-DD), defaults to tomorrow", "required": false, "schema": { "type": "string" } } ], "responses": { "403": { "description": "Forbidden" }, "401": { "description": "Unauthorized" }, "200": { "description": "Pre-visit summaries generated successfully", "content": { "application/json": {} } } } } }, "/api/v1/providers/{providerId}/patients/{patientId}/pre-visit-summary": { "get": { "tags": [ "Pre-Visit Planning" ], "summary": "Get pre-visit summary for a patient", "description": "Returns a comprehensive pre-visit summary including care gaps, recent lab results, medications, and AI-suggested agenda items. This endpoint is HIPAA-audited and returns fresh data (no caching).", "operationId": "getPreVisitSummary", "parameters": [ { "name": "providerId", "in": "path", "description": "Provider ID requesting the summary", "required": true, "schema": { "type": "string" } }, { "name": "patientId", "in": "path", "description": "Patient ID for the summary", "required": true, "schema": { "type": "string" } }, { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant filtering", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Unauthorized - invalid or missing authentication" }, "200": { "description": "Pre-visit summary generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreVisitSummaryResponse" } } } }, "403": { "description": "Forbidden - insufficient permissions" }, "404": { "description": "Patient not found" } } } }, "/api/v1/providers/{providerId}/panel": { "get": { "tags": [ "Provider Panel" ], "summary": "Get provider panel", "description": "Returns paginated list of patients assigned to the provider", "operationId": "getProviderPanel", "parameters": [ { "name": "providerId", "in": "path", "description": "Provider's unique identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (0-based)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "description": "Page size", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageProviderPanelResponse" } } } } } } }, "/api/v1/providers/{providerId}/panel/patients/{patientId}": { "get": { "tags": [ "Provider Panel" ], "summary": "Check patient in panel", "description": "Check if a specific patient is assigned to the provider", "operationId": "isPatientInPanel", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "patientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } }, "delete": { "tags": [ "Provider Panel" ], "summary": "Remove patient from panel", "description": "Remove a patient from the provider's panel", "operationId": "removePatient", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "patientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/providers/{providerId}/panel/patient-ids": { "get": { "tags": [ "Provider Panel" ], "summary": "Get panel patient IDs", "description": "Returns list of patient IDs in the provider's panel", "operationId": "getPanelPatientIds", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } }, "/api/v1/providers/{providerId}/panel/count": { "get": { "tags": [ "Provider Panel" ], "summary": "Get panel count", "description": "Returns count of patients in the provider's panel", "operationId": "getPanelCount", "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } } } } } } } }, "/api/v1/patients": { "get": { "tags": [ "patient-api-controller" ], "operationId": "listPatients", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePatientDemographicsEntity" } } } } } } }, "/api/v1/patients/{patientId}": { "get": { "tags": [ "patient-api-controller" ], "operationId": "getPatientById", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "patientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientDemographicsEntity" } } } } } } }, "/api/v1/patients/{patientId}/regional-profile": { "get": { "tags": [ "patient-api-controller" ], "summary": "Get canonical regional patient profile foundation", "description": "Returns the canonical regional patient profile foundation contract for one patient.\n\nThis JSON surface is the first implementation slice for the regional super HIE work:\n- identity and cross-reference spine\n- demographic summary\n- insurance-linked aliases\n- completeness scoring for required data classes\n- provenance and source freshness metadata\n- cohort context placeholder\n- encounter-derived location summary\n\nDownstream cohort synchronization, privacy projection, and delivery flows build on this contract.\n", "operationId": "getRegionalProfile", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "description": "Tenant ID for multi-tenant isolation", "required": true, "schema": { "type": "string" } }, { "name": "patientId", "in": "path", "description": "Enterprise patient UUID", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientRegionalProfileResponse" } } } }, "200": { "description": "Canonical regional patient profile returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientRegionalProfileResponse" }, "examples": { "Regional patient profile foundation": { "description": "Regional patient profile foundation", "value": { "patientId": "550e8400-e29b-41d4-a716-446655440000", "tenantId": "tenant-123", "fhirPatientId": "patient-fhir-123", "contractVersion": "regional-patient-profile-v1", "generatedAt": "2026-04-23T12:00:00Z", "note": "Canonical regional patient profile assembled from patient-service registry data and consent-filtered FHIR aggregation resources.", "identity": { "enterprisePatientId": "550e8400-e29b-41d4-a716-446655440000", "fhirPatientId": "patient-fhir-123", "medicalRecordNumber": "MRN-12345", "active": true, "deceased": false, "crossReferences": [ { "type": "enterprise_patient_id", "value": "550e8400-e29b-41d4-a716-446655440000", "source": "patient-demographics", "note": "Canonical patient-service UUID" }, { "type": "payer_member_id", "value": "MEM-001", "source": "patient-insurance", "note": "Acme Health" } ] }, "demographics": { "fullName": "John Q Doe", "firstName": "John", "middleName": "Q", "lastName": "Doe", "dateOfBirth": "1985-05-15", "gender": "male", "preferredLanguage": "en", "city": "Portland", "state": "ME", "country": "US", "primaryCareProviderId": "pcp-1", "primaryCareProviderName": "Dr. Rivera" }, "coverages": [ { "coverageType": "medical", "payerName": "Acme Health", "payerId": "payer-1", "planName": "Gold PPO", "memberId": "MEM-001", "primary": true, "active": true, "effectiveDate": "2026-01-01", "terminationDate": null } ], "completeness": { "scorePercent": 100, "availableRequiredDataClassCount": 6, "requiredDataClassCount": 6, "availableDataClasses": [ "demographics", "identity", "insurance", "conditions", "observations", "encounters" ], "missingRequiredDataClasses": [] }, "provenance": { "state": "aggregated-foundation", "headline": "Canonical profile assembled from registry data and consent-filtered FHIR aggregation", "detail": "Demographics and identifiers come from patient-service persistence. Clinical resource summaries come from the audited patient aggregation flow.", "resourceTypeCounts": { "Condition": 1, "Observation": 1, "Encounter": 1 }, "sourceSummaries": [ { "sourceId": "patient-demographics", "sourceLabel": "Patient demographics repository", "available": true, "recordCount": 1, "lastUpdatedAt": "2026-04-23T11:30:00Z", "note": "Foundational identity and demographic source" } ] }, "cohortContext": { "membershipState": "not-yet-linked", "activeCohortCount": 0, "cohortLabels": [], "inclusionReason": "No cohort memberships are linked in the foundation slice.", "note": "This contract reserves cohort context before cohort synchronization and downstream distribution workflows are implemented." }, "locationSummary": { "state": "encounter-derived-active", "freshness": "fresh", "confidence": "high", "display": "North Campus", "encounterId": "encounter-1", "encounterStatus": "in-progress", "lastObservedAt": "2026-04-23T08:00:00Z", "note": "Location is derived from the most recent active encounter." } } } } } } }, "404": { "description": "Patient not found for the given tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientRegionalProfileResponse" } } } } }, "security": [ { "BearerAuthentication": [] } ] } }, "/api/v1/patients/search": { "get": { "tags": [ "patient-api-controller" ], "operationId": "searchPatients", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "mrn", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePatientDemographicsEntity" } } } } } } }, "/api/v1/patients/fhir/{fhirPatientId}": { "get": { "tags": [ "patient-api-controller" ], "operationId": "getPatientByFhirPatientId", "parameters": [ { "name": "X-Tenant-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "fhirPatientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientDemographicsEntity" } } } } } } } }, "components": { "schemas": { "ProviderPanelRequest": { "required": [ "patientId" ], "type": "object", "properties": { "patientId": { "type": "string", "format": "uuid" }, "assignmentType": { "type": "string", "enum": [ "PRIMARY", "SPECIALIST", "CARE_COORDINATOR", "COVERING", "CONSULTING" ] }, "notes": { "type": "string" } } }, "ProviderPanelResponse": { "type": "object", "properties": { "assignmentId": { "type": "string", "format": "uuid" }, "patientId": { "type": "string", "format": "uuid" }, "assignmentType": { "type": "string" }, "assignedDate": { "type": "string", "format": "date-time" }, "notes": { "type": "string" }, "patientName": { "type": "string" }, "mrn": { "type": "string" }, "dateOfBirth": { "type": "string" }, "gender": { "type": "string" }, "riskLevel": { "type": "string" }, "openCareGaps": { "type": "integer", "format": "int32" }, "lastVisitDate": { "type": "string", "format": "date-time" } } }, "BulkAssignment": { "required": [ "patientIds" ], "type": "object", "properties": { "patientIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "assignmentType": { "type": "string", "enum": [ "PRIMARY", "SPECIALIST", "CARE_COORDINATOR", "COVERING", "CONSULTING" ] } } }, "TimelineEvent": { "type": "object", "properties": { "resourceId": { "type": "string" }, "resourceType": { "type": "string" }, "date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "status": { "type": "string" }, "details": { "type": "string" } } }, "PatientRiskAssessmentDataAvailability": { "type": "object", "properties": { "hccDataAvailable": { "type": "boolean", "description": "Whether HCC profile data was available", "example": true }, "careGapDataAvailable": { "type": "boolean", "description": "Whether care gap data was available", "example": true }, "documentationGapDataAvailable": { "type": "boolean", "description": "Whether documentation gap data was available", "example": true } }, "description": "Indicates which data sources were available" }, "PatientRiskAssessmentExplanation": { "type": "object", "properties": { "type": { "type": "string", "description": "Explanation category", "example": "hcc", "enum": [ "hcc", "care-gap", "documentation-gap", "recapture", "availability" ] }, "code": { "type": "string", "description": "Code or internal key for the explanation", "example": "HCC18" }, "label": { "type": "string", "description": "Human-readable label for the explanation", "example": "Diabetes with Chronic Complications" }, "reason": { "type": "string", "description": "Plain-language reason this explanation matters" } }, "description": "Structured explanation contributing to the current risk assessment" }, "PatientRiskAssessmentProvenance": { "type": "object", "properties": { "assessmentMethod": { "type": "string", "description": "Short description of how the assessment was assembled", "example": "Aggregated from the patient HCC profile and patient care gap counts." }, "sources": { "type": "array", "description": "Source systems and endpoints used to build the assessment", "items": { "$ref": "#/components/schemas/PatientRiskAssessmentProvenanceSource" } } }, "description": "Backend-owned provenance metadata for the assessment" }, "PatientRiskAssessmentProvenanceSource": { "type": "object", "properties": { "service": { "type": "string", "description": "Service that supplied this portion of the assessment", "example": "hcc-service" }, "endpoint": { "type": "string", "description": "Backend endpoint used for this source", "example": "/api/v1/hcc/patient/{patientId}/profile" }, "available": { "type": "boolean", "description": "Whether this source was available when the assessment was generated", "example": true }, "detail": { "type": "string", "description": "Short description of what this source contributed" }, "generatedAt": { "type": "string", "description": "Timestamp associated with this source payload when available", "format": "date-time", "example": "2026-02-02T15:30:00Z" } }, "description": "One backend source contributing to the assessment" }, "PatientRiskAssessmentResponse": { "type": "object", "properties": { "patientId": { "type": "string", "description": "Patient identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "generatedAt": { "type": "string", "description": "Timestamp when the canonical risk payload was generated", "format": "date-time", "example": "2026-02-02T15:30:00Z" }, "modelVersion": { "type": "string", "description": "Backend-owned model or contract version for this risk payload", "example": "patient-risk-assessment-hcc-care-gaps-v1" }, "rafScoreBlended": { "type": "number", "description": "Blended RAF score (weighted combination of V24 and V28)", "example": 1.234 }, "rafScoreV24": { "type": "number", "description": "RAF score under CMS-HCC V24 model", "example": 1.156 }, "rafScoreV28": { "type": "number", "description": "RAF score under CMS-HCC V28 model", "example": 1.312 }, "riskLevel": { "type": "string", "description": "Risk level classification based on RAF score", "example": "HIGH", "enum": [ "LOW", "MODERATE", "HIGH", "VERY_HIGH" ] }, "riskScore": { "type": "integer", "description": "Numerical risk score (0-100) for UI display", "format": "int32", "example": 78 }, "hccCount": { "type": "integer", "description": "Total count of captured HCC codes", "format": "int32", "example": 5 }, "topHccs": { "type": "array", "description": "Top HCC codes by RAF impact (up to 5)", "example": [ "HCC18", "HCC85", "HCC96" ], "items": { "type": "string", "description": "Top HCC codes by RAF impact (up to 5)", "example": "[\"HCC18\",\"HCC85\",\"HCC96\"]" } }, "chronicConditions": { "type": "array", "description": "Chronic conditions derived from HCC codes", "example": [ "Diabetes with Complications", "Heart Failure" ], "items": { "type": "string", "description": "Chronic conditions derived from HCC codes", "example": "[\"Diabetes with Complications\",\"Heart Failure\"]" } }, "openCareGaps": { "type": "integer", "description": "Count of open care gaps", "format": "int32", "example": 3 }, "highPriorityCareGaps": { "type": "integer", "description": "Count of high-priority care gaps", "format": "int32", "example": 1 }, "overdueCareGaps": { "type": "integer", "description": "Count of overdue care gaps", "format": "int32", "example": 2 }, "potentialRafUplift": { "type": "number", "description": "Potential RAF uplift if documentation gaps are addressed", "example": 0.145 }, "documentationGapCount": { "type": "integer", "description": "Count of documentation gaps that could improve RAF score", "format": "int32", "example": 2 }, "recaptureOpportunities": { "type": "integer", "description": "Count of prior-year HCCs needing recapture", "format": "int32", "example": 3 }, "calculatedAt": { "type": "string", "description": "Legacy timestamp alias for compatibility with existing clients", "format": "date-time", "example": "2026-02-02T15:30:00Z" }, "profileYear": { "type": "integer", "description": "Profile year for HCC calculations", "format": "int32", "example": 2026 }, "dataAvailability": { "$ref": "#/components/schemas/PatientRiskAssessmentDataAvailability" }, "provenance": { "$ref": "#/components/schemas/PatientRiskAssessmentProvenance" }, "explanations": { "type": "array", "description": "Structured explanations for the current risk assessment", "items": { "$ref": "#/components/schemas/PatientRiskAssessmentExplanation" } } }, "description": "Patient risk assessment combining HCC RAF scores with care gap data" }, "MedicationSummary": { "type": "object", "properties": { "activeCount": { "type": "integer", "format": "int32" }, "totalCount": { "type": "integer", "format": "int32" }, "activeMedicationNames": { "type": "array", "items": { "type": "string" } }, "adherenceRisk": { "type": "string" }, "polypharmacyFlag": { "type": "boolean" } } }, "ImmunizationSummary": { "type": "object", "properties": { "completedCount": { "type": "integer", "format": "int32" }, "totalCount": { "type": "integer", "format": "int32" }, "complianceStatus": { "type": "string" }, "completedVaccines": { "type": "array", "items": { "type": "string" } }, "isCompliant": { "type": "boolean" } } }, "HealthStatusSummary": { "type": "object", "properties": { "patientId": { "type": "string" }, "assessmentDate": { "type": "string", "format": "date" }, "activeConditionsCount": { "type": "integer", "format": "int32" }, "activeMedicationsCount": { "type": "integer", "format": "int32" }, "criticalAllergiesCount": { "type": "integer", "format": "int32" }, "completedImmunizationsCount": { "type": "integer", "format": "int32" }, "recentEncountersCount": { "type": "integer", "format": "int32" }, "recentProceduresCount": { "type": "integer", "format": "int32" }, "activeCarePlansCount": { "type": "integer", "format": "int32" }, "activeGoalsCount": { "type": "integer", "format": "int32" }, "recentActivityScore": { "type": "integer", "format": "int32" }, "healthAlerts": { "type": "array", "items": { "type": "string" } }, "immunizationComplianceStatus": { "type": "string" }, "medicationAdherenceRisk": { "type": "string" }, "hasActiveCarePlan": { "type": "boolean" }, "daysSinceLastEncounter": { "type": "integer", "format": "int32" } } }, "ConditionSummary": { "type": "object", "properties": { "activeCount": { "type": "integer", "format": "int32" }, "totalCount": { "type": "integer", "format": "int32" }, "activeConditionNames": { "type": "array", "items": { "type": "string" } }, "hasChronicConditions": { "type": "boolean" }, "severity": { "type": "string" } } }, "AuditMetadata": { "type": "object", "properties": { "decisionEventId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" }, "historyPath": { "type": "string" }, "correlationPath": { "type": "string" } } }, "BenchmarkContext": { "type": "object", "properties": { "label": { "type": "string" }, "source": { "type": "string" }, "note": { "type": "string" } } }, "ConfidenceRange": { "type": "object", "properties": { "low": { "type": "integer", "format": "int32" }, "high": { "type": "integer", "format": "int32" } } }, "DetailItem": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "EpisodeLinkage": { "type": "object", "properties": { "indexEpisodeId": { "type": "string" }, "episodeType": { "type": "string" }, "admissionTimestamp": { "type": "string", "format": "date-time" }, "dischargeTimestamp": { "type": "string", "format": "date-time" }, "dischargeDisposition": { "type": "string" } } }, "FeatureExplanation": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "weight": { "type": "integer", "format": "int32" }, "direction": { "type": "string" }, "rationale": { "type": "string" } } }, "MeasureDefinition": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "definition": { "type": "string" }, "alignment": { "type": "string" }, "timeHorizon": { "type": "string" } } }, "MeasurePayload": { "type": "object", "properties": { "measure": { "$ref": "#/components/schemas/MeasureDefinition" }, "displayValue": { "type": "string" }, "score": { "type": "number", "format": "double" }, "probabilityPercent": { "type": "number", "format": "double" }, "riskBand": { "type": "string" }, "benchmark": { "$ref": "#/components/schemas/BenchmarkContext" }, "modelVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "episodeLinkage": { "$ref": "#/components/schemas/EpisodeLinkage" }, "confidenceRange": { "$ref": "#/components/schemas/ConfidenceRange" }, "provenance": { "$ref": "#/components/schemas/PatientClinicalRiskProfileProvenance" }, "detailItems": { "type": "array", "items": { "$ref": "#/components/schemas/DetailItem" } }, "featureExplanations": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureExplanation" } }, "protectiveFeatures": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureExplanation" } }, "metadata": { "type": "object", "additionalProperties": { "type": "object" } } }, "description": "One canonical clinical-risk measure payload" }, "PatientClinicalRiskProfileProvenance": { "type": "object", "properties": { "status": { "type": "string" }, "sourceLabel": { "type": "string" }, "detail": { "type": "string" }, "modelVersion": { "type": "string" }, "featureSetVersion": { "type": "string" }, "benchmarkSnapshotVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "sourceDataTimestamps": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" } }, "auditMetadata": { "$ref": "#/components/schemas/AuditMetadata" }, "retentionPolicy": { "$ref": "#/components/schemas/RetentionPolicy" }, "warning": { "type": "string" } } }, "PatientClinicalRiskProfileResponse": { "type": "object", "properties": { "patientId": { "type": "string", "description": "Patient identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "generatedAt": { "type": "string", "description": "Timestamp when the profile payload was generated", "format": "date-time", "example": "2026-04-23T12:00:00Z" }, "modelVersion": { "type": "string", "description": "Backend-owned contract version", "example": "patient-clinical-risk-profile-v1" }, "note": { "type": "string", "description": "Human-readable note explaining the overall payload composition" }, "unsupportedMeasures": { "type": "array", "description": "Requested measure ids that are not supported by the canonical contract", "items": { "type": "string", "description": "Requested measure ids that are not supported by the canonical contract" } }, "unavailableMeasures": { "type": "array", "description": "Supported measure ids that could not be produced for the current patient snapshot", "items": { "type": "string", "description": "Supported measure ids that could not be produced for the current patient snapshot" } }, "measures": { "type": "array", "description": "Canonical measure payloads", "items": { "$ref": "#/components/schemas/MeasurePayload" } } }, "description": "Canonical patient-level clinical risk profile with multi-measure outputs" }, "RetentionPolicy": { "type": "object", "properties": { "policyName": { "type": "string" }, "retentionDays": { "type": "integer", "format": "int32" }, "storage": { "type": "string" } } }, "AcuteEpisodeResponse": { "type": "object", "properties": { "episodeId": { "type": "string", "description": "Stable backend episode identifier", "example": "enc-123" }, "encounterId": { "type": "string", "description": "FHIR encounter identifier that anchors the episode", "example": "enc-123" }, "episodeType": { "type": "string", "description": "Normalized acute episode type", "example": "INPATIENT", "enum": [ "INPATIENT", "EMERGENCY_DEPARTMENT", "OBSERVATION" ] }, "encounterClass": { "type": "string", "description": "FHIR encounter class code or derived class label", "example": "IMP" }, "acuity": { "type": "string", "description": "Normalized acuity label", "example": "high" }, "admissionTimestamp": { "type": "string", "description": "Episode admission timestamp", "format": "date-time", "example": "2026-04-01T14:00:00Z" }, "dischargeTimestamp": { "type": "string", "description": "Episode discharge timestamp", "format": "date-time", "example": "2026-04-04T16:15:00Z" }, "dischargeDisposition": { "type": "string", "description": "Encounter discharge disposition when available", "example": "home" }, "plannedIndexEncounter": { "type": "boolean", "description": "Whether the index encounter appears planned/elective", "example": false }, "transferChain": { "type": "boolean", "description": "Whether this episode is part of a transfer chain and should be excluded", "example": false }, "excluded": { "type": "boolean", "description": "Whether this episode is excluded from outcome calculations", "example": false }, "exclusionReasons": { "type": "array", "description": "Reasons this episode was excluded from modeling surfaces", "items": { "type": "string", "description": "Reasons this episode was excluded from modeling surfaces" } }, "followUpEvents": { "type": "array", "description": "Derived follow-up events for this acute episode", "items": { "$ref": "#/components/schemas/FollowUpEvent" } }, "outcomes": { "$ref": "#/components/schemas/Outcomes" } }, "description": "Normalized acute episode derived from encounter history" }, "ClinicalRiskFeatureResponse": { "type": "object", "properties": { "patientId": { "type": "string", "description": "Patient identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tenantId": { "type": "string", "description": "Tenant identifier", "example": "tenant-123" }, "generatedAt": { "type": "string", "description": "Timestamp when the feature payload was generated", "format": "date-time", "example": "2026-04-23T12:00:00Z" }, "featureSetVersion": { "type": "string", "description": "Backend feature-pipeline version", "example": "clinical-risk-feature-pipeline-v1" }, "latestAcuteEpisode": { "$ref": "#/components/schemas/AcuteEpisodeResponse" }, "acuteEpisodes": { "type": "array", "description": "All normalized acute episodes used to derive utilization outcomes", "items": { "$ref": "#/components/schemas/AcuteEpisodeResponse" } }, "featureGroups": { "type": "array", "description": "Named feature groups exposed by the backend pipeline", "items": { "$ref": "#/components/schemas/FeatureGroup" } }, "features": { "type": "array", "description": "Named features including provenance and missingness", "items": { "$ref": "#/components/schemas/FeatureEntry" } }, "modelInput": { "type": "object", "additionalProperties": { "type": "object", "description": "Model-ready feature map shared with downstream predictive services" }, "description": "Model-ready feature map shared with downstream predictive services" }, "sourceDataTimestamps": { "type": "object", "additionalProperties": { "type": "string", "description": "Most recent timestamps observed for upstream source families", "format": "date-time" }, "description": "Most recent timestamps observed for upstream source families" } }, "description": "Normalized clinical-risk feature payload with provenance and model-ready inputs" }, "FeatureEntry": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable feature key", "example": "age" }, "displayName": { "type": "string", "description": "Human-readable feature label", "example": "Age" }, "group": { "type": "string", "description": "Owning feature group", "example": "demographics" }, "dataType": { "type": "string", "description": "Data type used for the model-ready value", "example": "integer" }, "value": { "type": "object", "description": "Feature value" }, "missing": { "type": "boolean", "description": "Whether the value is missing from currently available source data", "example": false }, "provenance": { "$ref": "#/components/schemas/FeatureProvenance" } }, "description": "One normalized feature with provenance" }, "FeatureGroup": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable group key", "example": "demographics" }, "displayName": { "type": "string", "description": "Human-readable group name", "example": "Demographics" }, "featureKeys": { "type": "array", "description": "Feature keys included in the group", "items": { "type": "string", "description": "Feature keys included in the group" } } }, "description": "Feature group metadata" }, "FeatureProvenance": { "type": "object", "properties": { "sourceSystem": { "type": "string", "description": "Source system name", "example": "fhir-service" }, "sourcePath": { "type": "string", "description": "Upstream resource or endpoint used for the feature", "example": "/fhir/Observation/laboratory" }, "sourceWindow": { "type": "string", "description": "Date window or horizon applied when deriving the feature", "example": "latest available laboratory result" }, "observedAt": { "type": "string", "description": "Most relevant observed timestamp for this feature", "format": "date-time", "example": "2026-04-18T08:30:00Z" }, "missing": { "type": "boolean", "description": "Whether the upstream source was missing or not populated for this feature", "example": false }, "note": { "type": "string", "description": "Plain-language detail about how the value was derived" } }, "description": "Source provenance for one feature" }, "FollowUpEvent": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Follow-up event type", "example": "READMISSION", "enum": [ "READMISSION", "EMERGENCY_RETURN", "OBSERVATION_RETURN" ] }, "encounterId": { "type": "string", "description": "Follow-up encounter identifier", "example": "enc-456" }, "encounterClass": { "type": "string", "description": "Follow-up encounter class", "example": "IMP" }, "planned": { "type": "boolean", "description": "Whether the follow-up encounter appears planned/elective", "example": false }, "excluded": { "type": "boolean", "description": "Whether this follow-up event is excluded from outcome calculations", "example": false }, "exclusionReason": { "type": "string", "description": "Exclusion rationale for the follow-up event when excluded" }, "daysFromIndexDischarge": { "type": "integer", "description": "Days from discharge of the index episode to the start of the follow-up event", "format": "int32", "example": 7 }, "startTimestamp": { "type": "string", "description": "Start timestamp of the follow-up event", "format": "date-time", "example": "2026-04-11T09:00:00Z" }, "endTimestamp": { "type": "string", "description": "End timestamp of the follow-up event", "format": "date-time", "example": "2026-04-12T10:30:00Z" } }, "description": "A follow-up acute utilization event linked to the index episode" }, "Outcomes": { "type": "object", "properties": { "readmission30d": { "type": "boolean", "description": "Whether an unplanned inpatient readmission occurred within 30 days", "example": true }, "emergencyDepartmentReturn30d": { "type": "boolean", "description": "Whether an emergency department return occurred within 30 days", "example": false }, "observationStay30d": { "type": "boolean", "description": "Whether an observation stay occurred within 30 days", "example": false }, "death365d": { "type": "boolean", "description": "Whether patient death occurred within 365 days after discharge", "example": false }, "lengthOfStayDays": { "type": "integer", "description": "Length of stay for the index episode in days", "format": "int32", "example": 3 }, "costProxyAmount": { "type": "number", "description": "Internal proxy amount for expected acute event cost", "example": 17550.0 }, "expectedCostTier": { "type": "string", "description": "Internal cost tier label derived from episode utilization", "example": "high" }, "expectedCostInputs": { "type": "object", "additionalProperties": { "type": "object", "description": "Internal inputs used to derive the cost proxy and tier" }, "description": "Internal inputs used to derive the cost proxy and tier" } }, "description": "Outcome rollup for a normalized acute episode" }, "AllergySummary": { "type": "object", "properties": { "criticalCount": { "type": "integer", "format": "int32" }, "totalCount": { "type": "integer", "format": "int32" }, "criticalAllergens": { "type": "array", "items": { "type": "string" } }, "hasMedicationAllergies": { "type": "boolean" }, "hasCriticalAllergies": { "type": "boolean" } } }, "AgendaItem": { "type": "object", "properties": { "topic": { "type": "string" }, "timeEstimate": { "type": "string" }, "priority": { "type": "integer", "format": "int32" }, "category": { "type": "string" }, "rationale": { "type": "string" }, "talkingPoints": { "type": "array", "items": { "type": "string" } } } }, "CareGapItem": { "type": "object", "properties": { "gapId": { "type": "string" }, "measureId": { "type": "string" }, "measureName": { "type": "string" }, "priority": { "type": "string" }, "recommendation": { "type": "string" }, "dueDate": { "type": "string", "format": "date" }, "gapCategory": { "type": "string" }, "suggestedActions": { "type": "array", "items": { "type": "string" } } } }, "MedicationItem": { "type": "object", "properties": { "name": { "type": "string" }, "dosage": { "type": "string" }, "frequency": { "type": "string" }, "adherence": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "prescriber": { "type": "string" }, "status": { "type": "string" }, "potentialIssues": { "type": "array", "items": { "type": "string" } } } }, "PatientDemographics": { "type": "object", "properties": { "age": { "type": "integer", "format": "int32" }, "gender": { "type": "string" }, "preferredLanguage": { "type": "string" }, "primaryInsurance": { "type": "string" }, "phoneNumber": { "type": "string" }, "lastVisitDate": { "type": "string", "format": "date" } } }, "PreVisitSummaryResponse": { "type": "object", "properties": { "patientId": { "type": "string" }, "patientName": { "type": "string" }, "appointmentDate": { "type": "string", "format": "date-time" }, "appointmentType": { "type": "string" }, "careGaps": { "type": "array", "items": { "$ref": "#/components/schemas/CareGapItem" } }, "recentResults": { "type": "array", "items": { "$ref": "#/components/schemas/RecentResultItem" } }, "medications": { "type": "array", "items": { "$ref": "#/components/schemas/MedicationItem" } }, "suggestedAgenda": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaItem" } }, "lastVisitSummary": { "type": "string" }, "demographics": { "$ref": "#/components/schemas/PatientDemographics" }, "riskIndicators": { "$ref": "#/components/schemas/RiskIndicators" }, "generatedAt": { "type": "string", "format": "date-time" } } }, "RecentResultItem": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "unit": { "type": "string" }, "date": { "type": "string", "format": "date" }, "trend": { "type": "string" }, "previousValue": { "type": "string" }, "previousDate": { "type": "string", "format": "date" }, "interpretation": { "type": "string" }, "loincCode": { "type": "string" } } }, "RiskIndicators": { "type": "object", "properties": { "hccScore": { "type": "number" }, "riskLevel": { "type": "string" }, "chronicConditions": { "type": "array", "items": { "type": "string" } }, "hasRecentHospitalization": { "type": "boolean" }, "hasRecentEDVisit": { "type": "boolean" }, "missedAppointments": { "type": "integer", "format": "int32" } } }, "PageProviderPanelResponse": { "type": "object", "properties": { "totalPages": { "type": "integer", "format": "int32" }, "totalElements": { "type": "integer", "format": "int64" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "size": { "type": "integer", "format": "int32" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderPanelResponse" } }, "number": { "type": "integer", "format": "int32" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } }, "numberOfElements": { "type": "integer", "format": "int32" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "empty": { "type": "boolean" } } }, "PageableObject": { "type": "object", "properties": { "offset": { "type": "integer", "format": "int64" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } }, "pageNumber": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" }, "paged": { "type": "boolean" }, "unpaged": { "type": "boolean" } } }, "SortObject": { "type": "object", "properties": { "direction": { "type": "string" }, "nullHandling": { "type": "string" }, "ascending": { "type": "boolean" }, "property": { "type": "string" }, "ignoreCase": { "type": "boolean" } } }, "PagePatientDemographicsEntity": { "type": "object", "properties": { "totalPages": { "type": "integer", "format": "int32" }, "totalElements": { "type": "integer", "format": "int64" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "size": { "type": "integer", "format": "int32" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/PatientDemographicsEntity" } }, "number": { "type": "integer", "format": "int32" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } }, "numberOfElements": { "type": "integer", "format": "int32" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "empty": { "type": "boolean" } } }, "PatientDemographicsEntity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "fhirPatientId": { "type": "string" }, "mrn": { "type": "string" }, "ssnEncrypted": { "type": "string", "nullable": true }, "firstName": { "type": "string" }, "middleName": { "type": "string", "nullable": true }, "lastName": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "gender": { "type": "string" }, "race": { "type": "string", "nullable": true }, "ethnicity": { "type": "string", "nullable": true }, "preferredLanguage": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "addressLine1": { "type": "string", "nullable": true }, "addressLine2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zipCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "deceased": { "type": "boolean" }, "deceasedDate": { "type": "string", "format": "date", "nullable": true }, "pcpId": { "type": "string", "nullable": true }, "pcpName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CohortContext": { "type": "object", "properties": { "membershipState": { "type": "string" }, "activeCohortCount": { "type": "integer", "format": "int32" }, "cohortLabels": { "type": "array", "items": { "type": "string" } }, "inclusionReason": { "type": "string" }, "note": { "type": "string" } }, "description": "Cohort context placeholder carried in the contract before cohort sync work is implemented" }, "Completeness": { "type": "object", "properties": { "scorePercent": { "type": "integer", "format": "int32" }, "availableRequiredDataClassCount": { "type": "integer", "format": "int32" }, "requiredDataClassCount": { "type": "integer", "format": "int32" }, "availableDataClasses": { "type": "array", "items": { "type": "string" } }, "missingRequiredDataClasses": { "type": "array", "items": { "type": "string" } } }, "description": "Canonical completeness summary for the foundational patient data classes" }, "Coverage": { "type": "object", "properties": { "coverageType": { "type": "string" }, "payerName": { "type": "string" }, "payerId": { "type": "string" }, "planName": { "type": "string" }, "memberId": { "type": "string" }, "primary": { "type": "boolean" }, "active": { "type": "boolean" }, "effectiveDate": { "type": "string", "format": "date" }, "terminationDate": { "type": "string", "format": "date" } }, "description": "Insurance coverage summaries linked to the patient" }, "CrossReference": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "note": { "type": "string" } } }, "Demographics": { "type": "object", "properties": { "fullName": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string", "nullable": true }, "lastName": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "gender": { "type": "string" }, "race": { "type": "string", "nullable": true }, "ethnicity": { "type": "string", "nullable": true }, "preferredLanguage": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "primaryCareProviderId": { "type": "string", "nullable": true }, "primaryCareProviderName": { "type": "string", "nullable": true } }, "description": "Patient demographic summary" }, "Identity": { "type": "object", "properties": { "enterprisePatientId": { "type": "string" }, "fhirPatientId": { "type": "string" }, "medicalRecordNumber": { "type": "string" }, "active": { "type": "boolean" }, "deceased": { "type": "boolean" }, "crossReferences": { "type": "array", "items": { "$ref": "#/components/schemas/CrossReference" } } }, "description": "Identity spine and cross-reference aliases" }, "LocationSummary": { "type": "object", "properties": { "state": { "type": "string" }, "freshness": { "type": "string" }, "confidence": { "type": "string" }, "display": { "type": "string" }, "encounterId": { "type": "string" }, "encounterStatus": { "type": "string" }, "lastObservedAt": { "type": "string", "format": "date-time" }, "note": { "type": "string" } }, "description": "Encounter-derived location summary for the patient" }, "PatientRegionalProfileProvenance": { "type": "object", "properties": { "state": { "type": "string" }, "headline": { "type": "string" }, "detail": { "type": "string" }, "resourceTypeCounts": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } }, "sourceSummaries": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSummary" } } }, "description": "Provenance and source freshness metadata for the foundational profile" }, "PatientRegionalProfileResponse": { "type": "object", "properties": { "patientId": { "type": "string", "description": "Enterprise patient identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tenantId": { "type": "string", "description": "Tenant identifier", "example": "tenant-123" }, "fhirPatientId": { "type": "string", "description": "FHIR patient identifier", "example": "patient-fhir-123" }, "contractVersion": { "type": "string", "description": "Canonical contract version", "example": "regional-patient-profile-v1" }, "generatedAt": { "type": "string", "description": "Timestamp when the regional profile payload was generated", "format": "date-time", "example": "2026-04-23T12:00:00Z" }, "note": { "type": "string", "description": "Human-readable note describing how the profile was assembled" }, "identity": { "$ref": "#/components/schemas/Identity" }, "demographics": { "$ref": "#/components/schemas/Demographics" }, "coverages": { "type": "array", "description": "Insurance coverage summaries linked to the patient", "items": { "$ref": "#/components/schemas/Coverage" } }, "completeness": { "$ref": "#/components/schemas/Completeness" }, "provenance": { "$ref": "#/components/schemas/PatientRegionalProfileProvenance" }, "cohortContext": { "$ref": "#/components/schemas/CohortContext" }, "locationSummary": { "$ref": "#/components/schemas/LocationSummary" } }, "description": "Canonical regional patient profile foundation payload" }, "SourceSummary": { "type": "object", "properties": { "sourceId": { "type": "string" }, "sourceLabel": { "type": "string" }, "available": { "type": "boolean" }, "recordCount": { "type": "integer", "format": "int32" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "nullable": true }, "note": { "type": "string" } } }, "RiskStratificationSummaryResponse": { "type": "object", "description": "Non-PHI aggregate risk-tier distribution for a tenant", "properties": { "scoreType": { "type": "string", "description": "Risk score type the distribution was computed over", "example": "COMPOSITE_RISK" }, "totalPatients": { "type": "integer", "format": "int64", "description": "Total number of patients with a current risk score in this tenant", "example": 1980 }, "tiers": { "type": "array", "description": "Per-tier counts (HIGH, MEDIUM, LOW)", "items": { "$ref": "#/components/schemas/RiskStratificationSummaryResponse_TierCount" } }, "generatedAt": { "type": "string", "format": "date-time", "description": "When this distribution was computed", "example": "2026-06-07T05:34:00Z" } } }, "RiskStratificationSummaryResponse_TierCount": { "type": "object", "description": "Count of patients in a single risk tier", "properties": { "riskCategory": { "type": "string", "description": "Risk category label", "example": "HIGH" }, "count": { "type": "integer", "format": "int64", "description": "Number of patients in this tier", "example": 243 } } } }, "securitySchemes": { "BearerAuthentication": { "type": "http", "description": "JWT Bearer token from the Authentication Service.\n\n**How to obtain a token:**\n1. POST to `/api/v1/auth/login` with credentials\n2. Extract the `accessToken` from the response\n3. Click \"Authorize\" button above and enter: `Bearer `\n\n**Token format:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n\n**Token expiration:** 1 hour (configurable)\n", "scheme": "bearer", "bearerFormat": "JWT" } } } }