How Auto-Matching Works
When you upload a file and reach the mapping step, PrimeConnect automatically reads every column header in your spreadsheet and attempts to match each one to the corresponding QuickBooks field for the selected entity type. This process, called auto-matching, uses fuzzy string comparison to handle variations in naming.
How it works
PrimeConnect compares your column header text against a list of known QuickBooks field names and common aliases. The comparison is case-insensitive and ignores special characters, so minor differences in naming, spacing, or punctuation are tolerated. Here are some examples of how auto-matching resolves common column names:
| Your Column Header | Matched QuickBooks Field |
|---|---|
| "Invoice Number", "Inv #", "InvoiceNo" | RefNumber |
| "Customer Name", "Customer", "Bill To" | CustomerRef |
| "Date", "Invoice Date", "TxnDate" | TxnDate |
| "Amount", "Total", "Line Amount" | Amount |
| "Item", "Item Name", "Product" | ItemRef |
| "Description", "Desc", "Memo" | Description / Memo |
| "Quantity", "Qty" | Quantity |
| "Rate", "Price", "Unit Price" | Rate |
| "Account", "Account Name" | AccountRef |
Match indicators
After auto-matching completes, each column shows one of two states:
- Green checkmark — PrimeConnect found a confident match. The matched QuickBooks field is displayed in the dropdown. You should still verify it is correct.
- Empty dropdown — no match was found. You need to manually select the correct field or leave it unmapped (see Handling Unmapped Columns).
Manual Field Mapping
When auto-matching does not find a match for a column, or when you need to override an incorrect auto-match, you can manually assign the mapping.
How to map a field manually
- Find the column in the mapping list that needs to be mapped (or re-mapped).
- Click the dropdown next to the column name. This opens the list of available QuickBooks fields for the selected entity type.
- Search or scroll to find the correct field. The dropdown includes a text filter input at the top — type a few characters to narrow down the list (e.g., type "ref" to see all reference fields).
- Click the desired field to select it. The column is now mapped.
Changing an existing mapping
To change a mapping that was set by auto-match or a previous manual selection, simply click the dropdown again and choose a different field. The previous mapping is replaced instantly.
Clearing a mapping
To unmap a column (so that it is ignored during import), click the dropdown and select the blank/empty option at the top of the list. The column will then be treated as unmapped.
Required vs Optional Fields
QuickBooks requires certain fields to be present for each record type. In the mapping screen, these fields are visually distinguished so you know which mappings are mandatory.
Required fields
Required fields are marked with a red asterisk (*) next to the field name. The Next button will be disabled until all required fields have a mapping assigned. You cannot proceed to the validation step with unmapped required fields.
Required fields vary by entity type. Here are some common examples:
| Entity Type | Required Fields |
|---|---|
| Customers | Name |
| Vendors | Name |
| Invoices | CustomerRef, at least one line item (ItemRef + Amount or Quantity + Rate) |
| Bills | VendorRef, at least one line item |
| Journal Entries | AccountRef, Amount, debit/credit designation |
| Items | Name, ItemType |
| Accounts | Name, AccountType |
Optional fields
All other fields are optional — mapping them adds more data to the QuickBooks record, but the import will succeed without them. Optional fields include things like memo, description, due date, PO number, ship address, terms, and class.
Saving Mapping Templates
If you regularly import files with the same column structure, you can save your mapping configuration as a template for instant reuse in future imports.
How to save a template
- Configure all your field mappings in Step 3 of the import wizard.
- Click the Save Template button at the top of the mapping screen.
- Enter a descriptive name for the template (e.g., "Monthly Invoices from Accounting", "Vendor Import from ERP", "Customer List Update").
- Click Save. The template is stored locally in PrimeConnect's database and is available for all future imports of the same entity type.
What gets saved
A mapping template stores the complete column-to-field mapping configuration, including:
- Each column header name and its mapped QuickBooks field
- The entity type the template applies to
- Any columns that are intentionally left unmapped
Loading Saved Mappings
Loading a saved template applies a complete field mapping configuration in one click, eliminating the need to manually map each column.
How to load a template
- In Step 3 (Map Fields) of the import wizard, click the Load Template button at the top of the mapping screen.
- A list of saved templates for the current entity type is displayed. Select the template you want to apply.
- PrimeConnect applies the saved mappings to your current file. Each column header in your file is matched to the corresponding column name in the template.
What happens if columns differ
If your new file has columns that were not in the saved template (e.g., a new column was added), those columns will remain unmapped. If the template references columns that are not in your new file (e.g., a column was removed), those mappings are silently skipped.
After loading a template, you can still adjust individual mappings before proceeding. The template gives you a starting point — you have full control to fine-tune as needed.
Handling Unmapped Columns
It is common for spreadsheet files to contain columns that have no corresponding field in QuickBooks. These might be internal reference numbers, notes, formulas, or data from another system that is not relevant to the QuickBooks import.
What happens to unmapped columns
Columns that are not mapped to any QuickBooks field are completely ignored during the import. They will not cause errors, warnings, or any side effects. PrimeConnect simply skips them when building the QuickBooks request for each row.
This means you do not need to remove extra columns from your spreadsheet before importing. Leave them in place — they will be harmlessly ignored.
Identifying unmapped columns
In the mapping screen, unmapped columns are visually distinguished — they appear with an empty dropdown and no green checkmark. You can review the list at a glance to confirm that only non-essential columns are unmapped.
Best Practices
Follow these recommendations to get the most out of PrimeConnect's field mapping system:
- Name columns to match QuickBooks field names. The closer your column headers are to the actual QuickBooks field names, the more accurate auto-matching will be. Use names like "CustomerRef", "TxnDate", "RefNumber", and "Amount" for the best results. Check the sample files for the exact field names PrimeConnect expects.
- Create one template per file format. If you receive data from multiple sources (e.g., an accounting system, a CRM, and a POS), create a separate mapping template for each source. Name them clearly (e.g., "CRM Customer Export", "POS Daily Sales").
- Review mappings before every import. Even when using a saved template, take 30 seconds to review the mapping screen. File structures can change over time — a renamed or reordered column could lead to data being imported into the wrong field.
- Use the sample files as a reference. PrimeConnect's sample files use the exact column names that auto-matching expects. Use these as a template when creating your own import files.
- Do not map columns that contain formulas. If your spreadsheet has calculated columns (e.g., "Total = Qty x Rate"), do not map them. QuickBooks calculates totals from line item quantities and rates — importing a pre-calculated total can cause discrepancies.
- Keep headers on the first row. PrimeConnect reads the first row of your file as column headers. If you have title rows, instructions, or other content above your data headers, remove them before importing.