Enrollment via Flat File
Zus supports managing patient enrollments via flat file (CSV) upload. This option enables customers to create new patients, update demographics, and enroll or unenroll patients in subscription packages without making direct API calls. This approach is useful for organizations that prefer batch operations or have existing systems that can easily generate CSV exports.
Configuration
To enable flat file enrollment, contact your Zus representative to provision SFTP folders for your organization.
Access is configured via pre-shared key authentication.
• You will need to generate an SSH key pair.
• Send the public key to your Zus representative, who will register it with the SFTP service.
• The private key should be stored securely in your environment.
Once configured, you will be able to upload CSV files to your provisioned SFTP folder. Zus will automatically process new files placed there.
Roster File
Workflow
Upon receiving a new enrollment file in the /input folder, Zus will attempt to locate an existing patient matching the the identifier value and system provided.
- For patients that already exist, update demographics to match columns F-T of the file and update their enrollment status to match what is provided in columns A and B.
- For patients that do not already exist, create a new patient record with demographics matching columns F-T of the file and set enrollment status to match columns A and B.
- Return a validation response file to the
/outputfolder (see below).
Validation Response File
For each enrollment file, Zus will return a validation response file in the /output folder summarizing total patients enrolled, unenrolled, and any validation errors.
HEADER|File loaded with errors and/or warnings.
BODY|1850|EMAIL_ADDRESS: Invalid format, expected format is email format.
BODY|2250|EMAIL_ADDRESS: Invalid format, expected format is email format.
BODY|9914|EMAIL_ADDRESS: Invalid format, expected format is email format.
BODY|11550|CITY: Value is required.
BODY|11550|STATE: Value is required.
BODY|11550|ZIP_CODE: Value is required.
BODY|12823|CITY: Value is required.
BODY|12823|STATE: Value is required.
BODY|12823|ZIP_CODE: Value is required.
BODY|14783|EMAIL_ADDRESS: Invalid format, expected format is email format.
BODY|15563|EMAIL_ADDRESS: Invalid format, expected format is email format.
FOOTER|Activate: 17821|Deactivate: 0
The number provided indicates the file row number of the patient who encountered a validation error.
Caveats and Considerations
Naming convention: There is no strict standard for naming enrollment files. However, we strongly recommend including a timestamp or other unique identifier to ensure each file name is unique and human-readable.
Identifiers: The identifier value and system provided are used to determine whether a patient record needs to be created or updated. We recommend using a stable external system (such as an EHR or internal identifier) and using the same identifier system in subsequent files. Zus UPID is not supported as an identifier in this field.
Frequency: Files can be uploaded multiple times per day, however we recommend spacing uploads by 3-4 hours to avoid any collisions with multiple files being processed simultaneously.
Updated 3 days ago