Import & Data Cleanup

If you are switching to ContractorScope AI from another estimating platform, spreadsheets, or a CRM, the Import tool lets you bring your existing data along. Import your client list, past estimates, and price book so you can hit the ground running without re-entering everything by hand.

Import is a first-class action in ContractorScope AI. You can start an import at any time from the Import button in the left sidebar, or from Settings > Import & data cleanup. You do not need to be in the middle of onboarding.

This guide covers importing from CSV files, mapping fields to ContractorScope AI's data model, configuring custom fields, and troubleshooting common import issues.

---

What You Can Import

ContractorScope AI supports importing the following data types:

Data Type	Supported sources
Clients / Contacts	CSV, QuickBooks, ServiceTitan, Jobber, HubSpot
Price Book	CSV
Past Estimates	CSV (summary-level)
Products / Materials	CSV

note

Importing full estimate line-item history from other platforms is not currently supported due to the wide variation in export formats. You can import estimate summaries (client, date, total, status) and re-build templates from your price book.

---

Supported File Formats

CSV Requirements

CSV files must meet these requirements:

• Encoding: UTF-8
• Delimiter: Comma (,) — not semicolon or tab
• Max file size: 50 MB
• Max rows: 10,000 rows per import (split larger files)
• Header row: Required — the first row must contain column names

Excel Files

You can upload an Excel workbook (.xlsx or the legacy .xls format) directly — there's no need to convert it to CSV first. The same limits apply: 50 MB max file size, 10,000 rows per sheet. If your file is mislabeled (e.g. a workbook saved with a .csv extension), the importer detects the real format from the file's contents and reads it correctly anyway.

If your workbook has multiple sheets, every sheet with a header row is read and combined automatically — you don't need to merge them yourself first. A sheet with no column headers (e.g. a cover page or notes tab) is skipped; if none of your sheets have headers, the import will ask you to add a header row (e.g. "First Name", "Email", "Phone") to the first data row.

The one case where converting to CSV still helps: if your data uses formulas, pivot tables, or heavy formatting that you want stripped down to plain values before mapping — otherwise, upload the .xlsx/.xls file as-is.

Preparing Your File

Before importing, clean up your source file:

• Remove any merged cells (if exporting from Excel).
• Ensure phone numbers are consistent (e.g., all (555) 123-4567 or all 5551234567 — mixing formats will import, but may need cleanup).
• Remove any duplicate rows.
• Make sure required fields (see below) are populated.

---

Importing CRM Data

Step 1: Download a Template

ContractorScope AI provides CSV templates pre-formatted with the correct column headers. Using a template reduces mapping errors.

1. Go to Settings → Import & data cleanup (or click Import in the left sidebar).
2. Click Download Template next to the data type you want to import.
3. Open the template in Excel or Google Sheets and paste your data into the appropriate columns.

Step 2: Upload Your File

1. Go to Settings → Import & data cleanup (or click Import in the left sidebar).
2. Click New Import.
3. Select the data type: Clients, Price Book, Estimates, or Products.
4. Click Choose File or drag your CSV onto the upload area.
5. The file uploads and the system scans the first 10 rows to auto-detect column mappings.

Step 3: Map Your Fields

The field mapping screen shows your CSV columns on the left and ContractorScope AI fields on the right. The system attempts to auto-map based on column names, but you should review every row.

note

The mapping you set here is what the import uses. If you change a column's destination — or correct one the auto-mapper guessed wrong — your choice is applied to every row when you run the import. (Earlier, a spreadsheet import could ignore your edited mapping and finish with zero rows imported while still showing success; that is fixed. If an import ever completes with no rows imported, re-check the mapping screen and the error report below.)

Required Fields by Data Type

Clients:

Field	Required	Notes
First Name	Yes
Last Name	Yes
Email	No	At least one of email or phone is required
Phone	No	At least one of email or phone is required
Street Address	No
City	No
State	No	2-letter abbreviation
ZIP	No

Price Book Items:

Field	Required	Notes
Item Name	Yes
Unit of Measure	Yes	e.g., EA, LF, SQ, SF
Unit Cost	No	Your cost (used for margin calculation)
Unit Price	Yes	The price you charge clients
Category	No	Groups items in the price book

Step 4: Configure Options

Before running the import, choose how to handle duplicates and conflicts:

Option	Description
Skip duplicates	If a matching record already exists (matched by email or name), skip the incoming row
Update duplicates	If a match is found, overwrite the existing record with the imported data
Create duplicates	Import all rows regardless of existing records — you will de-duplicate manually

For most first-time imports, Skip duplicates is the safest choice.

Step 5: Preview and Run

