openapi: 3.2.0
info:
  title: Vim Data Source API Integration Get Patient Care Insights API
  description: API for managing patient insights
  version: ''
servers:
- url: https://{environment}-{customerName}.com
  description: Customer API server URL
  variables:
    environment:
      default: api
      description: Environment (e.g., api, staging, dev)
    customerName:
      default: example
      description: Customer name
security:
- bearerAuth: []
tags:
- name: Get Patient Care Insights
  description: Retrieving patient care insights such as diagnosis gaps and care insights
paths:
  /insights/fetch:
    post:
      operationId: post-insights-fetch
      tags:
      - Get Patient Care Insights
      summary: 'Fetching Patient Care Insights '
      description: Retrieving patient care insights for the patient identified in the previous step
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Patient'
            example:
              patient_id: d4fon0UkvtdfNBW1JfD5
        description: Patient identifier
      security:
      - bearerAuth: []
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Authentication Bearer token to allow request to be processed
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
          default: application/json
        description: Media type of the body of the request
      responses:
        '200':
          description: Successfully fetched insights for the patient
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/DiagnosisGap'
                  - $ref: '#/components/schemas/Insight'
                  discriminator:
                    propertyName: data_type
                    mapping:
                      diagnosis_gap: '#/components/schemas/DiagnosisGap'
                      insight: '#/components/schemas/Insight'
              examples:
                withGaps:
                  summary: Response with gaps
                  x-collapsed: true
                  value:
                  - data_type: diagnosis_gap
                    id: gap1
                    system: ICD
                    hcc_model_version: CMS-HCC V28
                    medical_codes:
                    - system: ICD
                      code: E11.9
                      description: Type 2 diabetes mellitus without complications
                    type: KNOWN
                    status: OPEN
                    source: 2023 claims
                    raf_score: 0.368
                    last_recorded:
                      date: '2023-09-15'
                      provider:
                        npi: '1234567890'
                        name: Jane Smith
                    notes: Example diagnosis gap
                    custom_fields:
                    - title: Risk Priority
                      level: gap
                      type: string
                      value: High
                  - data_type: diagnosis_gap
                    id: gap2
                    system: HCC
                    hcc_model_version: CMS-HCC V28
                    hcc_code: 19
                    hcc_description: Diabetes without Complication
                    medical_codes:
                    - system: ICD
                      code: E11.9
                      description: Type 2 diabetes mellitus without complications
                    type: KNOWN
                    status: OPEN
                    source: 2023 claims
                    raf_score: 0.104
                    last_recorded:
                      date: '2023-10-20'
                      provider:
                        npi: 0987654321
                        name: John Doe
                    notes: Example HCC diagnosis gap
                  - data_type: insight
                    id: insight1
                    code: CBP
                    title: Blood Pressure Check
                    category: QUALITY
                    description: Annual blood pressure check
                    type: HEDIS
                    medical_codes:
                    - system: CPT
                      code: 3074F
                      description: Most recent systolic BP less than 130 mm Hg
                    status: OPEN
                    source: Quality measure
                    last_recorded:
                      date: '2023-09-15'
                      provider:
                        npi: '1234567890'
                        name: Jane Smith
                    notes: Annual blood pressure check required
                    custom_fields:
                    - title: Patient Risk Score
                      level: patient
                      type: decimal
                      value: 3.2
                    document:
                      doc_file_path: gs://medical-records/patient123_bp_history.pdf
                      doc_coordinates:
                      - 1
                      - 8.5
                      - 11
                      - 2.1
                      - 3.5
                      - 6.2
                      - 3.5
                      - 6.2
                      - 4.8
                      - 2.1
                      - 4.8
                noGaps:
                  summary: Response with no gaps
                  x-collapsed: true
                  value: []
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: INVALID_INPUT
                reason: The request is missing required parameters or contained invalid values
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: UNAUTHORIZED
                reason: The provided authentication credentials are invalid
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: FORBIDDEN
                reason: You do not have permission to access this resource
        '404':
          description: Patient/path not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: PATIENT_NOT_FOUND
                reason: No patient matching the provided identifier was found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: SERVER_ERROR
                reason: An unexpected error occurred while processing the request
