This process applies to post-tax accounts only. To process a Balance Transfer file for pre-tax benefits, please see the article Pre-tax balance transfer file specifications
Before You Begin
- Review the article: What is a balance file and how does it work? to ensure your file is formatted correctly.
- Maximum file size: 5,000 rows of data.
- File format: CSV only.
- Balance file uploads are account-specific. To adjust balances across multiple accounts, you’ll need to upload a separate file for each account.
- When using a balance file to add funds, the upload will process even if an employee’s balance exceeds the account maximum.
- If an employee’s balance exceeds the account maximum through a balance file and remains over the limit at renewal, then at the next renewal date they will not receive additional renewal funds. Additionally, any excess amount will be removed, leaving only the maximum allowed balance.
How to Upload a Balance File
- Log in to Forma Admin.
- Navigate to Benefit Accounts.
- Scroll to the account you’d like to update.
Click the three-dot menu next to the account and select Upload balance file. - In the pop-up:
- Click Upload CSV file and select your file.
- (Optional) Click Download sample file to see the required file template.
- Click Continue with updates to process the file.
⏱️ Processing time: About 30 minutes.
When you upload a file, the system automatically scans for issues:
Warning Checks
- Duplicate Transaction Protection: Warns if a similar transaction for the same employee was uploaded within the last 24 hours.
- Amount will exceed the wallet max amount: Warns if the credited amount would cause an employee’s balance to exceed the account maximum.
- File Queueing: Only one balance file can be processed per account at a time.
Error Checks
- Duplicate Prevention: Flags duplicate employee emails and blocks processing until fixed.
- Transaction Checks: Validates transaction types (i.e. invalid transaction type, missing transaction type)
- Amount Checks: Validates amount values (i.e. negatives, non-numerics)
- Validate Format: File is empty or cannot be parsed, meaning that Forma is unable to read, analyze, and interpret a file because its content does not match the expected structure or format
⚠️ You can proceed with files that have warnings, but errors must be corrected before the file can be uploaded successfully.
Viewing Uploaded Files
To see a history of balance files uploaded:
- Go to File Manager.
- Select the Balance Files tab.
Balance File Statuses
Each balance file you upload will display one of the following statuses:
- Pending – The file is scheduled for a future execution time and will remain in this status until processing begins.
- Processing – The file is actively being processed.
- Complete – The file has been successfully processed.
The contribution report provides a centralized view of balance file upload records, allowing admins to easily track and verify the status of uploads in one place. For more information, see the article How do I create a Contribution Report on Forma Admin?