Ingest Transaction, Account, and Form Data via File Uploader
Welcome to the guide for the Ingest Page (within Manage Data) in the TaxBit Dashboard. This tool offers a streamlined way to upload your data files. Follow our step-by-step instructions to make the most of this self-service feature to ensure a smooth data ingestion process with TaxBit.
Accessing the “Ingest” Page
1. Login to TaxBit: Enter your credentials to log in to the TaxBit Dashboard.
If you have access to multiple Dashboard instances, select the appropriate environment in the top right hand corner.
2. Navigate to “Manage Data”: The “Manage Data” module can be found in the left-hand navigator of the TaxBit Dashboard.
3. Select “Ingest”: The “Ingest” page is located within the “Manage Data” module.
Using the “Ingest” Page
The “Ingest” page simplifies the data ingestion process, enabling you to upload CSV and/or JSONL files, identify any data formatting errors, and track the ingestion status of a file, without assistance from the TaxBit team.
We currently support the upload of the following information to the TaxBit Dashboard. Additional detail on each type of information is provided in the linked guides below:
Primary Functions
Upload a File
1. Select File Type: Select the relevant data type of the file you want to upload (i.e., Accounts, Transactions, Form Data), by clicking on the appropriate tile. Please note, Account Owner and Account information are uploaded together via the Account template (See Account / Account Owner).
2. [Form Data ONLY] Select Form Type and Form Year: Before ingesting Form Data, the relevant Form Type and Form Year must also be selected from the dropdown menus. A template will not be made available for download (as noted in the subsequent step) until the Form Type is selected – there is a unique template per Form Type. Note that Form Data can only be provided for a single year at a time.
3. Download Template: Download the relevant TaxBit CSV template by clicking the link provided. Your data must be organized according to this CSV template for successful ingestion by TaxBit. Additionally, a guide is available for download to clarify the requirements for each column in the CSV template.
4. Upload File: To upload a file, either drag and drop it into the uploader or click “browse files” to select and upload the appropriate file.
5. Initiate the upload by clicking “Upload File”, once your file is visible in the uploader.
Please note the following:
- The uploader will only accept a CSV or JSONL file (a JSONL file is only acceptable for transaction information). All other file types (e.g., XLXS files) will be rejected.
- Only one file can be processed at a time, across all data types.
- An error message will alert you immediately if the headers included on your CSV file do not align with those in the relevant, acceptable template.
- You must remain on the Ingest page of the TaxBit Dashboard until the upload is complete, which is indicated by the file's appearance in the file history table at the bottom of the screen with a status of “Validating”.
Review Data Errors & Warnings
1. Data Validation: After your file is uploaded, it will undergo a thorough validation process to verify that all fields are correctly formatted and meet TaxBit's system requirements. Throughout this period, your file will have a status of "Validating."
Once the validation process is complete, the status should update to “Needs Review.”
Please note, however, if all rows of data within the uploaded file are invalid, the status would instead be updated to “Invalid.”
Additionally, if anything were to go wrong during the validation process, the status would be updated to “Contact Support.”
2. Download Summary Reports: Once the validation process is complete, TaxBit will surface detailed filings for your review before proceeding.
During the validation process, the TaxBit engine will detect whether there are any errors and/or warnings in the file you provided –
- Errors are identified in rows of data that do not comply with TaxBit's requirements. These are critical issues that prevent data from being processed / ingested correctly. Errors might stem from missing fields, incorrect data formats, or values that fall outside of accepted parameters. Data rows marked with errors must be corrected to be in compliance with TaxBit's standards and re-uploaded in order to be ingested.
- Warnings flag data that exhibits unusual formatting or characteristics, with the intention of highlighting potential issues that don’t currently violate any specific rules, but are noteworthy for additional manual review before proceeding with ingestion. Data flagged with warnings will still be ingested if the file is approved, provided there are no errors.
This detail, as well as a breakdown of new versus updated records can be found by clicking the three-dot icon located at the far end of the file history table, and then selecting “Download Summary Reports.”
There are 4 reports that may be provided in the zip file, depending on the file:
- Error & Warnings Details: The detailed report offers a line-by-line breakdown of errors and warnings encountered during validation. This report will only be available after validation if errors and/or warnings are identified in your data.
- Error & Warnings Summary: The summary report gives an overview/count of the errors and warnings detected. This report will only be available after validation if errors and/or warnings are identified in your data.
- New Records: The New Records report provides a list of ID’s that do not currently exist in TaxBit’s system and will be created if the file is approved.
- Updated Records: The Updated Records report provides a list of ID’s that already exist in TaxBit’s system and will be updated (i.e., overwritten) if the file is approved.
Approve / Reject Data Ingestion
Note – this functionality is only applicable to files with a status of “Needs Review.”
If the file status is “Invalid”, there will not be an option to “Review File”, since every record in the file contains one or more errors, and therefore, no records are available for ingestion. In these instances, it is recommended that you review the Summary Reports and resolve any errors before re-uploading.
1. Review File: Once you have completed your review of any errors / warnings, the file requires your approval for data ingestion to proceed. At this stage, none of the information included within the file has been ingested.
To review the file, click the three-dot icon located at the far end of the file history table and select “Review File.”
This should open a pop-up displaying next steps, as well as key summary counts. Review these counts to ensure they align with your expectations before proceeding with either clicking “Approve File” or “Reject File”. Please note, this decision is necessary, even if no errors/warnings are detected in your data.
2a. Approve File: By clicking “Approve File”, TaxBit will proceed with the data ingestion of the file. Please be aware, however, that only error-free, valid records will be processed upon approval. Any records with errors will be excluded from ingestion.
Once a file is approved, the file status will update to “Processing.”
Once the file is done processing, the file status will update to “Complete” to indicate that the data has been ingested successfully.
2b. Reject File: Alternatively, you have the option to "Reject File" – in which case, none of the file's records will be processed by TaxBit.
Once a file is rejected, the file status will update to “Rejected.”
You have the option to remove a file with a status of “Rejected” so the file will no longer appear in the file history table. To remove the file, click the three-dot icon located at the far end of the file history table and select “Remove.”
Note – You may also remove a file with a status of “Invalid” by following the same steps.
View File Details
At the bottom of the page, you'll find a file history table that enables you to filter and view information on current and past uploads. The table supports filtering by file type (i.e., Accounts, Transactions, or Form Data), and provides detailed information for each entry:
- File Name: The name of the file at the time it was uploaded. The file name cannot be changed once it is uploaded.
- Type: The data type of the file (i.e., Accounts, Transaction, or Form Data).
- Status: The current ingestion status for the file (For additional detail, see FAQs)
- Rows: The total row count represents the number of rows provided in your uploaded file.
- Valid: The count of valid records. A valid record is a record without any detected errors.
- Invalid: The count of invalid records. An invalid record contains at least one error.
- Warnings: The count of records with warnings. This count includes rows with at least one warning.
- Date: The date the file was uploaded.
- Description: A description for the file. This field is optional and can be set by a user after a file is uploaded.
- Author: The name of the user who uploaded the file.
Troubleshooting and Support
- Common Dashboard Issues: Refer to the FAQ section on the dashboard for solutions to common issues.
- Tips for Working with CSVs: Refer to this guide for key items to consider to ensure a successful and efficient CSV file ingestion process.
- Customer Support: For further assistance, contact TaxBit’s support team through the helpdesk available on the dashboard.