File-Based Data Integration Overview

Vim supports file-based integration for securely exchanging structured data over sFTP. This enables healthcare organizations to deliver care insights that are surfaced directly within provider EHR workflows at the point of care.

Integration begins with sharing data files formatted according to Vim’s schema. Each file is validated, filtered, and ingested into a secure, customer-specific namespace. As providers interact with insights in the application, Vim generates feedback files (passbacks) summarizing actions taken for customer to update their systems and keep future files in sync with the current state of the data.

This guide outlines the required setup, file structure, data specifications, and validation process needed to complete a successful integration.

This page will outline in detail the requirements and deliverables for the file-based integration between Vim and a data connection.

Setting Up the sFTP Connection

The first step in enabling file-based integration is establishing a secure sFTP connection between the data connection and Vim. This connection supports bi-directional file exchange: from the data connection → Vim and from Vim → data connection.

Vim will be hosting the sFTP connection supporting public key-based authentication allowing a secure method for logging in via RSA SSH. This authentication method requires:

• RSA SSH keys - The public key will be shared with Vim, while the private key will be used by the data connection to access the sFTP server
• IP whitelisting - The data connection will share the IP addresses (up to 20) that should be allowed access to the server
• Access details - Vim will provide the username and hosting URL

The sFTP server includes two folders:

• from_<data_source_name> - Files the data connection sends to Vim
• from_vim - Files Vim sends to the data connection

Preparing Your File

Before integration can begin, you’ll need to generate a data file that follows Vim’s formatting and schema requirements. This file should include the insights your organization wants to surface to providers, structured in a way that ensures accurate ingestion and display within the application.

The following sections outline supported file formats, naming conventions, configuration options, and required content structure.

File Format and Structure

Vim supports a ragne of file formats and configurations to meet various data sharing needs. The following requirements apply to all files submitted for ingestion:

1. One file per data stream - Submit one file for Diagnosis Gaps and a second for all other insight categories
   • Patient demographic data can either be included in the same file as the insights or submitted separately as a dedicated member eligibility file
2. File naming convention - Vim is expecting the following format: <customer_name>_<care_insight_data_type>_<yyyy-mm-dd>.<file_extension>
   • Accepted values for <care_insight_data_type>: diagnosis_gaps or care_insights
   • Use only lowercase letters and underscores; no spaces
   • Files not following this naming convention will not be processed
3. File formats - Files should be submitted as .csv, .txt or .xls
   • Zipped files also accepted
4. File delimiters - Either a comma or pipe (|) as the delimiter can be used
5. Encoding - Files are expected to use UTF-8 encoding
6. Delivery cadence - Files can be submitted on a daily, weekly, or monthly basis, depending on your organization’s preference

Field-Level Specifications

The following sections outline the field-level specifications for the two supported data types: Diagnosis Gaps and Care Insights. Each table defines the required fields, accepted formats, and display behavior to ensure data is correctly processed and rendered in the application.

Diagnosis Gaps File Schema

The table below outlines the required structure and accepted field-level specifications for submitting diagnosis gaps to Vim.

