openapi: 3.0.3
info:
  title: MAHATI Systems API Documentation
  version: 2.0.0
  description: >
    Complete API documentation for all MAHATI microservices including Admin, Gateway,
    Audit, Billing, Claims, Command Line, Document, External Integration, Individual,
    Policy, Policy Transaction, Reinsurance, and Relationship services.
    All endpoints are protected with Bearer JWT authentication.
  contact:
    name: MAHATI Systems
    email: support@mahatisystems.com
    url: https://www.mahatisystems.com

servers:
  - url: http://localhost:3005
    description: Document Service
  - url: http://localhost:3020
    description: Application Service  
  - url: http://localhost:3025
    description: Billing Service
  - url: http://localhost:3026
    description: Claims Service
  - url: http://localhost:3027
    description: Individual Service
  - url: http://localhost:3028
    description: Policy Service
  - url: http://localhost:3029
    description: Policy Transaction Service
  - url: http://localhost:3030
    description: Reinsurance Service
  - url: http://localhost:3031
    description: Relationship Service
  - url: http://localhost:3032
    description: Command Line Service
  - url: http://localhost:3033
    description: Admin Service
  - url: http://localhost:3034
    description: External Integration Service
  - url: http://localhost:3035
    description: Audit Service
  - url: http://localhost:3036
    description: Audit Service

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    # Common Error Response
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        message:
          type: string
        details:
          type: object
          nullable: true

    # Admin Service Schemas
    TruncateDBRequest:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string

    ListTablesRequest:
      type: object
      properties:
        schema:
          oneOf:
            - type: string
            - type: array
              items:
                type: string

    FetchTableDataRequest:
      type: object
      properties:
        schemaName:
          type: string
        tableName:
          type: string
        metadata:
          type: boolean
        tableNames:
          type: array
          items:
            type: string

    AddRowRequest:
      type: object
      properties:
        schemaName:
          type: string
        tableName:
          type: string
        rowData:
          type: object
      required:
        - schemaName
        - tableName
        - rowData

    UpdateRowRequest:
      type: object
      properties:
        schemaName:
          type: string
        tableName:
          type: string
        id:
          type: integer
        rowData:
          type: object
      required:
        - schemaName
        - tableName
        - id
        - rowData

    DeleteRowRequest:
      type: object
      properties:
        schemaName:
          type: string
        tableName:
          type: string
        id:
          type: integer
      required:
        - schemaName
        - tableName
        - id

    SampleDataRequest:
      type: object
      properties:
        templateData:
          type: string

    ImportConnectorRequest:
      type: object
      properties:
        base64Data:
          type: string
        topRows:
          type: integer
      required:
        - base64Data

    # Application Service Schemas
    ChatbotRequest:
      type: object
      required:
        - contextTableName
        - userInput
      properties:
        contextTableName:
          type: string
          example: policies
        userInput:
          type: string
          example: fdfdf

    ChatbotResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        options:
          type: array
          items:
            type: string
        botAvatarUrl:
          type: string
        userAvatarUrl:
          type: string

    ChatConversation:
      type: object
      required:
        - name
        - email
        - StartTime
        - FinishTime
        - chatHistory
        - referenceNumber
        - contextTableName
      properties:
        name:
          type: string
          example: Brett Okerson
        email:
          type: string
          example: bokerson@gmail.com
        StartTime:
          type: string
          format: date-time
          example: 2025-11-03T06:59:50.657Z
        FinishTime:
          type: string
          format: date-time
          example: 2025-11-03T07:13:04.985Z
        chatHistory:
          type: array
          items:
            type: object
            properties:
              sender:
                type: string
                enum: [bot, user]
              message:
                type: string
              avatarUrl:
                type: string
                nullable: true
              options:
                type: array
                items:
                  type: string
        referenceNumber:
          type: string
          example: "1000000074"
        contextTableName:
          type: string
          example: policies

    FeedbackRequest:
      type: object
      required:
        - feedback
        - rating
        - referenceNumber
        - email
        - screen
        - StartTime
        - FinishTime
      properties:
        feedback:
          type: string
          example: fsdff
        rating:
          type: integer
          minimum: 1
          maximum: 5
          example: 5
        referenceNumber:
          type: string
          example: "1000000074"
        email:
          type: string
          example: bokerson@gmail.com
        screen:
          type: string
          example: home
        StartTime:
          type: string
          format: date-time
        FinishTime:
          type: string
          format: date-time

    Product:
      type: object
      properties:
        Id:
          type: string
        Code:
          type: string
        Name:
          type: string
        NotInUse:
          type: boolean

    CapabilityRole:
      type: object
      properties:
        Id:
          type: string
        Name:
          type: string
        EffectiveDate:
          type: string
          format: date-time
        ExpirationDate:
          type: string
          format: date-time
          nullable: true
        CapabilityRoleNumber:
          type: string

    # Audit Service Schemas
    AuditFilterOption:
      type: object
      properties:
        value:
          type: string
          example: "1000000078"
        label:
          type: string
          example: "Tina Howlenski"

    AuditCategoryOption:
      type: object
      properties:
        Id:
          type: string
          example: "1"
        Name:
          type: string
          example: "Policy"

    TableOption:
      type: object
      properties:
        TableName:
          type: string
          example: "insurance.Policy"

    FieldOption:
      type: object
      properties:
        FieldName:
          type: string
          example: "Status"

    DataAuditRecord:
      type: object
      properties:
        Id:
          type: string
          example: "101"
        TableName:
          type: string
          example: "insurance.Policy"
        FieldName:
          type: string
          example: "Status"
        OldValue:
          type: string
          example: "Expired"
        NewValue:
          type: string
          example: "Active"
        ChangedBy:
          type: string
          example: "Tina Howlenski"
        ChangedDate:
          type: string
          format: date-time
          example: "2025-02-12T10:20:00.000Z"
        AuditCategory:
          type: string
          example: "Policy"

    SchemaAuditRecord:
      type: object
      properties:
        Id:
          type: string
          example: "55"
        TableName:
          type: string
          example: "base.User"
        FieldName:
          type: string
          example: "UserName"
        OldValue:
          type: string
          example: "john"
        NewValue:
          type: string
          example: "john1"
        ChangedBy:
          type: string
          example: "Bob Hughes"
        ChangedDate:
          type: string
          format: date-time
          example: "2025-02-01T08:20:00.000Z"
        SchemaCategory:
          type: string
          example: "User"

    # Billing Service Schemas
    BilledItem:
      type: object
      properties:
        BilledItemId:
          type: string
          example: "68"
        BilledItemNumber:
          type: string
          example: "1000000068"
        BilledAmount:
          type: string
          example: "1634"
        OutstandingAmount:
          type: string
          nullable: true
        WriteOffAmount:
          type: string
          nullable: true
        AgingDate:
          type: string
          format: date-time
          example: "2024-08-10T18:30:00.000Z"
        PolicyNumber:
          type: string
          example: "COPA-100001"
        InceptionDate:
          type: string
          format: date-time
          example: "2024-02-28T18:30:00.000Z"
        RelationshipNumber:
          type: string
          example: "1000000025"

    CashAllocation:
      type: object
      properties:
        BilledItemNumber:
          type: string
        billedamount:
          type: string
        AgingDate:
          type: string
          format: date-time
        AllocatedAmount:
          type: string
        allocateddate:
          type: string
          format: date-time
        cashdirectionname:
          type: string
        cashtransfermode:
          type: string
        receiveddate:
          type: string
          format: date-time
        receivedamount:
          type: string
        ReferenceId:
          type: string
        individualname:
          type: string
          nullable: true
        officename:
          type: string
          nullable: true

    # Claims Service Schemas
    ClaimSummary:
      type: object
      properties:
        Id:
          type: string
          example: "1"
        ClaimNumber:
          type: string
          example: "PEAU-CL-10001"
        DateOfLoss:
          type: string
          format: date-time
          example: "2022-06-04T18:30:00.000Z"
        PolicyNumber:
          type: string
          example: "PEAU-100001"
        Status:
          type: string
          example: "Closed"
        ClaimStatusCode:
          type: string
          example: "Closed"
        AddressLine1:
          type: string
          example: "5 Pearl St"
        AddressLine2:
          type: string
          nullable: true
        AddressLine3:
          type: string
          nullable: true
        StateName:
          type: string
          example: "New Jersey"
        CountryName:
          type: string
          example: "United States of Americaa"

    ExposureRef:
      type: object
      properties:
        ExposureNumber:
          type: string
          example: "PEAU-EXP-10001"
        CoverageNumber:
          type: string
          example: "1000000009"
        SubCoverageNumber:
          type: string
          example: "1000000001"
        CoverableNumber:
          type: string
          example: "1000000004"
        Status:
          type: string
          example: "Closed"

    # Document Service Schemas
    DocumentMetadata:
      type: object
      properties:
        Id:
          type: string
        DocumentName:
          type: string
        DocumentType:
          type: string
        FilePath:
          type: string
        MimeType:
          type: string
        UploadedBy:
          type: string
        RelationshipId:
          type: string
        UploadedAt:
          type: string
          format: date-time
        is_parsed:
          type: integer
          example: 0

    DocumentContent:
      type: object
      properties:
        Id:
          type: string
        DocumentId:
          type: string
        ParsedText:
          type: string
        StructuredData:
          type: object
        ParsedBy:
          type: string
        ParsedAt:
          type: string
          format: date-time

    UploadResponse:
      type: object
      properties:
        message:
          type: string
        document:
          $ref: "#/components/schemas/DocumentMetadata"

    # Integration Service Schemas
    RunIntegrationRequest:
      type: object
      properties:
        apiUrl:
          type: string
          description: External API URL to call
          example: "https://us-street.api.smarty.com/street-address?key=API_KEY"
        callbackUrl:
          type: string
          description: Internal callback URL which will receive the verification results
          example: "http://localhost:3034/api/integration/integrationAddress"
        maxRetries:
          type: integer
          format: int32
          description: Maximum number of automatic retries for the job
          default: 3
        payload:
          type: array
          description: Array containing payload objects
          items:
            type: object

    # Individual Service Schemas
    Interaction:
      type: object
      properties:
        Id:
          type: string
          example: "1"
        Date:
          type: string
          format: date-time
          example: "2025-06-12T18:30:00.000Z"
        Sensitive:
          type: boolean
          example: false
        DistributionChannel:
          type: string
          example: "13"
        ContextTableName:
          type: string
          nullable: true
        ContextUniqueId:
          type: string
          nullable: true
          example: "3"
        Content:
          type: string
          example: "Testing"
        FromIndividualPersona:
          type: string
          example: "Christine Ward"
        ToIndividualPersona:
          type: string
          nullable: true

    # Policy Service Schemas
    Policy:
      type: object
      properties:
        PolicyNumber:
          type: string
        InceptionDate:
          type: string
          format: date-time
        RiskState:
          type: string
        RiskStateName:
          type: string
        RiskPostalCode:
          type: string
        PolicyStatus:
          type: string
        PolicyStatusName:
          type: string
        Product:
          type: string
        ProductName:
          type: string
        Relationship:
          type: string
        RelationshipNumber:
          type: string
        LegalEntity:
          type: string
          nullable: true
        LegalEntityCode:
          type: string
          nullable: true
        MostRecentInteraction:
          type: string
          nullable: true
        MostRecentInteractionDetail:
          type: string
          nullable: true
        RiskType:
          type: string
        RiskTypeName:
          type: string

    # Policy Transaction Schemas
    PolicyTerm:
      type: object
      properties:
        TermNumber:
          type: string
        EffectiveDate:
          type: string
          format: date-time
        ExpirationDate:
          type: string
          format: date-time
          nullable: true
        PolicyTermUniqueNumber:
          type: string
        TermLength:
          type: string
          nullable: true
        TermLengthName:
          type: string
          nullable: true
        InstallmentType:
          type: string
          nullable: true
        InstallmentTypeName:
          type: string
          nullable: true
        Policy:
          type: string
          nullable: true
        PolicyNumber:
          type: string
          nullable: true

    PolicyTransaction:
      type: object
      properties:
        PolicyTerm:
          type: string
        PolicyTermNumber:
          type: string
          nullable: true
        Type:
          type: string
        PolicyTransactionTypeName:
          type: string
          nullable: true
        Status:
          type: string
          nullable: true
        PolicyTransactionStatusName:
          type: string
          nullable: true
        CreatedDate:
          type: string
          format: date-time
          nullable: true
        CompletedDate:
          type: string
          format: date-time
          nullable: true
        EffectiveDate:
          type: string
          format: date-time
          nullable: true
        PolicyTransactionNumber:
          type: string

    # Relationship Service Schemas
    Relationship:
      type: object
      properties:
        Id:
          type: string
        RelationshipNumber:
          type: string
        Individual:
          type: string
        IndividualNumber:
          type: string
        IndividualFirstName:
          type: string
        IndividualLastName:
          type: string
        Company:
          type: string
          nullable: true
        CompanyFEIN:
          type: string
          nullable: true
        CompanyName:
          type: string
          nullable: true
        Status:
          type: string
        StatusName:
          type: string
        Segment:
          type: string
        SegmentName:
          type: string
        Tier:
          type: string
        TierName:
          type: string
        EffectiveDate:
          type: string
          format: date-time
        ExpirationDate:
          type: string
          format: date-time
          nullable: true

    # Command Line Service Schemas
    CheckDataQualityRequest:
      type: object
      properties:
        username:
          type: string
          description: Username to run pre-process checks for
          example: tinaj
      required:
        - username

    ChangeDataCaptureRequest:
      type: object
      properties:
        username:
          type: string
          description: Username of the requester
          example: tinaj
        base64Data:
          type: string
          nullable: true
          description: Base64-encoded Excel file
        applySchema:
          type: boolean
          description: If true, detected schema changes will be applied
          example: false
        applyData:
          type: boolean
          description: If true, detected data changes will be applied
          example: false
      required:
        - username

    # Data Service Schemas
    DataServiceBilledItemRequest:
      type: object
      required:
        - billedItem
      properties:
        billedItem:
          $ref: '#/components/schemas/DataServiceBilledItem'

    DataServiceBilledItem:
      type: object
      required:
        - BilledItemNumber
        - AgingDate
        - Amount
        - OutstandingAmount
      properties:
        BilledItemNumber:
          type: integer
          example: 10001
        AgingDate:
          type: string
          format: date
          example: "2022-10-28"
        Amount:
          type: number
          example: 112
        OutstandingAmount:
          type: number
          example: 112
        WriteOffAmount:
          type: number
          nullable: true
        relationshipCharge:
          $ref: '#/components/schemas/DataServiceRelationshipCharge'
          nullable: true
        policyTransactionCost:
          $ref: '#/components/schemas/DataServicePolicyTransactionCost'
          nullable: true

    DataServiceRelationshipCharge:
      type: object
      required:
        - RelationshipChargeNumber
        - Amount
        - relationship
      properties:
        RelationshipChargeNumber:
          type: integer
          example: 1000000001
        Amount:
          type: number
          example: 112
        relationship:
          $ref: '#/components/schemas/DataServiceRelationship'

    DataServicePolicyTransactionCost:
      type: object
      required:
        - PolicyTransactionCostNumber
        - OriginalAmount
        - policyTransaction
      properties:
        PolicyTransactionCostNumber:
          type: integer
          example: 50002
        OriginalAmount:
          type: number
          example: 88.5
        policyTransaction:
          $ref: '#/components/schemas/DataServicePolicyTransaction'

    DataServicePolicyTransaction:
      type: object
      required:
        - PolicyTransactionNumber
        - Type
        - CreatedDate
        - policy
      properties:
        PolicyTransactionNumber:
          type: integer
          example: 60002
        Type:
          type: integer
          example: 1
        CreatedDate:
          type: string
          format: date
          example: "2024-02-10"
        policy:
          $ref: '#/components/schemas/DataServicePolicy'

    DataServicePolicy:
      type: object
      required:
        - PolicyNumber
        - Product
        - PolicyStatus
        - relationship
      properties:
        PolicyNumber:
          type: string
          example: "5002"
        Product:
          type: integer
          example: 101
        PolicyStatus:
          type: integer
          example: 1
        relationship:
          $ref: '#/components/schemas/DataServiceRelationship'

    DataServiceRelationship:
      type: object
      required:
        - RelationshipNumber
        - individual
      properties:
        RelationshipNumber:
          type: string
          example: "1001"
        individual:
          $ref: '#/components/schemas/DataServiceIndividual'

    DataServiceIndividual:
      type: object
      required:
        - IndividualNumber
        - FirstName
        - LastName
        - Internal
      properties:
        IndividualNumber:
          type: integer
          example: 1005
        FirstName:
          type: string
          example: John
        LastName:
          type: string
          example: Doe
        Internal:
          type: boolean
          example: false

    DataServiceSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        processedCount:
          type: integer
          example: 4
        message:
          type: string
          example: Billed items processed successfully