components:
  schemas:
    Patient:
      type: object
      required:
      - patient_id
      description: Patient identifier
      properties:
        patient_id:
          type: string
          description: Unique patient identifier
      example:
        patient_id: d4fon0UkvtdfNBW1JfD5
    ErrorResponse:
      type: object
      required:
      - code
      - reason
      properties:
        code:
          type: string
          description: Error code indicating the type of error
        reason:
          type: string
          description: Detailed explanation of the error
      example:
        code: SERVER_ERROR
        reason: An unexpected error occurred while processing the request
    Insight:
      type: object
      required:
      - data_type
      - id
      - title
      - category
      properties:
        data_type:
          type: string
          enum:
          - insight
          description: Type of the data - used as a discriminator
        id:
          type: string
          description: A unique identifier per insight and per patient
        title:
          type: string
          description: The name of the insight as it will be displayed in the application
        code:
          type: string
          description: The insight code to present in the application next to the title
        category:
          type: string
          description: The category of the insight (RISK/ QUALITY/ RX/ SDOH/ CCM/ UTILIZATION/ ADT/ CLINICAL INSIGHTS)
          enum:
          - RISK
          - QUALITY
          - RX
          - SDOH
          - CCM
          - UTILIZATION
          - ADT
          - CLINICAL INSIGHTS
        description:
          type: string
          description: Free-text explanation about the insight
        type:
          type: string
          description: The type or program affiliation (e.g., HEDIS, ACO, STAR)
        medical_codes:
          type: array
          items:
            type: object
            required:
            - system
            - code
            - description
            properties:
              system:
                type: string
                enum:
                - CPT
                - ICD
                description: The system of the medical code (CPT/ ICD)
              code:
                type: string
                description: The medical code
              description:
                type: string
                description: Description corresponding to the medical code
          description: Array of medical codes associated with the insight - each object contains a medical code, its system, and description.
        status:
          type: string
          description: The status of the insight. An option to filter closed insights
          enum:
          - OPEN
          - CLOSED
        source:
          type: string
          description: The source of the insight
        last_recorded:
          type: object
          properties:
            date:
              type: string
              format: date
              description: Most recent date of a relevant service in yyyy-mm-dd format
            provider:
              type: object
              properties:
                npi:
                  type: string
                  description: NPI of the most recent provider
                name:
                  type: string
                  description: Name of the most recent provider
          description: Information about when and by whom the insight was last recorded
        notes:
          type: string
          description: Additional information related to the insight
        custom_fields:
          type: array
          description: Additional fields defined by the customer for enhanced context at patient, gap, or insight level
          items:
            type: object
            required:
            - title
            - level
            - type
            - value
            properties:
              title:
                type: string
                description: Title for UI display
              level:
                type: string
                enum:
                - patient
                - gap
                - insight
                description: 'Determines where the field appears: patient details, gap card, or insight card'
              type:
                type: string
                enum:
                - string
                - integer
                - decimal
                - date
                - cost
                description: 'Controls how the value is formatted in the UI: ''string'' displays as plain text; ''integer'' displays whole numbers; ''decimal'' displays numbers with decimal places; ''date'' formats as MM/DD/YYYY; ''cost'' displays numbers with $ prefix'
              value:
                description: The actual field value
          example:
          - title: SDoH Risk Score
            level: patient
            type: decimal
            value: 2.56
          - title: Priority Level
            level: gap
            type: string
            value: High
        document:
          type: object
          description: Document viewer information for displaying supporting PDF evidence directly in Care Insights
          required:
          - doc_file_path
          properties:
            doc_file_path:
              type: string
              format: uri
              description: Path to PDF document in customer's cloud storage (Google Cloud Storage or Azure)
              example: gs://clinical-docs/patient123.pdf
            doc_coordinates:
              type: array
              description: 'Optional coordinates array for highlighting specific sections: [pageIndex, pageWidth, pageHeight, sectionPoint.topLeft.x, sectionPoint.topLeft.y, sectionPoint.topRight.x, sectionPoint.topRight.y, sectionPoint.bottomRight.x, sectionPoint.bottomRight.y, sectionPoint.bottomLeft.x, sectionPoint.bottomLeft.y]'
              items:
                type: number
              minItems: 11
              maxItems: 11
              example:
              - 5
              - 8.4444
              - 11.0833
              - 0.8356
              - 7.136
              - 7.1295
              - 7.136
              - 7.1295
              - 1.2095
              - 0.8356
              - 1.2095
    DiagnosisGap:
      type: object
      required:
      - data_type
      - id
      - system
      - hcc_model_version
      properties:
        data_type:
          type: string
          enum:
          - diagnosis_gap
          description: Type of the data used as a discriminator
        id:
          type: string
          description: A unique identifier per gap and per patient
        system:
          type: string
          description: The type of gap system
          enum:
          - ICD
          - HCC
        hcc_model_version:
          type: string
          description: Specific HCC model version
          enum:
          - CMS-HCC V28, HHS-HCC V07, RX-HCC V08, CMS-ESRD-HCC V24
        hcc_code:
          type: integer
          description: '[CONDITIONAL] Gap HCC code - Required when system is ''HCC'''
        hcc_description:
          type: string
          description: HCC description
        medical_codes:
          type: array
          items:
            type: object
            required:
            - system
            - code
            properties:
              system:
                default: ICD
                type: string
                description: The system of the medical code
              code:
                type: string
                description: The medical code
              description:
                type: string
                description: Description corresponding to the medical code
          description: '[CONDITIONAL] Array of medical code records - Each object contains a medical code, its system, and description. Required when system is ''ICD''.'
        type:
          type: string
          description: Indication for a previously known diagnosis or a suspected diagnosis
          enum:
          - KNOWN
          - SUSPECTED
        status:
          type: string
          description: Gap Status. Both open and closed gaps can be retrieved, with an option to filter closed gaps.
          enum:
          - OPEN
          - CLOSED
        source:
          type: string
          description: Gap source
        raf_value:
          type: number
          format: float
          description: Risk adjustment factor which is used for gap sorting
        last_recorded:
          type: object
          properties:
            date:
              type: string
              format: date
              description: Most recent date of a relevant service in yyyy-mm-dd format
            provider:
              type: object
              properties:
                npi:
                  type: string
                  description: NPI of the most recent coding provider
                name:
                  type: string
                  description: Name of the most recent coding provider
          description: Information about when and by whom the gap was last recorded
        notes:
          type: string
          description: Additional information related to the gap
        custom_fields:
          type: array
          description: Additional fields defined by the customer for enhanced context at patient, gap, or insight level
          items:
            type: object
            required:
            - title
            - level
            - type
            - value
            properties:
              title:
                type: string
                description: Title for UI display
              level:
                type: string
                enum:
                - patient
                - gap
                - insight
                description: 'Determines where the field appears: patient details, gap card, or insight card'
              type:
                type: string
                enum:
                - string
                - integer
                - decimal
                - date
                - cost
                description: 'Controls how the value is formatted in the UI: ''string'' displays as plain text; ''integer'' displays whole numbers; ''decimal'' displays numbers with 2 decimal places; ''date'' formats as MM/DD/YYYY; ''cost'' displays numbers with $ prefix'
              value:
                description: The actual field value
          example:
          - title: SDoH Risk Score
            level: patient
            type: decimal
            value: 2.56
          - title: Priority Level
            level: gap
            type: string
            value: High
        document:
          type: object
          description: Document viewer information for displaying supporting PDF evidence directly in Care Insights
          required:
          - doc_file_path
          properties:
            doc_file_path:
              type: string
              format: uri
              description: Path to PDF document in customer's cloud storage (Google Cloud Storage or Azure)
              example: gs://clinical-docs/patient123.pdf
            doc_coordinates:
              type: array
              description: 'Optional coordinates array for highlighting specific sections: [pageIndex, pageWidth, pageHeight, sectionPoint.topLeft.x, sectionPoint.topLeft.y, sectionPoint.topRight.x, sectionPoint.topRight.y, sectionPoint.bottomRight.x, sectionPoint.bottomRight.y, sectionPoint.bottomLeft.x, sectionPoint.bottomLeft.y]'
              items:
                type: number
              minItems: 11
              maxItems: 11
              example:
              - 5
              - 8.4444
              - 11.0833
              - 0.8356
              - 7.136
              - 7.1295
              - 7.136
              - 7.1295
              - 1.2095
              - 0.8356
              - 1.2095
  securitySchemes:
    service:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ''
          scopes: {}
      x-google-issuer: https://api.genairisk.dev.example.com/
      x-google-audiences: test3,https://sage.health/,test4
      x-google-jwks_uri: https://us-central1-clinicalnotesapp.cloudfunctions.net/getPublicCert
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token obtained from the /oauth/token endpoint
      bearerFormat: JWT