Field Name	Description	Required?	Type	Expected values	UI display	Example
patient_first_name	Patient's first name	Required	String	Letters only	TRUE	John
patient_last_name	Patient's last name	Required	String	Letters only	TRUE	Doe
patient_unique_id	Unique identifier assigned by the customer for the patient	Required	String	Letters + digits	FALSE	1234qwehce8fyw4fh
patient_dob	Patient's date of birth	Required	Date	YYYY-MM-DD	TRUE	1990-07-19
patient_insurance_id	Health plan member/subscriber ID	At least one of this, patient_ehr_id, or patient_zip_code is required	String		FALSE	123445455
patient_ehr_id	Unique identifier from the EHR system	Same as above	String		FALSE	a1b2c3d4
patient_zip_code	Patient's ZIP code	Same as above	String	xxxxx or xxxxx-xxxx	FALSE	90210
patient_insurer	Insurance provider name	Optional	String		FALSE	United Health Care
patient_state	U.S. state of residence	Optional	String	2-letter U.S. state code	FALSE	FL
gap_unique_id	Unique identifier per gap and patient assigned by the customer, representing a single gap card in the application	Required	String	Up to 50 characters	FALSE	fhipdusnyr98cenv485j
gap_system	DDefines whether the diagnosis gap is represented by an HCC or ICD code and determines which of the two is considered the primary gap. The selected code will be displayed prominently in the application and reported when the gap is closed	HCC, ICD	FALSE	HCC
hcc_code	HCC code to be displayed for the gap	Required if gap_system = HCC	String	Valid HCC codes per supported model	TRUE	18
hcc_description	Description of the HCC code	Optional (auto-populated if model is supported)	String		TRUE	Diabetes with chronic complications
icd_code	ICD code to be displayed for the gap	Required if gap_system = ICD	String	Valid CMS ICD codes	TRUE	E11.21
icd_description	Description of the ICD code	Optional (auto-populated if model is supported)	String		TRUE	DM with nephropathy
hcc_model_version	Version of the HCC model used	Required	Enum	CMS-HCC V24, CMS-HCC V28, HHS-HCC V07, RX-HCC V08, CMS-ESRD-HCC V24	TRUE	CMS-HCC V24
gap_type	Indicates whether the diagnosis is known or suspected	Optional	Enum	KNOWN, SUSPECTED	TRUE	KNOWN
gap_status	Current status of the gap (used for filtering)	Optional	Enum	OPEN, CLOSED	FALSE	OPEN
gap_raf_value	Risk adjustment factor for the gap	Optional	Decimal	Numeric (e.g., 2.659)	TRUE	2.659
gap_source	Source of the diagnosis gap	Optional	String		TRUE	2024 claims
last_recorded_dos	Most recent date of service tied to the diagnosis	Optional	Date	YYYY-MM-DD	TRUE	2023-07-19
last_recorded_npi	NPI of the provider for the last recorded service	Optional	Numeric	10-digit NPI	TRUE	1234567890
last_recorded_npi_name	Name of the provider for the last recorded service	Optional	String	Letters only	TRUE	John Smith
notes	Free-text field for context or comments	Optional	String		TRUE	Please address all suggested gaps
custom_field_<field_name>	Additional custom field to be displayed with the insight	Optional	String		TRUE	custom_field_<Total_RAF> 2.56

Care Insights Data Schema

The table below outlines the required structure and accepted field-level specifications for submitting additional care insightd, besides diagnosis gaps, to Vim.

Field Name	Description	Required?	Type	Expected values	UI display	Example
patient_first_name	Patient's first name	Required	String	Letters only	TRUE	John
patient_last_name	Patient's last name	Required	String	Letters only	TRUE	Doe
patient_unique_id	Unique identifier assigned by the customer for the patient	Required	String	Letters + digits	FALSE	1234qwehce8fyw4fh
patient_dob	Patient's date of birth	Required	Date	YYYY-MM-DD	TRUE	1990-07-19
patient_insurance_id	Health plan member/subscriber ID	At least one of this, patient_ehr_id, or patient_zip_code is required	String		FALSE	123445455
patient_ehr_id	Unique identifier from the EHR system	Same as above	String		FALSE	a1b2c3d4
patient_zip_code	Patient's ZIP code	Same as above	String	xxxxx or xxxxx-xxxx	FALSE	90210
patient_insurer	Insurance provider name	Optional	String		FALSE	United Health Care
patient_state	U.S. state of residence	Optional	String	2-letter U.S. state code	FALSE	FL
insight_unique_id	Unique identifier for the insight tied to the patient	Required	String	Up to 50 characters	FALSE	fhipdusnyr98cenv485j
insight_category	Category of the insight	Required	Enum	RISK, QUALITY, RX, SDOH, CARE MANAGEMENT, UTILIZATION, ADT, CLINICAL INSIGHTS	TRUE	QUALITY
insight_title	Title of the insight as displayed in the application	Required	String	Up to 100 characters	TRUE	Controlling High Blood Pressure
insight_code	Code associated with the insight	Optional	String	Recommended value from an official code set	TRUE	CBP
insight_description	Description of the insight	Optional	String		TRUE	Assesses adults 18–85 with hypertension and BP <140/90
insight_type	Insight type, program or standard (e.g., HEDIS, ACO)	Optional	String		TRUE	HEDIS
insight_medical_code_system	The medical codes related to the insight (e.g. CPT/ICD). Each code must include system, code, and description	Optional	String	CPT II / ICD-10	TRUE	CPT II / ICD-10
insight_medical_code	Medical code for the insight	Optional	String	CPT II: xxxxF, ICD-10: Xxx.xx	TRUE	CPT II: 3074F
insight_medical_code_description	Description of the medical code	Optional	String		TRUE	Systolic BP < 130 mm Hg
insight_date	Most recent date tied to the insight	Optional	Date	YYYY-MM-DD	TRUE	2024-07-19
insight_provider_npi	NPI of the provider associated with the insight	Optional	Numeric	10-digit NPI	TRUE	1234567890
insight_provider_name	Name of the provider tied to the insight	Optional	String	Letters only	TRUE	John Smith
insight_source	Origin or source of the insight	Optional	String		TRUE	2024 claims
insight_required_action	Expected next step for the provider	Optional	String		TRUE	Schedule follow-up
notes	Free-text field for context or comments	Optional	String		TRUE	Needs follow-up next visit
custom_field_<field_name>	Additional custom field to be displayed with the insight	Optional	String		TRUE	custom_field_<Total_RAF> 2.56