1. Click Preview Import to see the first 20 rows as they will be imported.
2. Review for any obvious errors.
3. Click Run Import.
4. A progress bar shows how many rows have been processed. Large imports run in the background — you will receive an email when they complete.

tip

For large imports (more than 1,000 records), start with a test run of 50 rows to verify the mapping is correct before importing the full file.

---

Custom Field Configuration

ContractorScope AI lets you define custom fields on clients, estimates, and jobs. This is useful when your existing system has fields that do not have a direct match in ContractorScope AI's standard data model.

Creating Custom Fields

1. Go to Settings → Custom Fields.
2. Choose the record type: Client, Estimate, or Job.
3. Click Add Custom Field.
4. Configure the field:

Setting	Options
Label	The name shown in the UI and reports
Field Type	Text, Number, Date, Dropdown, Checkbox
Required	Whether this field must be filled before saving
Show on Estimates	Whether this field appears in the estimate editor
Include in PDF	Whether this field appears in exported PDFs

5. Click Save. The field is now available in the form editor and in Data Import field mapping.

Mapping Custom Fields During Import

After creating custom fields, they appear in the Destination Field dropdown on the field mapping screen. Map your source column to the custom field just like any standard field.

note

Dropdown custom fields require that the imported values match the options exactly (case-sensitive). For example, if your dropdown has "Residential" and "Commercial", an import row with "residential" (lowercase) will fail validation. Use the data quality tools (see below) to catch these mismatches before running the full import.

---

Troubleshooting Import Errors

Viewing the Error Report

After an import runs, a summary shows:

• Rows imported successfully
• Rows updated (existing records matched and overwritten, in Update mode)
• Rows quarantined (held back for review — see below)
• Rows skipped (duplicates, if Skip mode was used, or a row whose id collided with a different company's record — see Common Errors and Fixes)
• Rows with errors

Click Download Error Report to get a CSV of the failed rows with an error description in the last column. Fix the errors in the source file and re-import only the failed rows.

Quarantined Rows (imported 0 — but not a mapping problem)

Some rows that mapped correctly are still held back if they fail a data-quality gate — for example, a row with no usable name/email/phone to identify the contact, an address that's too low-confidence to trust, or a record that's ambiguous against your existing data. These rows are quarantined rather than imported.

When this happens, the import summary tells you exactly that — for example: "0 imported — 2 row(s) were quarantined: low_quality (2). Review them in Import History." It deliberately does not tell you to "check your column mappings," because your mapping was honoured — the rows simply didn't clear the quality bar. The summary line also shows a Quarantined: N count next to the imported and skipped counts.

To resolve quarantined rows: open the relevant records in your source file, add the missing identifying details (a real name, a valid email or phone, a complete address), and re-import. Quarantine protects your CRM from junk rows like placeholder @example.com addresses and blank contacts.

Common Errors and Fixes

Error message	Cause	Fix
Required field missing: Unit Price	A price book row has no sell price	Add the Unit Price column and fill it in
Invalid email format	Email address is malformed	Correct the email or leave the field blank
Duplicate row skipped	A matching record already exists	Expected in Skip mode; switch to Update mode if you want to overwrite
Invalid unit of measure: "square"	Unit must be an abbreviation	Change to SQ
Value exceeds maximum length	A text field is too long (max 500 chars)	Truncate the value
Invalid date format	Date is not in YYYY-MM-DD format	Reformat all date columns
Dropdown value not found: "residential"	Case mismatch on a dropdown field	Match the case exactly or add the value to the dropdown options
N row(s) skipped: contact_id already belongs to a different company	Your source file's "Contact #" (or other id column) collides with an id already used by a different ContractorScope AI company — a safety check refuses the import row rather than risk overwriting someone else's record	Give the colliding rows a new, unused id in your source file and re-import just those rows

Data Quality Tools

Before running a large import, use the built-in data quality check:

1. After uploading your file and completing field mapping, click Run Quality Check instead of Run Import.
2. The system scans all rows and flags potential issues without importing anything.
3. Download the quality check report, fix the issues in your source file, and re-upload.

The quality check catches:

• Missing required fields
• Invalid formats (email, phone, date)
• Values that do not match dropdown options
• Duplicate records

---

Post-Import Steps

After a successful import:

1. Review a sample — Open 5–10 imported records and verify the data looks correct.
2. Check custom fields — Confirm custom field values imported as expected.
3. Clean up duplicates — If you imported with the Create duplicates option, run a deduplication pass from Settings → Import & data cleanup → Find Duplicates.
4. Set up integrations — If you use QuickBooks or another integration, connect it now so future data stays in sync without manual imports. See QuickBooks Integration.

---

Next Steps

After importing your data, here are some important next steps:

• Account and Billing
• Multi-Company
• QuickBooks Integration
• Analytics & Reports