paths:
  # Admin Service Endpoints
  /api/admin/truncateDBData:
    post:
      tags:
        - Admin Service
      summary: Logically truncate schema data using Prisma deleteMany
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TruncateDBRequest"
      responses:
        "200":
          description: Truncation completed
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/admin/listTables:
    post:
      tags:
        - Admin Service
      summary: List S_* prefixed tables for given schema(s)
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListTablesRequest"
      responses:
        "200":
          description: Successfully listed tables
        "500":
          description: Server error

  /api/admin/fetchTableData:
    post:
      tags:
        - Admin Service
      summary: Fetch table data or metadata
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FetchTableDataRequest"
      responses:
        "200":
          description: Table data returned
        "500":
          description: Server error

    get:
      tags:
        - Admin Service
      summary: Fetch table data via GET
      security:
        - bearerAuth: []
      parameters:
        - name: tableNames
          in: query
          schema:
            type: string
        - name: tableName
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Data returned
        "500":
          description: Server error

  /api/admin/addRow:
    post:
      tags:
        - Admin Service
      summary: Insert a new row into a table
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddRowRequest"
      responses:
        "200":
          description: Row inserted
        "500":
          description: Insert failed

  /api/admin/updateRow:
    post:
      tags:
        - Admin Service
      summary: Update a row in a table
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRowRequest"
      responses:
        "200":
          description: Row updated
        "500":
          description: Update failed

  /api/admin/deleteRow:
    post:
      tags:
        - Admin Service
      summary: Delete a row
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteRowRequest"
      responses:
        "200":
          description: Row deleted
        "500":
          description: Server error

  /api/admin/sampleData:
    post:
      tags:
        - Admin Service
      summary: Import static sample Excel file
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SampleDataRequest"
      responses:
        "200":
          description: Sample data imported
        "500":
          description: Import failed

  /api/admin/import-data-from-connectors:
    post:
      tags:
        - Admin Service
      summary: Import Excel data using connector pipeline
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportConnectorRequest"
      responses:
        "200":
          description: Import completed
        "500":
          description: Error processing import

  # Gateway/Common Service Endpoints
  /api/common/getChatbotContent:
    post:
      summary: Get chatbot response content
      description: Processes user input and returns chatbot response with options
      tags: [Application Service]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatbotRequest"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatbotResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/common/saveChatConversation:
    post:
      summary: Save chat conversation
      description: Saves the complete chat conversation with user details
      tags: [Application Service]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatConversation"
      responses:
        "200":
          description: Chat saved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  interactionId:
                    type: string
                    example: "11"
                  message:
                    type: string
                    example: Chat saved successfully.

  /api/common/savefeedback:
    post:
      summary: Save user feedback
      description: Saves user feedback and rating, sends notification email
      tags: [Application Service]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedbackRequest"
      responses:
        "200":
          description: Feedback saved successfully

  /api/common/getUserAvatar:
    post:
      summary: Get user avatar URL
      description: Retrieves the avatar URL for the authenticated user
      tags: [Application Service]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Avatar URL retrieved successfully

  /api/common/products:
    get:
      summary: Get all products
      description: Retrieves list of all available products
      tags: [Application Service]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Products retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"

  /api/common/capabilityRole:
    get:
      summary: Get all capability roles
      description: Retrieves list of all capability roles
      tags: [Application Service]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Capability roles retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  capabilityRoles:
                    type: array
                    items:
                      $ref: "#/components/schemas/CapabilityRole"

  # Audit Service Endpoints
  /api/audit/getAuditCategory:
    get:
      summary: Get Data Audit categories
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of audit categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  options:
                    type: array
                    items:
                      $ref: "#/components/schemas/AuditCategoryOption"

  /api/audit/getSchemaCategory:
    get:
      summary: Get Schema Audit categories
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of schema audit categories

  /api/audit/getUserList:
    get:
      summary: Get users for audit filtering
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  options:
                    type: array
                    items:
                      $ref: "#/components/schemas/AuditFilterOption"

  /api/audit/getDataAuditTablenames:
    get:
      summary: Get table names for Data Audit
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Distinct table names

  /api/audit/getDataAuditFiledNames:
    get:
      summary: Get field names for Data Audit
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Distinct field names

  /api/audit/getShemaAuditTablenames:
    get:
      summary: Get table names for Schema Audit
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Distinct schema table names

  /api/audit/getAuditData:
    get:
      summary: Get Data Audit records
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: Data Audit records

  /api/audit/getSchemaAuditData:
    get:
      summary: Get Schema Audit records
      tags:
        - Audit Service
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: Schema Audit records

  # Billing Service Endpoints
  /api/billingnew/list:
    get:
      tags:
        - Billing Service
      summary: Get all or filtered billed items
      description: >
        Returns all billed items if no query parameter is provided.
        Optionally, filter by PolicyNumber.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: PolicyNumber
          schema:
            type: string
            example: COPA-100001
          description: Optional policy number to filter billed items
      responses:
        '200':
          description: List of billed items (filtered or all)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  total:
                    type: integer
                    example: 84
                  page:
                    type: integer
                    example: 1
                  limit:
                    type: integer
                    example: 10
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BilledItem'
        '401':
          description: Unauthorized
        '404':
          description: No billed items found
        '500':
          description: Internal server error

  /api/billingnew/cash-details/{id}:
    get:
      tags:
        - Billing Service
      summary: Get cash allocation details by billed item ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            example: 68
          description: Billed item ID to fetch cash details for
      responses:
        '200':
          description: Cash allocation details for the billed item
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CashAllocation'
        '404':
          description: No cash details found for given billed item ID
        '500':
          description: Internal server error

  # Claims Service Endpoints
  /api/claims/getClaims:
    get:
      summary: Get all claims
      description: Returns all claims when no filter is provided
      tags:
        - Claims Service
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Claims retrieved successfully
        "404":
          description: No claims found
        "500":
          description: Internal server error

  /api/claims/getClaimById/{id}:
    get:
      summary: Get a claim by claim number
      description: Returns a single claim with full exposures and nested details
      tags:
        - Claims Service
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Claim number (e.g. PEAU-CL-10001)
      responses:
        "200":
          description: Claim retrieved successfully
        "404":
          description: Claim not found
        "500":
          description: Internal server error

  /api/claims/search:
    get:
      summary: Search claims by filters
      description: Search across claims by optional filters
      tags:
        - Claims Service
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            type: string
          description: Claim status name
        - in: query
          name: startDate
          schema:
            type: string
            format: date-time
          description: DateOfLoss >= startDate
        - in: query
          name: endDate
          schema:
            type: string
            format: date-time
          description: DateOfLoss <= endDate
        - in: query
          name: claimNumber
          schema:
            type: string
          description: Exact claim number filter
      responses:
        "200":
          description: Search results
        "500":
          description: Internal server error

  /api/claims/getExposures/{claimId}:
    get:
      summary: Get exposures for a given claimId
      description: Returns list of exposure details for the claim
      tags:
        - Claims Service
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: claimId
          required: true
          schema:
            type: string
          description: Claim Id
      responses:
        "200":
          description: Exposures retrieved successfully
        "404":
          description: No exposures found
        "500":
          description: Internal server error

  # Command Line Service Endpoints
  /api/commandline/checkdataquality:
    post:
      tags:
        - Command Line Service
      summary: Trigger data-quality pre-checks and notify the user by email
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckDataQualityRequest'
      responses:
        '200':
          description: Validation triggered and email sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Validation triggered and email sent.
        '400':
          description: Bad request (missing or invalid input)
        '500':
          description: Internal server error

  /api/commandline/changedatacapture:
    post:
      tags:
        - Command Line Service
      summary: Import data capture (Excel) and compute/apply schema & data changes
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeDataCaptureRequest'
      responses:
        '200':
          description: Data import completed
        '400':
          description: Bad request
        '500':
          description: Internal server error

  # Document Service Endpoints
  /document/search:
    get:
      summary: Search uploaded documents
      description: Search by name, type, status, relationshipId with pagination
      tags:
        - Document Service
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: name
          schema:
            type: string
        - in: query
          name: type
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: relationshipId
          schema:
            type: integer
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Document list
        "500":
          description: Server error

  /document/upload:
    post:
      summary: Upload a document
      description: Uploads a file along with metadata using multipart/form-data
      tags:
        - Document Service
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - documentName
                - documentType
              properties:
                file:
                  type: string
                  format: binary
                documentName:
                  type: string
                documentType:
                  type: string
                relationshipId:
                  type: integer
                  description: Optional. Defaults to logged-in user's ID.
      responses:
        "201":
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResponse"
        "400":
          description: Missing file or required fields
        "500":
          description: Server error

  /document/{id}/download:
    get:
      summary: Get downloadable file details
      description: Returns URL + metadata for the file
      tags:
        - Document Service
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Download info
        "404":
          description: Document not found
        "500":
          description: Server error

  /document/{id}/parse:
    post:
      summary: Parse a PDF document
      description: Extracts text from PDF and stores it
      tags:
        - Document Service
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Parse success
        "404":
          description: Document not found
        "500":
          description: Server error

  /document/{id}/metadata:
    get:
      summary: View metadata + parsed content
      description: Requires the document belongs to the logged-in user
      tags:
        - Document Service
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Parsed document content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentContent"
        "404":
          description: Not found or no access
        "500":
          description: Server error

  /document/relationship/{relationshipId}:
    get:
      summary: Get documents by relationship ID
      tags:
        - Document Service
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: relationshipId
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: List of documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DocumentMetadata"
        "500":
          description: Server error

  /document/download-pdf:
    post:
      summary: Export data into a PDF file
      description: Accepts columns + data to generate a PDF table
      tags:
        - Document Service
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - columns
                - data
              properties:
                columns:
                  type: array
                  items:
                    type: string
                data:
                  type: array
                  items:
                    type: array
                    description: Row values (strings/numbers/dates)
      responses:
        "200":
          description: PDF file stream
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          description: Missing columns or data
        "500":
          description: Server error

  # External Integration Service Endpoints
  /api/integration/runIntegrationCall:
    post:
      summary: Initiate an integration call (creates a job)
      description: Accepts apiUrl, callbackUrl, maxRetries and payload
      tags:
        - Integration Service
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunIntegrationRequest"
      responses:
        "200":
          description: Integration job created
        "400":
          description: Bad request
        "500":
          description: Internal server error

  /api/integration/integrationAddress:
    post:
      summary: Receive integration address verification callback
      description: Endpoint for submitting verification results
      tags:
        - Integration Service
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - integrationId
                - result
              properties:
                integrationId:
                  type: string
                  description: Integration record Id
                  example: "123"
                result:
                  type: array
                  description: Array of address verification results
                  items:
                    type: object
      responses:
        "200":
          description: Address verified and saved successfully
        "400":
          description: Bad request
        "500":
          description: Internal server error

  /api/integration/list:
    get:
      summary: Get paginated list of integration records
      description: Returns integration records ordered by CreatedAt desc
      tags:
        - Integration Service
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
          description: Page size
      responses:
        "200":
          description: Integration list
        "500":
          description: Internal server error

  # Individual Service Endpoints
  /api/interaction/list:
    get:
      tags:
        - Individual Service
      summary: Get all or filtered interactions
      description: Returns all interactions when no query parameters are provided
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: individualId
          required: false
          schema:
            type: string
            example: "1000000025"
          description: Unique identifier of the individual to filter interactions
      responses:
        '200':
          description: Successfully fetched interactions
          content:
            application/json:
              example:
                data:
                  - Id: "1"
                    Date: "2025-06-12T18:30:00.000Z"
                    Sensitive: false
                    DistributionChannel: "13"
                    ContextTableName: null
                    ContextUniqueId: "3"
                    Content: "Testing"
                    FromIndividualPersona: "Christine Ward"
                    ToIndividualPersona: null
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /api/favourite:
    post:
      tags:
        - Individual Service
      summary: Add a page to user favorites
      description: Marks a specific page as a favorite for the authenticated user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url_path:
                  type: string
                  example: "/"
                page_name:
                  type: string
                  example: "Communication Hub"
      responses:
        '200':
          description: Page marked as favorite successfully
        '500':
          description: Internal server error

    get:
      tags:
        - Individual Service
      summary: Get all or filtered favorite pages
      description: Fetches all favorite pages for the authenticated user
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: url_path
          schema:
            type: string
            example: "/"
        - in: query
          name: page_name
          schema:
            type: string
            example: "Communication Hub"
        - in: query
          name: start
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - in: query
          name: end
          schema:
            type: string
            format: date
            example: "2025-12-31"
      responses:
        '200':
          description: List of favorite pages
        '500':
          description: Internal server error

    delete:
      tags:
        - Individual Service
      summary: Remove a page from favorites
      description: Removes a specific page from the user's favorites
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url_path:
                  type: string
                  example: "/"
      responses:
        '200':
          description: Successfully removed from favorites
        '500':
          description: Internal server error

  /api/favourite/check:
    get:
      tags:
        - Individual Service
      summary: Check if a page is marked as favorite
      description: Checks whether the specified page is marked as a favorite
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: url_path
          required: true
          schema:
            type: string
            example: "/"
        - in: query
          name: page_name
          required: true
          schema:
            type: string
            example: "Communication Hub"
      responses:
        '200':
          description: Favorite check status
        '500':
          description: Internal server error

  /api/history:
    post:
      tags:
        - Individual Service
      summary: Add a page visit to history
      description: Inserts a new record into the user's page visit history
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pageName:
                  type: string
                  example: "Communication Hub"
                urlPath:
                  type: string
                  example: "/"
      responses:
        '200':
          description: History record inserted successfully
        '500':
          description: Internal server error

    get:
      tags:
        - Individual Service
      summary: Get page visit history
      description: Fetches user's page history records with pagination, search, and date filtering
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
        - in: query
          name: pageName
          schema:
            type: string
            example: "Dashboard"
        - in: query
          name: urlPath
          schema:
            type: string
            example: "/"
        - in: query
          name: start
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - in: query
          name: end
          schema:
            type: string
            format: date
            example: "2025-12-31"
      responses:
        '200':
          description: List of visited pages
        '500':
          description: Internal server error
  
  /api/individual/getDetails:
    get:
      tags:
        - Individual Service
      summary: Get individual details
      description: Returns complete details for the logged-in individual
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully fetched individual details
        '404':
          description: Individual not found
        '500':
          description: Internal server error

  /api/individual/getProfile:
    get:
      tags:
        - Individual Service
      summary: Get profile of logged-in user
      description: Fetches minimal profile details for the logged-in individual
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully fetched profile
        '404':
          description: Individual not found
        '500':
          description: Internal server error

  /api/individual/update-bitbucket-credentials:
    post:
      tags:
        - Individual Service
      summary: Update Bitbucket credentials for logged-in user
      description: Validates and updates Bitbucket username and password
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                BitbucketUserName:
                  type: string
                  example: "tinah"
                BitbucketPassword:
                  type: string
                  example: "MySecurePass123!"
      responses:
        '200':
          description: Credentials updated successfully
        '400':
          description: Invalid credentials
        '500':
          description: Internal server error

  /api/individual/list:
    get:
      tags:
        - Individual Service
      summary: Get list of individuals
      description: Returns a list of all individuals in the system
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of individuals
        '500':
          description: Internal server error

  /api/individual/getAllUsersDetails:
    get:
      tags:
        - Individual Service
      summary: Get all user details with pagination
      description: Returns detailed information for all users with pagination
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            example: 1
        - in: query
          name: pageSize
          schema:
            type: integer
            example: 20
      responses:
        '200':
          description: Successfully fetched user details
        '500':
          description: Internal server error

  /api/individual/createInsurgenceProfile:
    post:
      tags:
        - Individual Service
      summary: Create new InsurgenceProfile
      description: Creates a new InsurgenceProfile record in the system
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                insurgenceTypeId:
                  type: integer
                  example: 1
                createdate:
                  type: string
                  format: date-time
                  example: "2025-11-12T00:00:00Z"
                companyId:
                  type: integer
                  example: 123
                insurgenceProfileNumber:
                  type: string
                  example: "IP-001"
                moduleSubscriptionTypeId:
                  type: integer
                  example: 4
      responses:
        '201':
          description: InsurgenceProfile created successfully
        '400':
          description: Missing required fields
        '500':
          description: Internal server error

  /api/individual/deleteInsurgenceProfile:
    post:
      tags:
        - Individual Service
      summary: Delete InsurgenceProfile
      description: Deletes an InsurgenceProfile based on its ID or profile number
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 42
                insurgenceProfileNumber:
                  type: string
                  example: "IP-001"
      responses:
        '200':
          description: InsurgenceProfile deleted successfully
        '404':
          description: InsurgenceProfile not found
        '500':
          description: Internal server error

  /createSuperuser:
    post:
      tags:
        - Individual Service
      summary: Create or update superuser
      description: Creates or updates the default system superuser (no authentication required)
      requestBody:
        required: false
      responses:
        "200":
          description: Superuser created or updated successfully
        "500":
          description: Error creating or updating superuser

  # Policy Service Endpoints
  /api/policy/getPolicies:
    get:
      tags:
        - Policy Service
      summary: Get all or filtered policies
      description: Returns all policies when no query parameters are provided
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: relationshipNumber
          required: false
          schema:
            type: string
            example: 1000000025
          description: Filter policies by RelationshipNumber
      responses:
        '200':
          description: Successfully fetched list or details of policies
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  total:
                    type: integer
                  page:
                    type: integer
                  limit:
                    type: integer
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'

  # Policy Transaction Service Endpoints
  /api/policytransaction/getPolicyTransactions:
    get:
      tags:
        - Policy Transaction Service
      summary: Get policy transactions and related sections
      description: Provide comma-separated policyNumbers query
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: policyNumbers
          required: true
          schema:
            type: string
            example: PEAU-100001,COPA-100001
          description: Comma-separated list of policy numbers
      responses:
        '200':
          description: Policy transactions and related data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  policyTerms:
                    type: array
                    items:
                      $ref: '#/components/schemas/PolicyTerm'
                  policyTransaction:
                    type: array
                    items:
                      $ref: '#/components/schemas/PolicyTransaction'
        '400':
          description: Bad request (missing policyNumbers)
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  # Reinsurance Service Endpoints
  /api/reinsurance/getRisk:
    get:
      tags:
        - Reinsurance Service
      summary: Fetch reinsurance/treaty data for policies
      description: Returns reinsurance information for a given policy number
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: policyNumber
          required: false
          schema:
            type: string
            example: COPA-100001
          description: Optional policy number to restrict the response to a single policy
      responses:
        '200':
          description: Reinsurance data returned successfully
        '400':
          description: Bad request (invalid parameters)
        '401':
          description: Unauthorized
        '404':
          description: No policies found
        '500':
          description: Internal server error

  # Relationship Service Endpoints
  /api/relationship/getRelationships:
    get:
      tags:
        - Relationship Service
      summary: Get all or specific relationship details
      description: Returns all relationships when no query parameters are provided
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: relationshipNumber
          required: false
          schema:
            type: string
            example: "1000000025"
          description: Optional relationship number to filter the result
      responses:
        '200':
          description: Successfully fetched relationship(s)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    relationship:
                      $ref: '#/components/schemas/Relationship'
        '401':
          description: Unauthorized
        '404':
          description: Relationship not found
        '500':
          description: Internal server error

  # Data Service Endpoints
  /api/billeditem:
    post:
      tags:
        - Data Service
      summary: Create billed items
      description: |
        Accepts a list of billed items for ingestion. Each billed item must include either a relationshipCharge or a policyTransactionCost, but not both (enforced in service logic).
      operationId: createBilledItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/DataServiceBilledItemRequest'
      responses:
        '200':
          description: Billed items processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataServiceSuccessResponse'
        '400':
          description: Invalid request payload
        '500':
          description: Internal server error