File Ingestion Process

Once a file is received via sFTP, Vim initiates the ingestion process. This process fully replaces any previously ingested data and ensures that only the most up-to-date records are visible in the Care Insights application. Partial ingestion is not supported. If the file fails validation or ingestion is interrupted, the existing data remains unchanged.

This section outlines how ingestion is executed, what validations are applied, and how customers are notified in the event of errors.

Validations and Error Handling

Before ingestion, Vim performs a series of validations to ensure the integrity and accuracy of the submitted file. If the file fails any of the criteria below, it will be rejected and not ingested. In such cases, the existing data in the application remains unchanged, and Vim will notify the data source with details about the issue.

Important note: Files that do not follow the expected naming convention will not trigger the ingestion process, but they are not considered failures and will not generate an error notification.

A file will be rejected if:

• It is submitted in an unsupported format or delimiter
• It is empty or missing headers
• It is missing one or more required columns
• Field types do not match the defined schema
• Its size is more than 80% smaller than the previously ingested file

Additionally, individual rows within a valid file may be excluded from ingestion if:

• Required fields are missing
• Duplicate values are found for patient_unique_id or insight_unique_id
• None of the following identifiers are provided: patient_insurance_id, patient_ehr_id, or patient_zip_code

Rows that are excluded will not appear in the application. Instead, they are returned to the customer in a gating file (described below) with specific rejection reasons for correction.

Failed Gating File

If any rows in the submitted file do not meet the required field-level specifications, Vim excludes them from ingestion and compiles them into a gating file. This file contains the same fields originally submitted by the data source, with additional metadata appended by Vim to support troubleshooting.

The gating file includes the following additional fields:

Field Name	Description	Required?	Type	Expected values	Example
vim_auto_generated_uuid	Internal Vim UUID for the row	Auto-generated	String	UUID format	a34f98fd-4938-4fd1-b27e-2b60cb3c02e3
vim_auto_created_load_ts	Timestamp when the file was processed by Vim	Auto-generated	DateTime	YYYY-MM-DD HH:MM:SS	2025-07-06 01:23:45
vim_auto_created_data_received_ts	Timestamp when the file was received	Auto-generated	DateTime	YYYY-MM-DD HH:MM:SS	2025-07-06 00:45:12
vim_auto_created_filename	Original name of the uploaded file	Auto-generated	String		data_source_2025-07-06_diagnosis_gaps.csv
failure_reason	Reason the row failed ingestion	Required	String		Missing required field: patient_unique_id
This file is delivered to the data source via sFTP after each ingestion cycle. It enables teams to quickly identify and correct issues without blocking the ingestion of valid data.

