Bulk Import: Load Records from a File

Bulk Import loads many records from a CSV or XLSX file at once. Use it for onboarding historical data, migrating from another system, or making large changes without entering records one by one. You do not need to start from a record-specific template. Upload your own file, then map your file’s columns to the fields accepted for the record type you selected. The same flow creates records and updates matching records.

​

Prerequisites

Before starting an import, confirm the source file and related setup are ready. This helps you resolve mapping and validation issues before any records are imported.

• Know which record type you are importing, such as bank accounts, customers, vendors, items, or journal entries.
• Prepare a CSV or XLSX file with a header row and one record per row.
• Confirm your role includes permission to perform bulk imports.
• For chart-of-accounts-related imports, make sure your chart of accounts is configured first.
• Make sure referenced records already exist when your file depends on them, such as GL accounts, companies, currencies, classifications, or allowed custom field values.

​

Step 1: Open bulk imports

From the main navigation, open Workflows and choose Bulk Imports. The Bulk Imports page shows prior imports and lets you start another file import.

​

Step 2: Start an import and choose a record type

Choose New Import, then choose the record type you want to load. The record type determines which fields are available in the mapper, which fields are required, and how matching records are identified during import. Examples of available fields include:

• Core fields for the selected record type, such as name, company, currency, GL account, or opening balance.
• Classifications that apply to that record type.
• Custom fields configured for that record type in your organization.

​

Multi-line record types

Some record types, such as journal entries, are made up of a header plus two or more lines. For these, Bulk Import loads the full record, not just a header total. For journal entries, the import creates full entries with individual debit and credit lines. The same balancing rule applies as in the UI: total debits must equal total credits before an entry can post. Download the journal entry template from New Import → Journal entries → Prepare File for Import to see the exact columns for header and per-line fields, and how the template groups multiple lines into one entry.

​

Step 3: Upload a CSV or XLSX file

Upload your file in the import wizard. Bulk Import reads the file and prepares a preview before any records are imported. For XLSX files, Bulk Import reads the first sheet by default. If the workbook has multiple sheets, choose the sheet you want to import. For CSV files, Bulk Import detects the encoding and the delimiter, including commas, semicolons, and tabs. If your file does not use DualEntry’s column names, choose Download template for the record type and paste your data under its headers. The template’s columns map automatically and show which fields are required before you upload. Files can be up to 256 MB, with a maximum of 1,000,000 rows and 2,048 columns.

​

Step 4: Map your columns

Use the field mapper to connect each source column in your file to the matching destination field. The preview shows the parsed file on one side and the mapping controls on the other. In the mapper, you can:

• Map source columns to accepted fields for the selected record type.
• Add optional fields that are available for that record type.
• Remove optional fields you do not need.
• Map classifications and custom fields.

Required fields cannot be removed. If your file uses different column names than the destination fields, map the columns manually before importing.

​

Step 5: Review validation issues

Bulk Import validates rows while you map the file and again when you confirm the import. Rows with validation errors are not imported. Issues can include: Validation messages include the source row number so you can find the affected row in your original file. Row numbers count from the header row, so the first data row is one higher. For the full list of messages, with the cause and the fix for each, see Bulk Import Errors.

​

Step 6: Import the file

After the preview and mapping look correct, confirm the import. Bulk Import creates rows that do not already exist and updates matching records when the selected record type uses the same match key. The match key is configured per record type, so the columns that identify a record differ from one type to the next. Where a record type has an identity column, such as the record’s DualEntry ID, supplying it targets exactly one record and overrides the rest of the key. Leaving any match key column blank makes the row a create rather than an update. If two existing records share the same key values, the row fails rather than guessing. See Bulk Import Errors.

​

Result

After the import finishes, Bulk Import shows one of two results. If every row imports successfully, the success screen links to the imported records filtered to that import batch. If some rows fail, successful rows are still committed and the error screen shows only failed rows. Each failed row includes the source row number, the affected field, and the reason. You can review the failures in the UI or download the report as CSV to fix your source file. To work through those failures, see How to Fix a Failed Bulk Import. To look up a specific error message, see Bulk Import Errors. To connect external data sources for ongoing sync instead of one-time loads, see Integrations.