Import Wizard
Bulk-import contacts and projects through a guided, four-step wizard that lets you map your data to Readybuild records before anything is written.
Overview
The Import Wizard lives under Settings → Imports and is designed for onboarding and migration — bringing in an existing book of clients, leads, and project history in one pass.
It differs from the Client Data Import dialog in one important way: before the import runs, the wizard shows you every distinct stage, project type, lead source, and salesperson in your file and asks what each one should become in Readybuild. Values that don't match anything are never silently dropped.
Two import sources are available:
| Source | Use when |
|---|---|
| CSV | You have a spreadsheet of contacts and projects in Readybuild's standard import format |
| BuilderTrend | You have Leads and Lead Activities exports from BuilderTrend |
Access requires the Company Setup permission.
Before You Start
Set up the records your import will reference, so you have something to map values onto:
- Sales stages
- Project types
- Lead sources
- Team members (salespeople)
You can also create missing stages, project types and sources from inside the wizard — but not team members, since a login can't be built from a name in a spreadsheet.
File Requirements
- Format: CSV, XLSX, or XLS
- Encoding: UTF-8 recommended
- Headers: First row must contain column headers
Column headers are matched loosely — First Name, first name, and first_name are all read as the same column, so you don't need to reformat an existing template.
CSV Columns
Your columns are your fields. The importer accepts any field configured on contacts or projects in your Readybuild account — including custom fields you've created yourself. There is no fixed template to conform to.
Name a column after either the field's label as it appears in Readybuild, or its internal name. Both work, and matching ignores case and spacing: Sales Person, sales person, and sales_person_id are the same column. To check which of your columns were recognized, upload the file and look at the Choose fields step — it lists every column it matched and where the value lands.
No column is required. A row creates a contact; a row that also carries a Project ID creates a project as well, so a contacts-only file imports cleanly.
Values by field type
| Field type | What to put in the cell |
|---|---|
| Text, Text area, Link | The text as-is |
| Number, Money | A number. Currency symbols and thousands separators are stripped |
| Date | Any recognizable date; stored as YYYY-MM-DD |
| Yes/No, Checkbox | y, yes, true, or 1 for yes — anything else is no |
| Dropdown | Must match one of the field's configured options |
| Dropdown (multi-select) | Separate values with semicolons: Kitchen; Bath |
| Stage, Source, Project Type, Team member, and similar | The name as it appears in your source system — you'll match it to a Readybuild record in the mapping step |
Structural columns
These few aren't fields; they control how rows are identified and where addresses go.
| Column | Description | Example |
|---|---|---|
project_id | Your system's project id. A row without this creates no project | JOB-1183 |
legacy_id | Your system's record id. Supply this so re-running updates rather than duplicates | CRM-4471 |
phone_number / phone_type | Contact phone; type defaults to Cell | (555) 010-4412 / Home |
project_note | Note attached to the project | Referred by the Ortegas |
mailing_address1 / mailing_address2 / mailing_address_zip | Contact mailing address | |
address1 / address2 / zip | Job-site address |
City and state are derived from the postal code, so you don't need to supply them.
A few field types have no sensible spreadsheet representation and are skipped: Contact and Subcontractor pickers (they point at other records), read-only fields, and the record ID.
The Four Steps
1. Upload Files
Choose your file and click Analyze files. Readybuild reads the file and collects every distinct stage, project type, source, and salesperson it contains. Large files are analyzed in the background.
2. Map Values
Readybuild collects every distinct value your file uses for stages, sources, project types, and people, then asks what each should become. People are gathered across all role columns at once — if Chris Alvarez appears as salesperson on some rows and estimator on others, you map him once and it applies everywhere.
Each distinct value appears with a choice:
| Action | What it does |
|---|---|
| Map to existing | Point the value at a record already in Readybuild |
| Create new | Create a Readybuild record using the value as its name |
| Skip rows | Exclude every row containing this value from the import entirely |
| Ignore field | Import the row, but leave this one field empty |
Values Readybuild could match on its own are pre-filled and tagged auto-matched — review them, and change any that matched the wrong record.
"Skip rows" is not "skip this field." If you mark the stage Lost as Skip rows, every lead in the Lost stage is excluded — no contact and no project is created for it. To import the row while leaving one field blank, choose Ignore field instead.
This applies to every category. Marking a person as Skip rows excludes all of their rows — contacts included — across every role column they appear in.
Your choices save automatically as you make them — there's no save button, and you can leave and resume later. Rows with a blank stage, type, source, or salesperson can't be mapped or skipped, since there's no value to match on; they import with that field left empty.
3. Choose Fields
This step lists only the columns actually found in your file, each with the Readybuild field it lands in — use it to confirm your headers were recognized. Turn off any column you don't want brought across; everything is enabled by default.
Fields your account supports that your file has no column for aren't listed, since there's nothing to import for them. The count above the list tells you how many were left out that way. If a column you expected is missing from the list, its header didn't match a field name or label — see CSV Columns.
4. Confirm & Run
Review the row counts and start the import. While it runs you'll see live progress — how many rows have been processed out of the total — and you can close the page; the import continues in the background and emails you a summary.
Click Cancel import to stop a running import. It halts at the next checkpoint, and rows already imported are kept.
Results
When the import finishes, the wizard shows a table of what was created, updated, and skipped for each record type, along with any errors. Errors are downloadable as a CSV listing the affected row and the reason.
Skipped counts include rows you deliberately excluded with Skip rows — those are counted, not reported as errors.
Re-running an Import
Re-running the same file updates existing records rather than duplicating them, as long as rows carry a stable legacy_id (or project_id). Without one, Readybuild derives a key from the contact's name, company, and email.
Notes
- Workflows, notifications, and similar automations do not fire for imported rows.
- Imported records are attributed to your company's system user, not to the person who ran the import.
- Address enrichment and search indexing run as usual.
Related
- Client Data Import — the Contacts board import dialog
- Import Field Reference
- Data Import & Migration