Skip to main content

Client Data & Project History Import

Import historical client data and projects from your previous system.

Overview​

The import system lets you migrate contacts and projects from another software platform or bulk-add records. Each row in your CSV represents a contact, optionally with a project attached. Contact fields and project fields go in the same row.

What Gets Imported:

  • Contact Information - Names, email, phone, address
  • Company Details - Company name, type, status
  • Lead Attribution - Source, campaign
  • Custom Fields - Your custom contact fields
  • Projects - Project details, team assignments, financial summaries

See the Field Reference for all available CSV columns.

What Can Be Imported​

  • Contacts - Client and vendor information
  • Projects - Project details with basic financial summary

These record types are complex and tightly integrated with other system features. They're best created fresh in Readybuild:

  • Estimates - Depend on item database, categories, and pricing structures
  • Contracts - Linked to estimates, payment schedules, and approval workflows
  • Invoices - Tied to contracts, change orders, and accounting integrations
  • Change Orders - Reference contract line items and approval chains
Start Fresh

Most companies find it easier to import contacts and historical project summaries, then create estimates and contracts fresh for any active work.

Planning Your Import​

What to Include​

Essential:

  • Active clients
  • Recent completed projects (1-2 years) for reference
  • Key project financial totals

Consider Skipping:

  • Very old records (5+ years)
  • Incomplete or test data
  • Detailed estimate line items
  • Historical invoices and payments

Data Assessment​

Before importing:

  1. Export data from your current system
  2. Review data quality and completeness
  3. Clean up duplicates and inconsistencies
  4. Map your fields to Readybuild fields (see Field Reference)

Import Process​

Step 1: Prepare Your Data​

  1. Export from previous system to CSV/Excel
  2. Clean up inconsistencies
  3. Map your columns to Readybuild fields
  4. Save as CSV with UTF-8 encoding

Step 2: Upload and Map​

  1. Go to Contacts board
  2. Click Import
  3. Select Clients as contact type
  4. Choose your CSV file
  5. Click Upload
  6. Review automatic column mapping
  7. Adjust any mismatched columns
  8. Map custom fields if applicable
  9. Click Import
  10. Import runs in background

Each row creates a contact. If a row includes project fields (like project_id), a project is also created and linked to that contact.

Step 3: Verify Results​

  1. Spot-check a sample of imported records
  2. Verify contact-project relationships
  3. Check that financial totals look correct
  4. Confirm team assignments

How Rows Are Processed​

Each CSV row is handled as follows:

  1. Contact is created or matched using email-based duplicate detection (see below)
  2. If project_id is present, a project is created — or, if a project with that project_id already exists in your company, it is updated in place
  3. A contact can appear in multiple rows — each row with a distinct project_id creates (or updates) a separate project under the same contact

Duplicate Detection​

Contacts are matched by (in order):

  1. legacy_id if provided (preserved across re-imports — see below)
  2. email (case-insensitive, exact match within your company)

Name-based matching is not used. Two rows with the same first_name + last_name but different or empty emails will create two separate contacts — this is intentional, because name collisions between distinct people are common.

Projects are matched on project_id (case-sensitive, exact match within your company). A CSV row with a project_id that already exists — whether the project was created in the UI, via a prior import, or elsewhere — updates that existing project. This prevents the import from creating duplicate project records sharing the same human-visible project number.

If contact match found:

  • Contact record is updated (non-email fields from the row overwrite existing fields)

If project match found:

  • Project record is updated (fields from the row overwrite existing fields) and is linked to the contact resolved for this row

If no match:

  • A new contact and/or project is created

Re-importing the same CSV:

  • Rows with an email are fully idempotent — a second import of the same file updates in place instead of creating duplicates
  • Rows without an email fall back to a hash of the identifying columns (company name or first + last name, plus project_id), which is still idempotent across re-imports provided those columns don't change
  • Rows with neither an email nor an identifying name will duplicate on re-import — clean your source data first

