Esc

↑↓ move↵ openIndex · Pagefind
Using the app / Import your contacts from another CRM

Import your contacts from another CRM

Prepare a CSV, map the columns, review every row and create company intake contacts with a receipt. Plus what the import will and won't do, and how to export contacts back out.

Preview

Partly in the app today. Items marked Planned are not built yet.

On this page

The CRM import turns a CSV of contacts into new company intake contacts. You review every row before anything is created, likely duplicates are shown to you rather than merged, and you get a receipt that maps each row to the contact it created.

You need Company CRM Standard access (or company admin) to see Import on CRM Home.

Prepare the file

Rule Limit
Format CSV, UTF-8
Size 256 KiB per file
Rows 200 contacts per file
Columns 50
Required columns A stable external ID, first name, last name

Most CRMs can export contacts with a record ID. Use that as the external ID. It is how os.construction recognizes the same person if you import again.

Optional columns you can map: organization, email, phone, role, relationship, lead source, notes and owner user ID.

  • Relationship must be one of lead, client, partner or subcontractor.
  • Owner user ID is the numeric os.construction user ID of an active member. If you don’t have IDs, leave it unmapped and set the Relationship owner in the app afterwards.

An illustrative file:

Record ID,First Name,Last Name,Company Name,Job Title,Email,Phone Number
1001,Maria,Lopez,Harbor Point Dental Group,Facilities Director,maria@example.com,555-0142
1002,Sam,Okafor,Okafor Mechanical,Estimator,sam@example.com,555-0188

Run the import

  1. Open Import

    On CRM Home choose Import (the page is titled Import company contacts).

  2. Select a source and map columns

    Choose the file and enter a Source key: a short lowercase name for where the data came from, such as legacy_crm. Use the same key for every batch from that system.

    Map the external ID, first-name and last-name columns, then any optional ones. If the headers include Record ID, First Name and Last Name (a common CRM export layout), the page says so and fills the mapping in for you. Check it anyway. Choose Review import.

  3. Review every row

    Each row shows as an error, a possible duplicate, or Ready to create.

    • Errors block the whole batch: a missing name, an external ID repeated in the file or already imported under this source key, or an owner who isn’t an active member. Fix the CSV and review again.
    • Possible duplicates are existing intake contacts with the same email or the same first and last name, or similar rows within the file. They are suggestions only.
  4. Create the contacts

    Tick the box confirming you reviewed the possible duplicates (it appears only when there are some), then choose Create N contacts. You get an Import recorded receipt listing each row and the contact it created.

If the review changes between preview and commit (someone imported a matching contact in the meantime), the commit is refused and you preview again. Retrying the same request returns the original receipt, not a second set of contacts.

After the import

  • Tidy duplicates you chose to keep. Open the contact and use Merge into… to fold one contact into another. Merge moves opportunities, activities and service cases to the kept contact and cannot be undone from the app. See Contacts, people and organizations.
  • Assign owners. Filter Contacts by owner to find the ones with none.
  • Create opportunities for live pursuits by hand. They are not part of the import.

Export contacts back out

Anyone with Company CRM view access can choose Export → Download contacts CSV. It contains non-archived company intake contacts, up to 50,000 in the browser, with these columns:

id, project_id, first_name, last_name, organization, email, phone, role, relationship, source, owner_id, created_at, updated_at

Internal notes and project contacts are left out. Every export is recorded in the audit log, and cells are protected against spreadsheet formula injection. For larger lists, page through the CRM API. Open follow-ups export separately as a calendar file: Download calendar (.ics) on the Activities tab.

Common mistakes

  • Mistake: Using row numbers as the external ID

    In the app: Row numbers change between exports. Use the source CRM record ID, so a second import is refused instead of doubling people up.

  • Mistake: A new source key for every batch

    In the app: The duplicate-ID guard works per source key. Keep one key per source system.

  • Mistake: Expecting the import to update existing contacts

    In the app: It only creates. Edit existing contacts in the app, or merge after import.

  • Mistake: Saving the file from Excel in a legacy encoding

    In the app: The import needs UTF-8. In Excel choose CSV UTF-8 when saving, or names with accents will fail or garble.

Before you choose Create contacts

  • File is UTF-8, 200 rows or fewer, under 256 KiB
  • External ID column comes from the source CRM’s record ID
  • Source key is the same one you used for earlier batches from this system
  • Zero errors in the review
  • You looked at every possible duplicate and know which you will merge afterwards

Terms on this page

Lead conversion rate · Audit trail · Single source of truth

Next steps

Keep exploring

Related across os.construction

Run it on your own project.

Start a 14-day free trial. Want a say in what ships next? Join the founding program.

Your role (optional)

14-day free trial. Pricing for paid plans isn't set yet. Talk to us. Already have an account? Sign in →

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file