Context:

Property admins and Community Admins can now save time by importing multiple tenants at once using the new bulk import feature in the ButterflyMX OS. This feature allows you to upload a CSV file with tenant information instead of adding residents one by one. If you're interested in using this feature as a Property Admin or Community Admin, please reach out to your Client Success Manager or Support to enable this feature for your building.

Before you start

• Prepare a CSV file.
  • Required columns are: first name, last name, e-mail and unit code.
  • If there are no units present in the building, floor number is required as well.
  • Download the import template for Standard Units or Business Units
    • The respective templates can be found attached at the bottom of this article

How to Import Tenants

1. Log in to the ButterflyMX OS
2. Navigate to Imports in the left sidebar

   • The "Imports" item in the left navigation goes to a page with three tabs, defaulted to "Import history".

     

3. Click on "New import" on the page
4. Choose an import type - Standard Units or Business Units
   • Download the import template for Standard Units.
   • Download the import template for Business Units.
5. Click Browse files and select your prepared CSV file
6. Review the preview of your import to ensure data appears correctly
   • The system will try to auto-detect the data type in that column and select it for you automatically.
     • If it didn't find a match, the dropdown will say "Assign".

   • You can remove unwanted rows or columns before importing.

     

7. Once everything is mapped, click Next
8. Click Import to begin the import process
9. Click Import again on the pop-up confirmation that appears

10. You will see a pop-up that the tenant import is being processed. For larger imports, the process can take up to 10 minutes. You can close the browser window at this point if you choose.

    

11. After a few minutes, you will receive an email notification that the import is finished.
    1. The email template for import complete includes both successful and failed record counts.

    2. A link appears only if there's work to be done

       

    3. The email link takes you to a review screen showing only the file in context, without collapsible headers.

       

       • There is an Import button for the full screen

Review Required tab

1. The "Review required" tab shows all files with pending records, with each file in its own collapsible section. If there's only one file, it will be expanded by default.
   • Expanding a file shows all records in that file that require review.
2. The Status column shows any error messages.
   • If you have many columns, there will be a scrollbar. The Status column will stay pinned in view.

3. Once you edit a record, its status changes to "Ready for import".

   

4. Once you've reviewed all records for a file, you can Submit them in a batch.

Import history tab

You can review the status of the import(s) in Import history

1. In the history list, the file name link lets you download the file.
2. Successfully imported users will be counted under the "Imported users" column
3. If the import finished but there's work to do, you'll see "Review". Tenants with errors with importing can also be reviewed under "Review required"
   • The red dot indicates a past import needs your attention.

4. If you previously uploaded a file without submitting it for import, you'll see an "Assign" button to pick up where you left off.

   

What Happens After Import

Once the import is complete:

• All tenants will appear in your Tenants list in the ButterflyMX OS
• Tenants will receive email invitations to download the ButterflyMX app
• Tenants can immediately use the app to open doors, manage visitor passes, and view call history
• You can edit individual tenant information as needed from the Tenants page

Troubleshooting

Import Failed or Shows Errors

If your import fails, check for these common issues:

• Unit numbers don't match: Verify that unit numbers in your CSV exactly match the units created in the ButterflyMX OS
• Invalid email format: Ensure all email addresses are properly formatted (name@domain.com)
• Duplicate entries: Check that you're not importing tenants who already exist in the system
• Missing required fields: All columns (First Name, Last Name, Email, Phone, Unit) must have values
• File format issue: Confirm your file is saved as .csv, not .xlsx or other formats

Some Tenants Imported, Others Didn't

The import process will skip rows with errors and import valid entries. Review the error message to identify which rows failed and why. You can:

• Create a new CSV with only the failed entries after correcting the errors
• Manually add the remaining tenants through the standard Add Resident 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
• Verify the email addresses in your CSV are correct
• Ask tenants to check their spam/junk folders
• Resend invitations individually from the Residents 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 option:

• Confirm you have Property Admin or Community Admin permissions
• Contact your ButterflyMX representative to enable the import feature flag for your property
• Try logging out and back in to refresh your permissions

Best Practices

• 📊 Test with a small batch first: Import 5-10 tenants initially to ensure your CSV is formatted correctly
• 🔍 Double-check unit numbers: Incorrect unit assignments are the most common import error
• 📧 Notify tenants in advance: Let residents know they'll be receiving app invitations
• 💾 Keep a backup: Save your original CSV file in case you need to reference it later
• ✅ Verify after import: Spot-check a few tenant profiles to ensure information imported correctly