Avoiding duplicates:

  • Provide valid, consistent email addresses whenever possible
  • Provide legacy_id explicitly for maximum control over re-imports
  • Clean your source data before importing — the import does not fuzzy-match on typos, whitespace, or capitalization differences in names

Import Results Email​

After processing, you'll receive an email with:

Summary Statistics:

  • Total rows processed
  • Successfully imported
  • Skipped (duplicates)
  • Failed (errors)

Error Details:

  • Row number
  • Contact information
  • Error message
  • First 50 errors shown

Before You Import​

Sources and Campaigns​

Sources and campaigns must exist before import — they are not auto-created:

  • Create sources in Admin → Marketing → Sources
  • Create campaigns in Admin → Marketing → Campaigns
  • Unmatched values will be left blank

Stages, Divisions, and Types​

All lookup fields must match existing values in the system:

  • Divisions: Admin → Settings → Divisions
  • Project Types: Admin → Settings → Project Types
  • Sales Stages: Admin → Settings → Sales Stages
  • Design Stages: Admin → Settings → Design Stages
  • Production Stages: Admin → Settings → Production Stages

Team Members​

For team assignments to work:

  • Team members must already exist in Readybuild
  • Use their employee number, not their name or ID
  • Find employee numbers in Admin → Team
  • Leave blank if unsure and assign manually later

Common Issues​

Missing Required Fields​

At minimum, provide:

  • Company name, OR
  • First name AND last name

To create a project, project_id is also required.

Invalid Email Format​

Email must be valid format:

  • Check for typos
  • Remove extra spaces
  • Valid domain required

Date Formatting​

Use consistent date format:

  • YYYY-MM-DD (recommended)
  • MM/DD/YYYY
  • DD/MM/YYYY (specify locale)

File Format Problems​

  • Wrong delimiter - Use commas, not semicolons or tabs
  • Encoding issues - Save as UTF-8
  • Extra columns - Remove columns not in template

Invalid References​

  • Ensure linked records exist (stages, sources, campaigns)
  • Team member employee numbers must exist in the system
  • Check that field values match expected formats

Data Cleanup Tips​

Names:

  • Standardize format (Smith vs. The Smiths)
  • Consider adding "Residence" or "Home" for consistency
  • Remove special characters

Addresses:

  • Verify ZIP codes match cities
  • Standardize abbreviations (St. vs Street)
  • Check for and merge duplicates

Financial Data:

  • Numbers only (no $ or comma symbols)
  • Use decimals for cents (75000.00)
  • Leave blank if unknown—don't use zero

Dates:

  • Use consistent format (YYYY-MM-DD preferred)
  • Leave blank if unknown
  • Verify dates are logical (sold date after created date)

Contact Info:

  • Verify email addresses
  • Update phone numbers
  • Remove invalid data

After Import​

For Historical Records​

  • Mark as appropriate stage (Won/Lost/Complete)
  • Available for reporting and reference
  • No further action needed

For Active Projects​

After importing the basics:

  1. Create estimates fresh in Readybuild
  2. Generate contracts from estimates
  3. Set up payment schedules
  4. Assign team members
  5. Create production schedules

Complete Missing Information​

Some data doesn't import well and should be added manually:

  • Activities and notes
  • Documents and photos
  • Detailed estimates
  • Production schedules

Organize Imported Contacts​

  • Assign to salespeople
  • Set pipeline stages
  • Add to campaigns

Best Practices​

Test First​

  • Import a small sample (10-20 records)
  • Verify results thoroughly
  • Adjust your mapping if needed
  • Then do the full import

Keep Your Mapping​

  • Document which of your fields mapped to which Readybuild fields
  • Save your original export files
  • Use legacy_id to cross-reference later

Accept Some Loss​

Not everything transfers perfectly:

  • Some data may need manual entry
  • Focus on what's most valuable
  • Start fresh where it makes sense

Data Quality​

  • Clean data before import
  • Remove duplicates in source
  • Verify email addresses

Standardization​

  • Consistent company naming
  • Standard source values
  • Uniform address format

Attribution​

  • Always include source
  • Link to campaigns
  • Track referrals