{
  "openapi": "3.0.3",
  "info": {
    "title": "RCM Claims Workflow API",
    "description": "Comprehensive API documentation for Revenue Cycle Management system with AI-powered agents",
    "version": "1.0.0",
    "contact": {
      "name": "RCM API Support",
      "email": "api-support@rcm-system.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.rcm-system.com/v1",
      "description": "Production server"
    },
    {
      "url": "https://staging-api.rcm-system.com/v1",
      "description": "Staging server"
    }
  ],
  "tags": [
    {
      "name": "Patient Intake",
      "description": "Patient registration and document processing"
    },
    {
      "name": "Eligibility",
      "description": "Insurance eligibility verification"
    },
    {
      "name": "Clinical Coding",
      "description": "Medical coding and billing code generation"
    },
    {
      "name": "Claims Processing",
      "description": "Claims validation, scrubbing, and submission"
    },
    {
      "name": "Payment Processing",
      "description": "Payment posting and reconciliation"
    },
    {
      "name": "Denial Management",
      "description": "Claim denial analysis and appeals"
    },
    {
      "name": "Analytics",
      "description": "RCM insights and reporting"
    },
    {
      "name": "Data Services",
      "description": "Document processing and data extraction"
    },
    {
      "name": "Patient Records",
      "description": "Patient data management"
    },
    {
      "name": "External Integration",
      "description": "Third-party system integrations"
    }
  ],
  "paths": {
    "/agents/patient-intake/process": {
      "post": {
        "tags": [
          "Patient Intake"
        ],
        "summary": "Process patient intake documents",
        "description": "Process patient registration documents using Bedrock Data Automation",
        "operationId": "processPatientIntake",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatientIntakeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Patient intake processed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PatientIntakeResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agents/eligibility/verify": {
      "post": {
        "tags": [
          "Eligibility"
        ],
        "summary": "Verify insurance eligibility",
        "description": "Real-time verification of patient insurance coverage and benefits",
        "operationId": "verifyEligibility",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EligibilityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Eligibility verification completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EligibilityResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agents/coding/generate-codes": {
      "post": {
        "tags": [
          "Clinical Coding"
        ],
        "summary": "Generate medical billing codes",
        "description": "Convert clinical documentation to ICD-10 and CPT codes",
        "operationId": "generateMedicalCodes",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CodingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Medical codes generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodingResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agents/scrubber/validate-claim": {
      "post": {
        "tags": [
          "Claims Processing"
        ],
        "summary": "Validate and scrub claim data",
        "description": "Validate claim data for errors and ensure clean submission",
        "operationId": "validateClaim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClaimValidationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim validation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimValidationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agents/submission/submit-claim": {
      "post": {
        "tags": [
          "Claims Processing"
        ],
        "summary": "Submit claim electronically",
        "description": "Submit validated claim to insurance payer via EDI",
        "operationId": "submitClaim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClaimSubmissionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agents/payment/post-payment": {
      "post": {
        "tags": [
          "Payment Processing"
        ],
        "summary": "Post insurance payment",
        "description": "Process and post insurance payment to patient account",
        "operationId": "postPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentPostingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment posted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentPostingResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agents/insights/analytics": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "summary": "Get RCM analytics",
        "description": "Retrieve comprehensive RCM performance metrics and KPIs",
        "operationId": "getRCMAnalytics",
        "parameters": [
          {
            "name": "startDate",
            "in": "query",
            "description": "Start date for analytics period",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "End date for analytics period",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Analytics data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/patients/{patientId}": {
      "get": {
        "tags": [
          "Patient Records"
        ],
        "summary": "Get patient information",
        "description": "Retrieve comprehensive patient information by ID",
        "operationId": "getPatient",
        "parameters": [
          {
            "name": "patientId",
            "in": "path",
            "description": "Unique patient identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Patient information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Patient"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PatientIntakeRequest": {
        "type": "object",
        "required": [
          "patientId",
          "documents"
        ],
        "properties": {
          "patientId": {
            "type": "string",
            "description": "Unique patient identifier"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            },
            "description": "Patient intake documents to process"
          },
          "extractionOptions": {
            "type": "object",
            "properties": {
              "extractDemographics": {
                "type": "boolean",
                "default": true
              },
              "extractInsurance": {
                "type": "boolean",
                "default": true
              },
              "extractMedicalHistory": {
                "type": "boolean",
                "default": true
              }
            }
          }
        }
      },
      "PatientIntakeResponse": {
        "type": "object",
        "properties": {
          "patientId": {
            "type": "string"
          },
          "processingStatus": {
            "type": "string",
            "enum": [
              "completed",
              "partial",
              "failed"
            ]
          },
          "extractedData": {
            "type": "object",
            "properties": {
              "demographics": {
                "$ref": "#/components/schemas/Demographics"
              },
              "insurance": {
                "$ref": "#/components/schemas/Insurance"
              },
              "medicalHistory": {
                "$ref": "#/components/schemas/MedicalHistory"
              }
            }
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "processingTime": {
            "type": "number",
            "description": "Processing time in seconds"
          }
        }
      },
      "EligibilityRequest": {
        "type": "object",
        "required": [
          "patientId",
          "insuranceInfo",
          "serviceDate"
        ],
        "properties": {
          "patientId": {
            "type": "string"
          },
          "insuranceInfo": {
            "$ref": "#/components/schemas/Insurance"
          },
          "serviceDate": {
            "type": "string",
            "format": "date"
          },
          "serviceType": {
            "type": "string",
            "description": "Type of service being verified"
          }
        }
      },
      "EligibilityResponse": {
        "type": "object",
        "properties": {
          "eligible": {
            "type": "boolean"
          },
          "coverage": {
            "type": "object",
            "properties": {
              "deductible": {
                "type": "number"
              },
              "deductibleRemaining": {
                "type": "number"
              },
              "copay": {
                "type": "number"
              },
              "coinsurance": {
                "type": "number"
              },
              "outOfPocketMax": {
                "type": "number"
              },
              "outOfPocketRemaining": {
                "type": "number"
              }
            }
          },
          "effectiveDate": {
            "type": "string",
            "format": "date"
          },
          "terminationDate": {
            "type": "string",
            "format": "date"
          },
          "verificationDate": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CodingRequest": {
        "type": "object",
        "required": [
          "patientId",
          "clinicalNotes"
        ],
        "properties": {
          "patientId": {
            "type": "string"
          },
          "clinicalNotes": {
            "type": "string",
            "description": "Clinical documentation to code"
          },
          "encounterDate": {
            "type": "string",
            "format": "date"
          },
          "providerId": {
            "type": "string"
          },
          "codingOptions": {
            "type": "object",
            "properties": {
              "generateICD10": {
                "type": "boolean",
                "default": true
              },
              "generateCPT": {
                "type": "boolean",
                "default": true
              },
              "generateHCPCS": {
                "type": "boolean",
                "default": false
              }
            }
          }
        }
      },
      "CodingResponse": {
        "type": "object",
        "properties": {
          "patientId": {
            "type": "string"
          },
          "codes": {
            "type": "object",
            "properties": {
              "icd10": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MedicalCode"
                }
              },
              "cpt": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MedicalCode"
                }
              },
              "hcpcs": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MedicalCode"
                }
              }
            }
          },
          "totalCharges": {
            "type": "number"
          },
          "codingAccuracy": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "Patient": {
        "type": "object",
        "properties": {
          "patientId": {
            "type": "string"
          },
          "demographics": {
            "$ref": "#/components/schemas/Demographics"
          },
          "insurance": {
            "$ref": "#/components/schemas/Insurance"
          },
          "medicalHistory": {
            "$ref": "#/components/schemas/MedicalHistory"
          },
          "createdDate": {
            "type": "string",
            "format": "date-time"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Demographics": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "dateOfBirth": {
            "type": "string",
            "format": "date"
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F",
              "O"
            ]
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "Insurance": {
        "type": "object",
        "properties": {
          "payerId": {
            "type": "string"
          },
          "payerName": {
            "type": "string"
          },
          "memberId": {
            "type": "string"
          },
          "groupNumber": {
            "type": "string"
          },
          "planType": {
            "type": "string"
          },
          "effectiveDate": {
            "type": "string",
            "format": "date"
          },
          "terminationDate": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "MedicalHistory": {
        "type": "object",
        "properties": {
          "chronicConditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allergies": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "medications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Medication"
            }
          },
          "previousHospitalizations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hospitalization"
            }
          }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "documentId": {
            "type": "string"
          },
          "documentType": {
            "type": "string",
            "enum": [
              "insurance_card",
              "drivers_license",
              "medical_form",
              "clinical_notes"
            ]
          },
          "content": {
            "type": "string",
            "description": "Base64 encoded document content"
          },
          "mimeType": {
            "type": "string"
          },
          "uploadDate": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MedicalCode": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "codeSystem": {
            "type": "string",
            "enum": [
              "ICD-10",
              "CPT",
              "HCPCS"
            ]
          },
          "charge": {
            "type": "number"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "street": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zipCode": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "default": "US"
          }
        }
      },
      "Medication": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "dosage": {
            "type": "string"
          },
          "frequency": {
            "type": "string"
          },
          "startDate": {
            "type": "string",
            "format": "date"
          },
          "endDate": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "Hospitalization": {
        "type": "object",
        "properties": {
          "admissionDate": {
            "type": "string",
            "format": "date"
          },
          "dischargeDate": {
            "type": "string",
            "format": "date"
          },
          "reason": {
            "type": "string"
          },
          "facility": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request - invalid input parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    },
    {
      "ApiKeyAuth": []
    }
  ]
}