The Import feature has two tabs:

• Tenants: add new tenants and update existing ones.
• Units: add the units in your building, with or without tenants.

Before you start

• You don't need to reformat your file. You can upload a CSV, Excel (.xlsx or .xls), or PDF file.
• Files can be up to 20 MB and 10,000 rows. If your list is larger, split it into smaller files and upload them one at a time.
• Your file should have a header row (column names) above the data.
• For each tenant, we need:
  1. First name
  2. Last name
  3. Unit number
  4. Floor, for units that are not in the ButterflyMX system yet
  5. Email or phone number (or both)
• For each unit, we need:
  1. Unit number
  2. Floor, for units that are not in the ButterflyMX system yet
• Optional information you can include for tenants: text message number, move-in date, move-out date, directory name, resident ID, in-unit phone, PIN, unit contact, and company name (for business units).
• Don't have a file? Download our template from the upload screen. There is a template for Standard Units and, in buildings with business units, a separate template for Business Units.

How to Import Tenants

1. Log in to the ButterflyMX OS
2. Navigate to the Tenants list screen and click Import tenants (under Add Tenant).
   • This opens the Import page on the Tenants tab.
3. If your building has business units, choose where these tenants live or work: Apartments or Offices and business units.
4. Click Browse files and select your file, or drag it into the upload area.
   • The upload starts automatically. You'll see "Reading your file" while we open the file, find your columns, and check units and contact details. This usually takes a few seconds.
5. Answer any quick questions (only if needed).
   • The system matches your columns automatically, even if they're named differently (for example "Apt", "Suite", or "Mobile").
   • If something is missing, you'll see "A couple of quick questions", such as Which column has the email address or phone number? Pick the column from your file, or choose My file doesn't have this.
   • You can also change any column we matched, or set it to Don't import.
   • Click Continue.
6. Review your import.
   • At the top, you'll see how many tenants and units we found, and how many issues there are to review.
   • Each row shows a status:
     • ✓ Ready: the row will be imported.
     • Amber Needs attention: the tenant has no email or phone number. They can still be imported.
     • Red Needs fixing: something must be corrected before this row can be imported. The issue is shown right under the field, for example "Check this email" or "Add a last name".
   • Click any field to edit it directly in the table. Once fixed, the row turns Ready.
   • Use the search bar to find a tenant by name, unit, email, or phone, or switch on Show errors only.
   • If a column holds the wrong information, click its header to fill it from another column in your file or choose Don't import this column.
   • To leave rows out, select them and click Discard selected.
7. Click Import at the bottom of the screen.
   • If some rows still need fixing, the button shows how many are ready (for example Import 45 of 50). You can import the ready rows now and fix the others later.
8. If any tenants have no email or phone number, you'll see a Missing contact details pop-up. These tenants won't be able to receive intercom calls or use the ButterflyMX app. Click Continue anyway to import them, or Close to go back and add their details.
9. On the One final check pop-up, review how many tenants will be added or updated, then click Import [number] tenants.
   • Tenants who are already in the building are updated, not duplicated.
   • Any rows that still need attention stay on the review screen so you can fix and import them later.
10. You'll see "Importing your tenants". You can leave this page at this point; the import keeps running in the background.
    • The Tenants list shows an "Importing your tenants…" banner and refreshes automatically when the import is done.

How to Import Units

Use the Units import to set up the units in your building before you add tenants. You can also skip this step: any new units in a tenant import are created automatically, as long as the file includes a floor.

1. Log in to the ButterflyMX OS.
2. Navigate to the Units list screen and click Import units (next to Add Unit).
   • You can also open the Import page and select the Units tab.
3. If your building has business units, choose whether these units are Apartments or Offices and business units.
4. Click Browse files and select your file.
   • Include the unit number and floor for each unit. You can also include the company name (for business units) and the in-unit phone number.
5. Answer any quick questions about your columns, then click Continue.
6. Review your units.
   • Units that are already in the building are marked "Already in this building, will be skipped". Existing units are never changed.
   • Fix any rows marked Needs fixing, such as a missing floor ("Required").
   • Use the search bar to find a unit by number, floor, or phone.
7. Click Import, then click Import [number] units on the confirmation pop-up.
8. You'll see "Importing your units". You can leave this page while the import runs.