Feedback Loop

Vim generates feedback files to share provider actions taken within the Care Insights application in a structured feedback files to the data source. These files help customers monitor engagement, track resolution, and update internal systems.

Feedback is delivered via the same sFTP connection and generated separately for Diagnosis Gaps and Care Insights.

Feedback File Format and Structure

Vim generates and delivers feedback files in a consistent format to support automated processing and reliable reconciliation. These files are shared with the data source via the same sFTP connection used for data ingestion.

The specifications below apply to all feedback files:

1. File name - <customer_name>YYYY_MM_DD__HH_MM_SS<insight_type_name>_report.csv
2. File type - CSV
3. File delimiter - Pipe (|) is standard; comma (,) is also supported
4. Cadence - Daily, weekly, or monthly — based on your preference
   • Recommendation: Align with your ingestion schedule to ensure a complete feedback cycle.
5. Coverage timeframe - Can represent a single day, week, or month
   • Recommendation: Use a timeframe consistent with your file delivery cadence.
6. Sending time - Scheduled for the end of the customer’s business day to ensure all provider actions are captured
   • Tip: Coordinate with your sFTP sync settings to avoid timing issues.

Feedback File Schema

The feedback passback files follow the structure below. Each row represents a single provider action.

The fields marked as “Always Included” will appear in every feedback file. Optional fields are included when relevant data is available.

Field Name	Description	Always Included?	Type	Expected values	Example
organization_name	Name of the organization in session	Yes	String		Scott's Clinic
vim_organization_key	Unique identifier for the organization in Vim	Yes	String		8i7owzgbgo6zJHYNxkNLRc
organization_tins	TINs associated with the organization	No	String	Comma-separated	Qwn479Ft954ojlj
ehr_type	The EHR system in session	Yes	String		eCW
user_first_name	First name of the user	No	String		John
user_last_name	Last name of the user	No	String		Doe
ehr_username	EHR username of the user	No	String		john.doe
user_npi	NPI of the user	No	Numeric	10-digit NPI	1848495833
user_roles	Roles of the user as defined in Vim	No	String		Medical Doctor
encounter_id	EHR encounter ID associated with the session	No	String		859574
encounter_date	Date of the encounter (org timezone)	No	Date	YYYY-MM-DD	2023-10-17
encounter_npi	NPI of the provider for the encounter	No	Numeric	10-digit NPI	1495738475
gap_system	Coding system of the gap (Diagnosis Gaps only)	Yes for Diagnosis Gaps	Enum	HCC or ICD	HCC
gap_id	Unique ID of the gap or insight	Yes	String		32fn48f
gap_code	Code associated with the gap or insight	Yes	String		82
gap_description	Description of the gap or insight	No	String		Assess Drug Dependence
selected_medical_codes	Codes selected during the session	No	String	Comma-separated
action_timestamp	Timestamp of the provider action	Yes	DateTime	YYYY-MM-DD HH:MM:SS	2025-07-06 08:42:22
action_type	Type of provider action	Yes	Enum	accept, dismiss, Undo	accept
action_reason	Reason selected for the action	No	String		ADD
action_additional_comments	Free-text comments provided during the action	No	String		not seen today
vim_patient_token	Encrypted internal patient identifier (Vim)	Yes	String		fj958tu94jgieorjf
patient_customer_id	Customer’s internal patient identifier	Yes	String		738463

Testing the Integration

Vim supports the data connections with the ability to perform end to end testing of the integration on Vim's mock EHR. If you wish to perform end to end testing in lower environments, please contact a vim representative.

Recommended: to be able to perform a production verification of the integration prior to the rollout, Vim supports adding dummy patients to the production file. A dummy patient should include the word "test" in the patient's first or last name.

Monitoring and Support

Vim is committed to knowledge and identify the root cause upon file ingestion failure within 24 hours from ingestion process start (excluding weekends).

For questions or technical assistance, contact Vim's Support Team at support@getvim.com.