Vim
Vim Data Source

Ingestion surface for pushing patient-specific clinical insights and gaps (Diagnosis Gaps, Risk, Quality, Social Determinants of Health) into Vim for surfacing at the point of care, via either API or file-based connections. Requires a stable unique patient ID and a stable unique identifier per insight/gap.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.0.0",
  "info": {
    "title": "Vim Data Source API Integration",
    "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": "Access Token Retrieval",
      "description": "Obtaining a Bearer service token to make API requests"
    },
    {
      "name": "Patient Identification",
      "description": "Identify the patient based on personal information"
    },
    {
      "name": "Get Patient Care Insights",
      "description": "Retrieving patient care insights such as diagnosis gaps and care insights"
    },
    {
      "name": "Patient Care Insights Feedback",
      "description": "Sending feedback about the care insights"
    }
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "operationId": "post-oauth-token",
        "tags": [
          "Access Token Retrieval"
        ],
        "summary": "Authenticate and Retrieve an Access Token",
        "description": "This endpoint authenticates clients and provides access tokens for subsequent API calls.",
        "parameters": [
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthTokenRequest"
              },
              "example": {
                "client_id": "example-client-id",
                "client_secret": "example-client-secret",
                "grant_type": "client_credentials"
              }
            }
          },
          "description": "Authentication request body containing client credentials"
        },
        "security": [
        ],
        "responses": {
          "200": {
            "description": "Authentication successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/patient/identify": {
      "post": {
        "operationId": "post-patient-identify",
        "tags": [
          "Patient Identification"
        ],
        "summary": "Identify an Eligible Patient",
        "description": "Identifies a patient that is eligible to the service by their personal details information.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatientDetails"
              },
              "example": {
                "first_name": "John",
                "last_name": "Doe",
                "dob": "1990-07-19",
                "member_id": "123445455",
                "ehr_id": "a1b2c3d4",
                "zip_code": "90210",
                "insurer": "United Health Care",
                "state": "FL"
              }
            }
          },
          "description": "Patient identification details"
        },
        "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 identified the patient",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdentifyPatientResponse"
                }
              }
            }
          },
          "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 criteria was found in the system"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/insights/feedback": {
      "post": {
        "operationId": "post-insights-feedback",
        "tags": [
          "Patient Care Insights Feedback"
        ],
        "summary": "Sending feedback about the insight",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/DiagnosisGapFeedback" },
                  { "$ref": "#/components/schemas/InsightFeedback" }
                ],
                "discriminator": {
                  "propertyName": "data_type",
                  "mapping": {
                    "diagnosis_gap": "#/components/schemas/DiagnosisGapFeedback",
                    "insight": "#/components/schemas/InsightFeedback"
                  }
                }
              },
              "examples": {
                "diagnosisGap": {
                  "summary": "Diagnosis Gap Feedback",
                  "x-collapsed": true,
                  "value": {
                    "data_type": "diagnosis_gap",
                    "patient_id": "d4fon0UkvtdfNBW1JfD5",
                    "id": "Ae3uywUB0YwdwxxdA4M5",
                    "action": {
                      "date": "2024-01-20",
                      "type": "AGREE",
                      "reason": "Confirmed diagnosis",
                      "notes": "Patient records show this diagnosis"
                    },
                    "organization": {
                      "name": "Test Medical Group",
                      "vim_organization_key": "test-medical-key-12345"
                    },
                    "system": "HCC",
                    "type": "KNOWN",
                    "status": "OPEN",
                    "medical_codes": [
                      {
                        "system": "ICD",
                        "code": "F32.9",
                        "description": "Major depressive disorder, single episode, unspecified"
                      }
                    ]
                  }
                },
                "insight": {
                  "summary": "Insight Feedback",
                  "x-collapsed": true,
                  "value": {
                    "data_type": "insight",
                    "patient_id": "d4fon0UkvtdfNBW1JfD5",
                    "id": "Bf4vywUB0YwdwxxdB5N6",
                    "action": {
                      "date": "2024-01-20",
                      "type": "AGREE",
                      "reason": "Procedure completed",
                      "notes": "Screening was completed"
                    },
                    "organization": {
                      "name": "Test Medical Group",
                      "vim_organization_key": "test-medical-key-12345"
                    },
                    "title": "Blood Pressure Check",
                    "code": "CBP",
                    "category": "QUALITY",
                    "description": "Annual blood pressure check",
                    "type": "HEDIS",
                    "status": "OPEN",
                    "medical_codes": [
                      {
                        "system": "CPT",
                        "code": "3074F",
                        "description": "Most recent systolic BP less than 130 mm Hg"
                      }
                    ]
                  }
                }
              }
            }
          },
          "description": "Feedback request details - schema varies based on data_type"
        },
        "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": "Feedback updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedbackResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Success Response",
                    "x-collapsed": true,
                    "value": {
                      "update_status": "SUCCESS"
                    }
                  }
                }
              }
            }
          },
          "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": {
      "AuthTokenRequest": {
        "type": "object",
        "required": [
          "client_id",
          "client_secret",
          "grant_type"
        ],
        "description": "Authentication request",
        "properties": {
          "client_id": {
            "type": "string",
            "description": "Unique defined ID for the client"
          },
          "client_secret": {
            "type": "string",
            "description": "Provided client secret information"
          },
          "grant_type": {
            "type": "string",
            "description": "OAuth 2.0 grant type, must be set to client_credentials",
            "default": "client_credentials"
          }
        },
        "example": {
          "client_id": "example-client-id",
          "client_secret": "example-client-secret",
          "grant_type": "client_credentials"
        }
      },
      "AuthTokenResponse": {
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "expires_in"
        ],
        "properties": {
          "access_token": {
            "type": "string",
            "description": "Bearer token for authenticating subsequent requests"
          },
          "token_type": {
            "type": "string",
            "default": "Bearer",
            "description": "Type of the token issued"
          },
          "expires_in": {
            "type": "integer",
            "default": 3600,
            "description": "Token expiry details in seconds"
          }
        }
      },
      "PatientDetails": {
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "dob"
        ],
        "description": "Patient identification details",
        "properties": {
          "first_name": {
            "type": "string",
            "description": "Patient's first name"
          },
          "last_name": {
            "type": "string",
            "description": "Patient's last name"
          },
          "dob": {
            "type": "string",
            "format": "date",
            "description": "Patient's date of birth in yyyy-mm-dd format"
          },
          "member_id": {
            "type": "string",
            "description": "[CONDITIONAL] Patient's member ID - Requirements based on the customer's patient matching mechanism"
          },
          "ehr_id": {
            "type": "string",
            "description": "[CONDITIONAL] Patient's EHR ID - Requirements based on the customer's patient matching mechanism"
          },
          "zip_code": {
            "type": "string",
            "description": "[CONDITIONAL] Patient's ZIP code - Requirements based on the customer's patient matching mechanism"
          },
          "insurer": {
            "type": "string",
            "description": "Patient's insurance provider"
          },
          "state": {
            "type": "string",
            "description": "Patient's state of residence"
          }
        },
        "example": {
          "first_name": "John",
          "last_name": "Doe",
          "dob": "1990-07-19",
          "member_id": "123445455",
          "ehr_id": "a1b2c3d4",
          "zip_code": "90210",
          "insurer": "United Health Care",
          "state": "FL"
        }
      },
      "IdentifyPatientResponse": {
        "type": "object",
        "required": [
          "is_eligible",
          "patient_id"
        ],
        "description": "Response from patient identification",
        "properties": {
          "is_eligible": {
            "type": "boolean",
            "description": "Indicates if the patient is eligible for the service"
          },
          "patient_id": {
            "type": "string",
            "description": "Unique identifier for the patient"
          }
        },
        "example": {
          "is_eligible": true,
          "patient_id": "d4fon0UkvtdfNBW1JfD5"
        }
      },
      "Patient": {
        "type": "object",
        "required": [
          "patient_id"
        ],
        "description": "Patient identifier",
        "properties": {
          "patient_id": {
            "type": "string",
            "description": "Unique patient identifier"
          }
        },
        "example": {
          "patient_id": "d4fon0UkvtdfNBW1JfD5"
        }
      },
      "GapDetails": {
        "type": "object",
        "required": [
          "gap_id",
          "gap_status"
        ],
        "properties": {
          "gap_id": {
            "type": "string",
            "description": "A unique identifier per gap and per patient"
          },
          "gap_status": {
            "type": "string",
            "description": "Gap Status. Only open gaps are displayed in the UI.",
            "enum": ["Open", "Closed"]
          },
          "last_recorded_dos": {
            "type": "string",
            "format": "date",
            "description": "Most recent date of a relevant service",
            "example": "1990-07-19"
          },
          "last_recorded_npi": {
            "type": "integer",
            "description": "NPI of the most recent coding provider",
            "example": 123456789
          },
          "last_recorded_provider_name": {
            "type": "string",
            "description": "Name of the most recent coding provider",
            "example": "John Doe"
          },
          "source": {
            "type": "string",
            "description": "Gap source",
            "example": "2021 claims"
          },
          "notes": {
            "type": "string",
            "description": "Additional information related to the gap",
            "example": "It's recommended to use category II codes claims for HEDIS"
          }
        }
      },
      "Insights": {
        "type": "array",
        "items": {
          "allOf": [
            { "$ref": "#/components/schemas/GapDetails" },
            {
              "type": "object",
              "required": ["gapCode", "gapDisplayName"],
              "properties": {
                "gapCode": {
                  "type": "string",
                  "description": "Gap code"
                },
                "gapDisplayName": {
                  "type": "string",
                  "description": "Gap description"
                },
                "actionRequired": {
                  "type": "string",
                  "description": "Action that should be taken by the Health Care Provider",
                  "example": "Perform & code B/P check. Controlled is BELOW 140/90. Take REPEAT if necessary."
                },
                "priorValues": {
                  "type": "string",
                  "description": "Prior values of clinical tests or procedure results",
                  "example": "Systolic / Diastolic: [X/Y]"
                },
                "collectionDate": {
                  "type": "string",
                  "format": "date",
                  "description": "Date in which the prior values were documented",
                  "example": "1990-07-19"
                },
                "cptCode": {
                  "type": "string",
                  "description": "Recommended CPT II code associated with the gap",
                  "example": "3074F"
                },
                "cptDescription": {
                  "type": "string",
                  "description": "Recommended CPT II description associated with the gap",
                  "example": "Most recent systolic BP less than 130 mm Hg"
                }
              }
            }
          ]
        }
      },
      "DiagnosisGaps": {
        "type": "array",
        "items": {
          "allOf": [
            { "$ref": "#/components/schemas/GapDetails" },
            {
              "type": "object",
              "required": ["hccCode", "icdCode", "hccDescription", "icdDescription", "hccModel", "gapType"],
              "properties": {
                "hccCode": {
                  "type": "integer",
                  "description": "Gap HCC code"
  

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vim/refs/heads/main/openapi/vim-data-source-openapi-original.json
Vim Data Source

Documentation

Specifications

Other Resources

OpenAPI Specification