Rows to Review and Import History

Rows that need your review

If some rows weren't imported, you'll see a banner at the top of the Tenants list (or Units list), for example "3 rows from your last import need your review".

• Click Review to open those rows, fix them, and import them.
• Click Discard if you don't want to import them.

Import history

You can see every list uploaded for your building under Import history. Click Import history on the upload screen to open it.

• The history shows the date, file, who uploaded it, its status, and how many tenants (or units) were imported.
• Statuses include Reading file, Waiting for your answers, Ready for review, Importing, Imported, and Couldn't read file.
• If an import finished but some rows still need attention, you'll see "Imported, [number] rows to review" and a Review button.
• If you uploaded a file but didn't finish importing it, click Open to pick up where you left off.
• Imports you completed with the previous CSV import also appear here.

What Happens After Import

Once the import is complete:

• All imported tenants appear in your Tenants list in the ButterflyMX OS.
• New tenants with an email address receive an invitation to set up their account and download the ButterflyMX app.
• Tenants can immediately use the app to open doors, manage visitor passes, and view call history.
• Existing tenants are updated with the names, phone numbers, and move-out dates in your file, and no duplicates are created. An email address already on file is never replaced.
• Tenants without an email or phone number are added to the building, but they can't receive intercom calls or use the app until you add their contact details.
• You can edit individual tenant information as needed from the Tenants page.

Troubleshooting

We Couldn't Read That File

If your file can't be read, you'll see a message explaining why:

• File is too big: Files can be up to 20 MB.
• More than 10,000 rows: Split the file into smaller files and upload them one at a time.
• Too many columns: Remove the columns you don't need and try again.
• No tenants found: Check that the file has a header row and at least one tenant.
• Unsupported format: Save your file as CSV, Excel, or PDF. If the file still can't be read, start from our template.

Common Issues on the Review Screen

• "Matches Apt 100, Office 100, use the full unit number": The unit number in your file matches more than one unit. Enter the full unit number as it appears in the ButterflyMX OS.
• "Required" under Floor: The unit isn't in the ButterflyMX system yet, so we need its floor to create it.
• "Check this email" or "Check this number": The email or phone number isn't in a valid format. Phone numbers can include spaces, dashes, or brackets.
• "Same email as row [number]" or "Same phone as row [number]": Two rows share the same contact details. If they are the same person, discard one row. If two different people share an email, add a phone number for the second person; they'll be imported separately and matched by phone.
• "Email already in use": That email belongs to another ButterflyMX account. Check the email with the tenant.
• "Already in this unit": This tenant is already in that unit.
• "Use 4 or 6 digits" or "Too easy to guess": PINs must be 4 or 6 digits and can't be simple sequences.

Some Tenants Imported, Others Didn't

The import adds every row that's ready and keeps the rest for you to review. Open them from the banner on the Tenants list or from Import history, fix the issues, and click Import. You can also add the remaining tenants manually through the standard Add Tenant flow.

Tenants Not Receiving App Invitations

If tenants aren't receiving their app invitations:

• Reminder that we do not send invitations until 8am local time.
• Tenants imported without an email address don't receive an invitation. Add their email from the Tenants page.
• Verify the email addresses in your file are correct.
• Ask tenants to check their spam/junk folders.
• Resend invitations individually from the Tenants page by clicking the three dots next to the tenant's name and selecting "Resend Invitation".

Don't See the Import Tenants Button

If you don't see the Import tenants or Import units option:

• Confirm you have Property Admin or Community Admin permissions.
• Try logging out and back in to refresh your permissions.

Best Practices

• Test with a small batch first: Import 5-10 tenants initially to see how your file is read.
• Double-check unit numbers: Use the full unit number as it appears in the ButterflyMX OS, especially if your building has similar unit numbers (for example "Apt 100" and "Office 100").
• Include an email or phone for every tenant: Tenants need an email to use the ButterflyMX app and a phone number to receive intercom calls.
• Import units first in a new building: Set up your units with their floors, then import your tenants.
• Notify tenants in advance: Let residents know they'll be receiving app invitations.
• Keep a backup: Save your original file in case you need to reference it later.
• Verify after import: Spot-check a few tenant profiles to ensure information imported correctly.