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

:::tip 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 duplicate detection (see below)
  2. If project fields are present (project_id, title, etc.), a project is created and linked to the contact
  3. A contact can appear in multiple rows — each row with project fields creates a separate project under the same contact

Duplicate Detection​

Contacts are matched by (in order):

  1. legacy_id if provided
  2. company_name (exact match)
  3. first_name + last_name combination

If match found:

  • Contact record is updated with new data
  • New information merged, existing data preserved
  • Project (if present in row) is still created as new

Avoiding duplicates:

  • Check for existing contacts first
  • Use consistent company names
  • Provide legacy_id for re-imports

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