tags:
  - name: Admin Service
    description: Database maintenance, table browsing, CRUD operations for S_* tables, Excel data imports
  - name: Application Service  
    description: Chatbot, feedback, user avatar, products, capability roles, common application services
  - name: Audit Service
    description: Data audit (business-level changes) and schema audit (system-level structural changes)
  - name: Billing Service
    description: Billing information, billed items, cash allocation details for policies and relationships
  - name: Claims Service
    description: Claims management with exposures, coverages, costs, and related claim data
  - name: Command Line Service
    description: Data quality checks and data capture/schema change imports via command line utilities
  - name: Document Service
    description: Document upload, search, metadata management, PDF parsing and export functionality
  - name: Integration Service
    description: External integration jobs, address verification callbacks, integration record management
  - name: Individual Service
    description: Individual interactions, page favorites, page history, individual profile management
  - name: Policy Service
    description: Policy management, policy lists and filtered policy information retrieval
  - name: Policy Transaction Service
    description: Policy terms, transactions, costs, claims, risk and billing data for policies
  - name: Reinsurance Service
    description: Reinsurance and treaty-related data for policies including risk transfer programs
  - name: Relationship Service
    description: Relationship profile details, individuals, companies, consents, reputation management
  - name: Data Service
    description: Data ingestion for billed items containing relationship charges or policy transaction costs
