The importer does two jobs, and one file can do both.
It adds new records. Import a spreadsheet to add many units and their owners at once, instead of adding them one at a time.
It updates the records you already have. Import a file that lists units already in PayHOA to change unit addresses, owner names, phone numbers and mailing addresses in bulk, fill in missing emails, set custom field values, and add tags or co-owners. See Update existing units and owners with the importer.
PayHOA's AI Assistant reads your file, matches each column to a PayHOA field, checks every row against the units and people you already have, and shows you which rows are new and which are updates before anything is saved. You can run the importer as often as you like.
Use something else for these:
One or two units or owners. See Add a unit and Add an owner. To change one or two, see Edit, delete or combine units and Edit a person's contact details.
A sale. The importer adds owners to a unit. It never removes the owners who are already there. See Change ownership when a unit is sold.
Tenants and other contacts. Everyone in the file is imported as an owner. Add tenants on the unit page. See Tenants, renters and other contacts.
Replacing an email an owner already has. The importer fills in an email for an owner who has none. It never replaces one. See Edit a person's contact details.
Removing anything, or renaming a unit. An import adds and changes; it never removes an owner, a tag or a value, and it never changes a unit's title. See What you can't update this way.
Invoices and payment history. The importer brings in one starting balance per unit, not individual invoices or payments. See Starting balances and backdated invoices and Import payments from a file.
Vendors. See Import vendors.
Before you start
Who can import | Admins, and anyone with Write permission on Units. See Give board members and staff access. |
Where it is | Click Units in the left menu, click Add units, then click the Import owners and units tab. |
File types | CSV, XLS, XLSX or PDF. |
File size | Up to 10 MB. There is no limit on the number of rows. |
Excel files | Only the sheet that was open when the file was last saved is read. Put everything on one sheet. |
Owners per unit | Up to 50. |
Sample file | On the upload page, click Download the sample file. It's a CSV named payhoa-sample-units.csv with 10 example units. |
Does AI read my file? | Yes. PayHOA's AI Assistant reads the column headings and the rows to match columns, split combined names and addresses, and find the units and owners you already have. It suggests; you check. Nothing is saved until you click Start import. |
What gets created | New units (with their address), new owners, tags, custom fields and starting balances. |
What gets updated | Units and owners you already have. A filled cell can change a value; a blank cell never clears one. See Update existing units and owners with the importer. |
What gets skipped | Rows with a problem (shown with a warning triangle), and columns you set to Skip column (do not import). |
Emails | Nothing is sent to owners. Importing doesn't invite anyone to the portal, and starting balance invoices aren't emailed. PayHOA emails you, the person who ran the import, a summary when it finishes. |
Billing | Nothing is charged to owners. Your PayHOA subscription is based on your number of units, so adding units can change it. See Subscription and billing. |
Undo | There is no undo. Before you click Start import you can throw the import away and nothing is kept. After that, fix mistakes by editing, deleting or importing again. See After the import. |
Your file
Start from the sample file, or use your own spreadsheet. Your column headings don't have to match the sample. PayHOA matches columns by their heading and their contents, and you can change any match before you import.
Columns PayHOA understands
These are the fields you can match a column to on the mapping page, in the order the list shows them. Only Unit Number is ever required, and only for some files (see The rules).
Field on the mapping page | Required? | What to put in it | Example | If it's blank or wrong |
Unit Number | Yes, when the file is unit data | The unit's title in PayHOA: a lot number, unit number or short name. Up to 255 characters. | Lot 12 | Blank with a street address: the street address becomes the title. Blank with no address: in a unit data file the row isn't imported; in an owner file the row only adds or updates the owner. |
Unit Description | No | Any text, up to 255 characters. | Corner lot, 3 bed | Left as it is. |
Full Address (combined) | No | A whole address in one cell. PayHOA splits it into street, city, state and ZIP. | 101 Maple Ridge Dr, Lexington, KY 40507 | An address it can't split leaves the row without an address. |
Street Number and Street Name | No | Use both when your file keeps the house number and street in separate columns. PayHOA joins them into Unit Address Line 1. | 101 and Maple Ridge Dr | |
Unit Address Line 1 | For a new unit | Street address. Up to 255 characters. | 101 Maple Ridge Dr | A new unit without it isn't imported: Unit Address Line 1 is required to create a new unit. |
Unit Address Line 2 | No | Apartment, suite or building. | Apt 4B | |
Unit City | For a new unit | City name. | Lexington | Unit City is required to create a new unit. |
Unit State | No | Two-letter code or full name. US states and territories and Canadian provinces are recognized. PayHOA saves the full name. | KY | Unit State "ZZ" is not a recognized state. Use the two-letter code or the full state name. |
Unit ZIP Code | For a new unit | 5 digits, or 5 digits plus a 4-digit extension. PayHOA puts back leading zeros a spreadsheet dropped (2134 becomes 02134). | 40507 | Blank on a new unit: Unit ZIP Code is required to create a new unit. Wrong shape: … is not a valid ZIP code. Use 5 digits, or 5 digits plus a 4-digit extension. |
Owners (combined data) | No | Several owners in one cell. PayHOA splits them into Owner 1, Owner 2 and so on. | John Smith (john@example.com); Jane Smith | |
Owner Name (Full) | See the rules | First and last name in one cell. The last word becomes the last name. | John Smith | A new owner with only one word isn't imported. |
Owner First Name, Owner Last Name | See the rules | Up to 255 characters each. A new owner needs both. | John, Smith | Owner first and last name are required to create a new owner. |
Owner Email | No | One email address, up to 127 characters. Becomes the owner's login email. | Blank: the owner is added without an email. Wrong: Owner Email "john@" is not a valid email address. | |
Owner Phone, Owner Secondary Phone | No | Digits, spaces, and + ( ) . - x. Up to 63 characters. A trailing label such as (c) or cell is dropped. | (859) 555-0101 | … is not a valid phone number. |
Owner Auxiliary Email | No | Extra email addresses for the owner. Separate several with a semicolon. Up to 127 characters each. | … is not a valid email address. Separate several with a semicolon. | |
Move-In Date | No | The date the unit's current owners took ownership. One date per row. See date formats below. | 01/15/2024 | Blank on a new unit: today. Wrong: Move-In Date "02/31/2024" is not a valid date. Use a real calendar date from 1900 onward. |
Owner Full Mailing Address (combined) | No | A whole mailing address in one cell. PayHOA splits it. | PO Box 2210, Lexington, KY 40588 | |
Owner Mailing Address 1, Owner Mailing Address 2, Owner Mailing City, Owner Mailing State, Owner Mailing ZIP | No | Only for owners who get mail somewhere other than the unit. Same rules as the unit address. | 450 Lake Shore Ave, Apt 12B, Chicago, IL, 60611 | Blank: the owner has no separate mailing address. A bad state or ZIP stops the row. |
Unit Tag | No | One or more tags for the unit. Separate several with a semicolon. You can match more than one column to it. | Corner Lot; Pool Access | Blank: no tags are added. |
Owner Tag | No | One or more tags for the first owner on the row. Separate several with a semicolon. You can match more than one column to it. | Board Member | Blank: no tags are added. |
Opening Balance | No | What the unit owed, or was owed, when you moved to PayHOA. A positive number is money owed. A negative number, or a number in parentheses, is a credit. Dollar signs and commas are fine. | 125.50 or (50.00) | Blank or 0: no balance. Wrong: Opening Balance "abc" is not a valid amount. |
Balance As-Of Date | No | The date of the starting balance. | 01/01/2026 | Blank: today. |
A field under Unit Custom Fields | No | A value for one of your unit custom fields. Up to 255 characters. | P-14 | Blank: the unit's value is left as it is. |
A field under Owner Custom Fields | No | A value for one of your owner custom fields, saved on the first owner on the row. Up to 255 characters. | Gold | Blank: the owner's value is left as it is. |
Dates. These all work: 2024-01-15, 01/15/2024, 1/15/24, 01-15-2024, Jan 15, 2024 and 15 Jan 2024. A date like 03/04/2024 is read month first, as March 4. The year must be 1900 or later.
Amounts. $1,275.50 is read as 1275.50 and (200.00) as -200.00.
Placeholders. A cell that holds only dashes, such as ---, counts as blank.
More than one owner. For a second owner, repeat the owner columns with a number in the heading, as the sample file does: Owner 2 First Name, Owner 2 Last Name, Owner 2 Phone, Owner 2 Email. Headings such as Second Owner Email or Co-Owner Name work too. On the mapping page these show as Owner 2 First Name and so on.
What there is no column for: tenants and other contacts, unit photos you upload yourself, notes, permissions, the Alliance lockbox ID, invoices and payments.
The rules
One row per unit. List each unit once, with its owners side by side (Owner 1, Owner 2). If your file has one row per owner instead, that works too: PayHOA merges rows with the same unit into one row with several owners. On the review page, a merged row shows 2 owners (or more) under the unit.
What must be in the file depends on what the file is. After it reads your file, PayHOA tells you what kind of data it thinks you're importing, and you confirm it.
Unit data (units with addresses, usually with their owners): a column must be matched to Unit Number, and every row needs a unit number or a street address.
Owner data, balances or custom field values: each row needs at least one way to find the unit or the person: Unit Number, Unit Address Line 1, Owner Email or an owner name.
How PayHOA finds a unit you already have. It compares the row's Unit Number with your unit titles.
Capitals and extra spaces don't matter.
A leading Unit, Apt, Apartment, Lot, Suite, Ste or # is ignored, so Lot 12 in the file matches a unit titled 12.
When two of your units could match, the street address on the row decides.
For close but not identical titles, such as 104 and MM-104 at the same address, the AI Assistant can suggest a match. It only keeps matches it's confident about.
No match: the row creates a new unit, which needs Unit Address Line 1, Unit City and Unit ZIP Code.
How PayHOA finds an owner you already have. In this order:
The same Owner Email as a person in your association.
Exactly the same first and last name as an owner already on that unit.
The same phone number as exactly one owner already on that unit, when the emails don't conflict.
Otherwise the AI Assistant may suggest a match for a near miss. It doesn't match two people who have different emails.
No match: the row adds a new owner. A new owner needs a first and a last name. An email is optional.
What changes on a unit you already have.
Address and description: a filled cell replaces what PayHOA has.
Move-In Date: a different date replaces the current one.
Owners: owners in the file who aren't on the unit are added. Owners already on the unit stay, even if they aren't in the file.
Tags: added. Existing tags are never removed.
Custom fields: a filled cell replaces the value.
Opening Balance: added only if the unit has no starting balance yet. A unit can have one. If it already has one, the balance in the file is ignored.
What changes on an owner you already have.
Name, phone numbers and mailing address: a filled cell replaces what PayHOA has. You can keep the old value for any cell on the review page.
Email: never replaced. If the first owner on the row had no email in PayHOA, the email in the file is filled in. To change an email an owner already has, or to give a co-owner an email, edit the person.
Auxiliary emails, tags and custom fields: added or updated.
Blank cells: never clear anything.
For every field, including second owners and the cases where a value is only filled in when blank, see What an update changes, and what it leaves alone.
Tags. A tag in the file that matches one you already use (capitals don't matter) is reused, with the spelling you already have. Anything else becomes a new tag. Unit tags and owner tags are separate lists, so a unit tag typed in an owner tags column counts as new. Owner tags and owner custom fields go on the first owner on the row only. A row with no owner name or email has no first owner, so its owner tags aren't saved, even though the review page shows them as chips.
The same person on several rows. Rows with the same Owner Email are one person who owns several units. Two different people can't share one Owner Email; put the second address in Owner Auxiliary Email, or leave the second person's email blank.
Addresses aren't verified. PayHOA checks that a state and a ZIP code are well formed. It doesn't check that the address exists or that mail can be delivered there.
Unit photos. There is no photo column. If Include Streetview Photo on Units Import is on in your preferences, PayHOA adds a Google Street View photo to each new unit that has an address, within a few seconds of the import. Existing units aren't changed. The photo is of wherever Google places the address: for example, several street addresses that don't exist, in a real ZIP code, can all get the same photo of a street in that area. Check the photos on new units. If the address can't be found on the map at all, the unit is still imported, without a photo. See Preferences.
Update existing units and owners with the importer
Importing a file that lists units you already have updates them. PayHOA recognizes each row, shows it as Updating when it will replace a value or add an owner, and marks each value it will replace so you can check it first. An import adds and changes. It never removes anything.
When to use it
You have a current owner list with new phone numbers and mailing addresses for many owners.
You want to add a tag such as Phase 2 to forty units, or give every unit a value in a custom field such as a parking space.
Several units gained a co-owner, or many owners still have no email in PayHOA.
If you only want to add details you didn't have the first time, these shorter articles each cover one task:
For one or two changes, edit the unit or the person instead. See Edit, delete or combine units and Edit a person's contact details.
Steps
Export what PayHOA has now. There are two exports. Use the one that fits the change.
Units (addresses, tags, custom fields): click Units in the left menu, then Export CSV at the top of the page. You get a file named unit-list-download_ followed by the date, such as unit-list-download_2026-11-11.csv, with one row per unit. For example, it can have Unit Title, Unit Address, Current Balance, Owner Names, Unit Tags, a column for each request form, and Violations. The columns follow what's turned on under Columns, a button that only shows in the list view of the Units page. If you search or filter the list first, only the units shown are in the file. See Units overview.
Owners (names, phone numbers, mailing addresses, emails): the Units export has no phone numbers or mailing addresses, so use a custom report. Click Reports. At the bottom of the Individual reports tab, under Custom reports, click Build report. In Step 1, leave everything unticked to get every unit, or tick the units you want. In Step 2, under Unit fields, tick Unit Title. Under Owner fields, tick First Name, Last Name, Email and the fields you want to change: Phone, Secondary Phone, Address Line 1, Address Line 2, City, State, Zip. Click Show results, then Export and Export CSV. The file is named custom-report_ followed by the date. You don't need to save the report as a template. See Custom reports.
Save a second copy of the export and leave it alone. It's your record of how things were. There is no undo.
Get the working copy ready. Keep the unit column. Delete the columns you aren't changing, and always delete balance columns. The headings the exports use are recognized as they are, so you only type headings for columns you add. The table under these steps says what to do with each column.
Change only the cells that should change. A blank cell never clears anything, so you can also empty the cells you don't want touched.
Leave the unit column exactly as it was exported. PayHOA finds each unit by its title. For an owner whose name you're correcting, leave their email in the row, so PayHOA can still tell who they are.
Upload the file. Click Units, Add units, then the Import owners and units tab, and drop the file in the box. See 1. Open the importer. Even a file of a few rows can take half a minute to read.
Answer Confirm your import. Read the sentence that starts It looks like you're importing….
A file with unit addresses or unit tags is usually described as unit and property data. Click Yes, that's right, then Continue.
A custom report file with only owner columns is usually described as owner and member data. That's fine when you're only changing names, phone numbers and mailing addresses: the mapping page shows the same statuses and marks either way. Click Yes, that's right, then Continue.
A file with only a unit column, a tags column and custom field columns can be described as custom field data.
If you're adding unit tags or filling in missing emails and the sentence doesn't say unit and property data, click No, let me clarify, type This is unit data. Update the units and owners we already have. and click Continue. When the clarification works, the window comes back with a green line, Updated using your clarification, and a new sentence that says unit and property data. Then click Yes, that's right and Continue.
Check the columns. On the mapping page, each column you kept should sit under the right field. Columns from the custom report sit under Owner 1 and Owner 2 fields, such as Owner 1 Phone and Owner 1 Mailing Address 1. Set anything you don't mean to import to Skip column (do not import). See 10. Edit mapped units and owners data: match your columns.
Check the Status column. Every row for a unit you already have should read Updating or No changes. The line above the table sums it up, as in 6 records will be imported • 2 updating • 4 no changes. PayHOA didn't recognize a unit when its row shows one of these:
New, when the row has a unit address. Importing would add a second unit.
A warning triangle, when the row has no unit address, as in a file from the custom report. The row is counted under Invalid, and a yellow box, 1 new unit needs an address, names the unit. The row wouldn't be imported.
Either way, don't import. Correct the unit column in your file and upload it again.
Check what will be replaced. Click the Updating filter. Each value that replaces one in PayHOA has an orange i. Point to it to see Previous value: and the value PayHOA has now. To keep that value, click the x beside it. Its tooltip reads Keep original value on an owner's value and Don't apply this update on a unit's value. The cell then shows PayHOA's value with a round arrow, and if that was the row's only change, the row moves to No changes. Click the round arrow (Undo) to put your change back. See 11. Edit mapped units and owners data: check the rows.
Click Start import. If the Opening Balances window opens and you didn't mean to import balances, a column is matched to Opening Balance. Click Cancel, set that column to Skip column (do not import), then click Start import again.
Check the result. On Import complete, the cards count what was saved: Existing units updated, Existing owners updated, Owners added and Tags created. They can show more than the mapping page promised, because rows that read No changes are saved too. For example, a file the mapping page sums up as 6 records will be imported • 2 updating • 4 no changes can finish with Existing unit updated 1, Owner added 1, Existing owners updated 2 and Tag created 1. An email filled in for an owner who had none isn't counted on any card. There should be no New units created card unless you meant to add units, and no Owners added card unless you meant to add owners. Then open a few units and compare them with your file. See 15. Import complete.
Clean up the Units export before you import it. Uploaded exactly as exported, the file is read without errors: every row can read No changes, and the line above the table can say 6 records match your existing data. No changes will be made. Don't trust that line. The balance column can be matched to Opening Balance; it shows no change only for units that owe nothing or already have a starting balance. And an automatic tag in the tags column shows as a new tag to be created.
Column in the Units export | What to do with it |
Unit Title | Keep it, and don't change the values. PayHOA reads it as Unit Number; check that on the mapping page. |
Unit Address | You can leave it. It holds the whole address in one cell, on two lines, and PayHOA splits it into Unit Address Line 1, Unit City, Unit State and Unit ZIP Code. Addresses you haven't changed normally show no mark. To change addresses, replace it with four columns headed Unit Address, Unit City, Unit State and Unit Zip, and fill them in for the units that change. A two-letter state such as KY matches a unit saved as Kentucky. |
Owner Names, Owner Emails | Delete them unless you're adding owners. Owner Names holds all of a unit's owners in one cell; PayHOA splits it into Owner 1, Owner 2 and so on, and usually finds the existing owners. A name it splits differently from the name in PayHOA would be added as another owner. To change owners' details, start from the custom report instead. |
Current Balance, Past Due Balance, Recurring Charges and the autopay columns | Delete them. Current Balance can be matched to Opening Balance, which would give a starting balance to every unit that owes money and doesn't have a starting balance yet. |
Violations and the request form columns | Delete them. They're usually left unmatched, with an empty list above them, so they wouldn't be imported, but they make the page harder to check. |
Unit Tags, Owner Tags | Delete them, or empty the cells and type only the tags you want to add. Two reasons. The export separates tags with commas and the importer only separates them at semicolons, so Corner Lot, Pool Access left as it is becomes one new tag. And the export includes PayHOA's automatic tags, such as Missing Email Address; left in, each becomes a real tag on the unit. |
Custom Fields | Delete it. It holds all of a unit's fields in one cell. Add one column per field instead, headed with the field's name. |
The custom report's file can be imported as it is. It has one row per unit, and it heads the owner columns First Owner First Name, First Owner Phone, First Owner Address Line 1, Second Owner First Name and so on. PayHOA reads First Owner columns as Owner 1 and Second Owner columns as Owner 2, and the address columns as the owner's mailing address. PayHOA usually matches every column of an untouched custom report file, and every row then reads No changes.
An owner with no email has an empty email cell. Leave it empty, or type the real email, for the first owner only. See What an update changes, and what it leaves alone.
States are spelled out, such as Tennessee. Leave them.
The columns aren't always in owner order: Second Owner Secondary Phone can sit next to First Owner Secondary Phone. Read the heading before you type in a column.
The file has no unit address. A row whose unit PayHOA doesn't recognize therefore can't become a new unit; it shows a warning triangle instead.
Headings to use for columns you add. These are the headings in PayHOA's sample file. The headings the two exports use, such as Unit Title, Unit Tags and First Owner Phone, work too.
For | Headings |
The unit | Unit Number |
The unit's address | Unit Address, Unit City, Unit State, Unit Zip |
The first owner | Owner 1 First Name, Owner 1 Last Name, Owner 1 Email, Owner 1 Phone |
A co-owner | Owner 2 First Name, Owner 2 Last Name, Owner 2 Email, Owner 2 Phone |
The first owner's mailing address | Mailing Address Line 1, Mailing Address Line 2, Mailing City, Mailing State, Mailing Zip |
Tags | Unit Tags, Owner Tags. Separate several tags with a semicolon. |
A custom field | The field's name, exactly as it is in PayHOA. Check on the mapping page that the column sits under that field. |
How PayHOA decides a row is an update
A row is an update when PayHOA finds its unit, its owner, or both. It looks for the unit first.
The unit. In this order:
Title. The row's Unit Number is compared with your unit titles. Capitals and extra spaces don't matter, and a leading Unit, Apt, Apartment, Lot, Suite, Ste or # is ignored. If the row has no unit number, its Unit Address Line 1 is compared with the titles instead.
Street address. If several of your units have that title, the row's street address picks the one at that address. If one unit has the title but the row's street address belongs to a different unit of yours, PayHOA doesn't rely on the title and goes to step 3.
The AI Assistant. For a row that is close to one of your units but not the same, such as 104 for a unit titled MM-104, the AI Assistant suggests a match. PayHOA keeps it only when the AI Assistant is at least 80% confident.
No match. The row is New and adds a unit, even when PayHOA found the owner.
The first owner on the row. In this order:
Email. The same Owner Email as a person in your association.
Name. Exactly the same first and last name as an owner already on that unit. Capitals and extra spaces don't matter.
Phone. A phone number that only one person in your association has, when that person owns that unit and the emails don't conflict.
The AI Assistant. A near miss in the name, kept only when the emails are the same or the person already owns that unit. Two people with different emails are never matched.
Second and later owners on the row are found by their email if the row gives one. If it doesn't, they're found by exactly the same name on that unit.
A row that matches. Your file has Lot 12, John Smith, john.smith@example.com and a new phone number. PayHOA has a unit titled Lot 12 owned by John Smith with that email. The row reads Updating and the phone number has an orange i.
Rows added as new by mistake.
A changed unit title. You retype Lot 12 as Lot 12-A, or your spreadsheet program saves 0012 as 12. No unit has that title. Unless the AI Assistant is confident it's the same unit, PayHOA treats the row as a new unit. For example, a row retitled from Lot 12 to Lot 12-A isn't recognized, even with the same street address and the same owners as the unit you already have.
If the row has a unit address, it reads New and importing it adds a second unit.
If it has no unit address, it gets a warning triangle and isn't imported: This row won't be imported — Unit Address Line 1 is required to create a new unit; Unit City is required to create a new unit; Unit ZIP Code is required to create a new unit. A yellow box above the table, 1 new unit needs an address, lists the unit.
To rename a unit, edit it. An import can't rename units, and there's no bulk rename: unit titles are changed one unit at a time. See Edit a unit.
A changed owner name with no email. PayHOA has Jon Smith with no email, and your row says John Smith with no email or phone. The names aren't exactly the same. Unless the AI Assistant is confident they're the same person, John Smith is added as a second owner, and the name has a list icon on the review page. Put the owner's email in the row, or correct the name on the person's page.
A row shows as Updating when it replaces a value, adds an owner PayHOA didn't find on the unit, or gives a starting balance to a unit that has none. Otherwise it shows as No changes. No changes doesn't mean nothing is saved: see the first Important note under the next table.
What an update changes, and what it leaves alone
In your file | What happens on a unit or owner you already have |
Unit Number | Never changed. It's only used to find the unit. |
Unit Description | Replaced with the file's value. |
Unit address: Unit Address Line 1, Unit Address Line 2, Unit City, Unit State, Unit ZIP Code | Replaced, one field at a time. A unit with no address gets one. |
Move-In Date | Replaced, when the row also names an owner. |
The first owner's first name, last name, Owner Phone, Owner Secondary Phone and mailing address | Replaced when the row's Unit Number is the unit's exact title. If PayHOA matched the unit loosely (Lot 12 for a unit titled 12, or through the AI Assistant), these may be filled in only when blank, even though the review page shows the orange mark. |
The first owner's Owner Email | Filled in only when the owner has no email. Never replaced. Only in a file PayHOA reads as unit data. |
Owner Auxiliary Email | Added to. Addresses the owner doesn't have yet are added. None are removed. |
A second or later owner PayHOA finds by email | Details are filled in only when blank. Their email is never changed. |
A second or later owner with no email in the row, found by name | Phone numbers and mailing address are replaced, on the same condition as the first owner's. |
A second or later owner who has no email in PayHOA, given an email in the row | Added as another person with the same name and the new email. The owner already on the unit is left as they were, still without an email. |
An owner who isn't on the unit yet | Added to the unit. If the email belongs to a person already in your association, that person becomes an owner of the unit. Otherwise a new person is created, which needs a first and a last name. The owners already on the unit stay, even if they aren't in the file. |
Unit Tag | Added to. No tag is removed. Only in a file PayHOA reads as unit data. |
Owner Tag | Added to, on the first owner on the row. |
A unit custom field | Replaced with the file's value. |
An owner custom field | Replaced, on the first owner on the row. |
Opening Balance | Added only when the unit has no starting balance. If it has one, the amount in the file is ignored and the rest of the row is still imported. |
An archived owner the row matches | Restored, unless you click the round arrow on the review page to leave them archived. |
Anything with no column: tenants and other contacts, notes, photos, permissions, invoices, payments | Never changed. |
Blank cells never clear anything. A blank cell leaves the value in PayHOA as it is. There's no way to empty a field with an import.
Important: The orange i marks only values that replace a different value, on the unit and on the first owner. Three kinds of change are saved without a mark, and a row that makes only these reads No changes: a detail filled in where PayHOA had none (such as an email for an owner who has none), a tag, and a custom field value. Changes to a second or later owner aren't marked either. A tag does show in its own column, as a blue chip if it's new and a green one if you already use it, but the row's status doesn't change. When every row is like this, the line above the table reads 6 records match your existing data. No changes will be made. Don't rely on it. Start import saves them all. For example, a row that reads No changes can create a new tag, put it on the unit, and fill in the first owner's missing email.
Important: To fill in a missing email, the owner must be the first owner on the row. If you give a second owner an email PayHOA doesn't know, they're added as another person on the unit, even when the name matches. The mapping page gives no sign of this: the row can still read No changes, and the second owner's cells have no mark at all. After the import the unit has two owners with that name: the original, still without an email, and a new person with the email from the file. Import complete counts the new person under Owner added. For a co-owner, add the email on the person's page instead. See Edit a person's contact details. If an import has already added the extra person, take them off the unit. See Add or remove owners on a unit.
What you can't update this way
An email an owner already has. An import fills in an email only when the owner has none. It never replaces one, because that email is the owner's login. The mapping page doesn't warn you. A row with a different email for an owner who already has one can read No changes, and the new email can carry the green i (Mapped to existing entity), as if it had matched. After the import the owner still has the old email. Edit the person instead. See Edit a person's contact details.
Who owns a unit after a sale. Owners are added, never removed. Importing the buyer puts them next to the seller. See Change ownership when a unit is sold. To take one owner off a unit, see Add or remove owners on a unit.
A unit's title. A changed title is treated as a different unit. See Edit, delete or combine units.
A starting balance a unit already has. The amount in the file is ignored. Remove the starting balance on the unit and enter the right one. See Starting balances and backdated invoices.
Removing a tag, or emptying a field. See Tags, notes and custom fields.
Tenants and other contacts, notes, photos and permissions. There is no column for them. See Tenants, renters and other contacts and The unit page.
Duplicates. An import can't merge two units or two people. See Edit, delete or combine units and Archive, restore or lock a person.
Check before you import
Important: New means "not recognized". In an update file, look at the New and Invalid filters before anything else. A New row for a unit you already have would add a second unit. An Invalid row with Unit Address Line 1 is required to create a new unit is a unit PayHOA didn't recognize in a file with no unit address. A list icon on an owner's name means a second owner would be added. One case shows no icon: a co-owner who has no email in PayHOA and is given one in the file is added as another person. Take that email out of the file. Fix the file and upload it again. The filters only show the kinds of row your file has, so no New filter means no units would be added.
Important: Changing a column's match on the mapping page doesn't re-check which rows are new and which are updates. PayHOA looks for your units and owners once, when it reads the file. If the unit number, an owner's name or an email ended up under the wrong field, fix the headings in your file and upload it again.
Warning: Check that no balance column is being imported. A column matched to Opening Balance gives a starting balance to every unit in the file that doesn't have one yet. Set it to Skip column (do not import) unless that is what you want.
Warning: There is no undo. Keep the untouched copy of your export. To put replaced values back, build a file from that copy and import it, or edit the units and people by hand. Values an import filled in where PayHOA had none, and owners, tags and units it added, have to be removed by hand.
The import, screen by screen
The importer has three steps, shown at the top of the page: Upload, Mapping and Complete. Several windows can open along the way. They're listed here in the order you meet them.
1. Open the importer
What you see. The Units page lists your units. The Add units button is near the top of the page. It opens a page with three tabs: Add single unit, Add single owner and Import owners and units.
What to do.
Click Units in the left menu.
Click Add units.
Click the Import owners and units tab.
What happens next. The Import Units & Owners page opens. If you started an import earlier and didn't finish it, a window asks whether to resume it (see screen 3).
2. Import Units & Owners (the Upload step)
What you see.
A back arrow at the top left. It returns to Units.
The step bar: Upload, Mapping, Complete.
The heading Import Units & Owners and the line Upload your file and AI Assistant will automatically map your columns.
The Quick guide card, with an AI-powered mapping badge and three steps: Upload a CSV, Excel or PDF file (with Not sure how to lay it out? and the Download the sample file link), AI analyzes your import data (Review column mappings and be sure it all looks right.) and Finish the import.
The Upload your file box: Drag & drop your file here, or click to browse, a Browse files button, and the line CSV, XLS, XLSX or PDF, up to 10 MB.
The My file has headers checkbox. It starts checked.
What to do.
If you don't have a file yet, click Download the sample file, replace the example rows with your own, and save it.
Leave My file has headers checked if the first row of your file holds column names. Uncheck it if the first row is already a unit. PayHOA then names the columns Column 1, Column 2 and so on, and you match each one yourself.
Drag your file into the box, or click Browse files and pick it.
What happens next. The file uploads and a progress window opens (screen 4). If the file can't be used, a red message says why and you stay on this page. See If something goes wrong.
Leaving. Nothing is kept until a file has uploaded. Click the back arrow to return to Units.
Tip: A PDF works when it's a clean table, such as an owner list exported from another system. The AI Assistant has to read the table out of the page, so check the rows more carefully than you would for a spreadsheet. If you can get a CSV or Excel file instead, use that.
3. You have an import in progress
This window opens when you come back to the importer and an earlier file of yours was read but never imported.
What you see. The heading You have an import in progress and Would you like to pick up where you left off, or start a new import? Below it:
Import type: Units & Owners.
Records: the number of rows, such as 7 rows.
Current step: Mapping or Review.
Last updated: the date and time, such as Nov 11, 2026, 2:13 PM.
What to do.
Click Resume import to go back to the mapping page with your column matches as you left them.
Click Start fresh to throw the earlier import away. You see Previous import cleared. Ready for a new file! and the upload page is ready for a new file.
Good to know.
An unfinished import is saved for you only. Another admin doesn't see it.
It stays until you resume it or start fresh.
If the earlier file is still being read, this window doesn't open. The progress window opens instead (screen 4).
4. Reading your file
What you see. A small window with a sparkle icon and a line that changes as the work moves on, such as Reading your file…, Lining up your columns…, Matching owners…, Checking owner names and emails…, Still matching owners…, Matching units to your records… and Still matching units…. Under it is your file name. A progress bar shows which of four steps is running, with a percentage at its right end. From step 2 on, a second bar under it shows the count:
Step | What PayHOA is doing | Count shown |
Step 1 of 4 · Reading your file | Uploading the file, reading the rows and matching columns to fields. | None |
Step 2 of 4 · Matching owners | Looking for each owner among the people you already have. | Matched 50 of 200 owners |
Step 3 of 4 · Matching units | Looking for each unit among the units you already have. | Matched 50 of 200 units |
Step 4 of 4 · Checking rows | Checking every value: dates, emails, phones, ZIP codes, required fields. | Checked 50 of 200 rows |
What to do. Wait. Step 1 is the slow one, because the AI Assistant reads your columns first: even a file with 7 rows takes 30 to 45 seconds in all. The other steps are quick. A file with 1,500 rows can be ready in about a minute.
After about 15 seconds the window changes. This happens for small files too.
The file name is replaced by This is a big import, and we're on step 2 of 4. Feel free to keep working, and we'll let you know when it's ready. The step number is the one that's running.
A Continue in background button appears at the bottom, and an x appears in the corner. The x does the same as Continue in background.
Once the file has been read (from step 2 on), a Cancel import button appears next to Continue in background. During step 1 there is no Cancel import button.
Then choose one:
Keep waiting. The window closes by itself when the file is ready.
Continue in background. PayHOA takes you to Units and keeps working. See screen 5.
Cancel import. A second window asks Cancel this import? with We will stop reading your file and throw away what we have so far. You can start a new import right away. Click Cancel import to confirm, or Keep going to go back. After you confirm you see Import cancelled. Ready for a new file.
What happens next. When all four steps finish, the Confirm your import window opens (screen 6).
If it stops. If PayHOA can't finish reading the file you see Import stopped with a reason, such as We could not finish analyzing this file. Please try again. Nothing was imported. Upload the file again.
5. Carrying on while a big file is read (the banner on Units)
If you clicked Continue in background, PayHOA takes you to Units and reads the file while you do other things.
What you see on the Units page.
While it's working: a blue banner, Importing your units. followed by the current step, such as Step 3 of 4: Matched 120 of 300 units. We'll let you know when it's ready. You can keep working.
When it's ready: a green banner, such as Your units import is ready to review: 1,500 new. or Your units import is ready to review: 130 updates, 170 new., with a Review import button. The counts can also include unchanged and need attention. A pop-up message, Your units import is ready to review, with the same counts and a Review import link, also appears at the top left of whatever page you're on.
If it stopped: a red banner with the reason, or Your units import stopped before it finished., and a Start over link.
What to do.
Keep working anywhere in PayHOA. You can also close the browser tab; the file keeps being read.
When the green banner or the pop-up appears, click Review import.
What happens next. Review import opens the Confirm your import window (screen 6). Start over opens the upload page.
Note: If you reloaded the page, closed the tab or signed in again while the file was being read, the Confirm your import window is skipped. PayHOA goes with its own reading of the file and opens the mapping page. If the mapping page then asks for a field your file doesn't have, click Upload different file and upload the file again, staying on the page this time.
Good to know. Click the x on the green or red banner to hide it. A hidden import isn't deleted: open the importer again and it offers to resume it.
6. Confirm your import
PayHOA tells you what kind of data it thinks the file holds. Your answer decides which columns are required.
What you see.
The heading Confirm your import.
Your file name, with the number of rows and columns, such as 7 rows · 24 columns.
A highlighted sentence that starts It looks like you're importing… and names the columns that led PayHOA there. For example: units and property data, owner and member data, owner balances, or custom field data.
Does this look right? with two choices:
Yes, that's right: Continue to column mapping.
No, let me clarify: I'll describe what I need.
Cancel and Continue. Continue is greyed out until you pick a choice.
What to do.
Read the sentence. Check it describes your file.
If it does, click Yes, that's right, then Continue.
If it doesn't, click No, let me clarify. A box opens, Describe what you're trying to import, with a few example phrases under it. The examples are written for your file, such as This file is primarily about owner contact information, not units, I only want to import the opening balances from this file or This is a full community roster with units, owners, and balances combined. Type what the file is for (at least 5 characters), then click Continue.
What happens next.
After Yes, that's right: the mapping page opens (screen 10), or the columns need your input window first (screen 7).
After No, let me clarify: PayHOA looks at the file again (the progress window shows for a few seconds) and shows this window again, with neither choice picked. A green line, Updated using your clarification: "…", means the description changed. A yellow line, Your clarification didn't change what we detected. Try describing the columns you want imported, or continue with what we found., means it didn't. Choose again.
Cancel or the x closes the window and leaves you on the upload page. The file has already been read and is saved. Open the importer again and it offers Resume import.
Note: If you see We'll help you import your unit data. Please review the column mappings on the next step., PayHOA couldn't tell what the file is. Click Yes, that's right to carry on as unit data, where Unit Number is required, or No, let me clarify to describe it.
7. Columns need your input
This window opens over the mapping page when your file has columns that don't fit any PayHOA field, and the AI Assistant thinks they're worth keeping. It doesn't open if every column matched.
A column whose heading is close to one of your existing custom fields doesn't count: PayHOA matches it to that field by itself. For example, a column headed Parking Space can be matched to an existing unit field named Parking/Garage Number without asking. Check those matches on the mapping page (screen 10).
What you see.
The heading 1 column needs your input (or 3 columns need your input) and We analyzed the values and have recommendations. Choose how to handle each column.
One card per column, with the column's heading, up to three example values from your file (and + 2 more if there are others), and a recommendation:
AI recommends: Tags - perfect for filtering: the column holds a few values that repeat, such as Phase 1 and Phase 2.
AI recommends: Custom Field - each record has different data: each row has its own value, such as a parking space or parcel number.
A list on each card with three choices: Tag, Custom Field and Skip this column. It starts on the recommendation.
Two buttons: Skip — I'll map manually and Continue.
What to do.
For each column, leave the recommendation or pick another choice.
Click Continue.
What happens next.
For each column set to Tag, the Map column to a tag window opens (screen 8).
For each column set to Custom Field, the Add custom field window opens (screen 9).
Columns set to Skip this column are left out of the import.
Skip — I'll map manually closes the window without changing anything. Those columns stay unmatched, with an empty list above them, and aren't imported unless you match them yourself on the mapping page.
You can make the same choices later from the list above any column. If you leave the importer with those columns still unmatched, the window opens again when you resume.
8. Map column to a tag
What you see.
The heading Map column to a tag and Each value in this column becomes a tag. Tags that already exist are reused; the rest are created when the import runs.
Column: the column's heading. Sample values: up to three values from your file.
Tag which record, with two choices:
Unit: Tag applied to the unit record.
Owner: Tag applied to the owner/member record.
Cancel and Save.
What to do.
Choose Unit or Owner. It starts on Unit.
Click Save.
What happens next. You see Mapped to Tags, and the column is matched to Unit Tag or Owner Tag. Cancel leaves the column unmatched.
9. Add custom field
This window opens for each column you set to Custom Field, and whenever you pick Create new custom field or Create new owner custom field from the list above a column.
What you see.
The heading Add custom field and This field will appear on each unit record and can be exported via the custom report under the reports tab. (It says owner when the field is for owners.)
Column and Sample values from your file.
Apply this field to, with two choices: Unit (Field value stored on the unit record) and Owner (Field value stored on the owner/member record). This isn't shown when you chose Create new owner custom field; the field is for owners.
Field name. It starts as the column's heading.
Two switches: Owner can view field and Owner can edit field. Both start off.
Cancel and Save. Save is greyed out while Field name is empty. Cancel leaves the column matched as it was.
What to do.
Choose Unit or Owner.
Check the Field name, and shorten it if the column heading is long.
Click Save.
What happens next. You see a message such as Unit custom field "Parking Space" will be created during import. The field is not created yet. It's created when you click Start import, and until then it shows in the column's list with an asterisk. If a field with that name already exists, the import uses it.
Important: Check who can see a new field after the import. A new unit field is created so owners can't see it. A new owner field is created so owners can see it but not edit it. Change this under Custom fields. See Tags, notes and custom fields.
10. Edit mapped units and owners data: match your columns
This is the Mapping step. It shows your whole file as a table. Nothing has been saved yet.
What you see at the top.
The heading Edit mapped units and owners data.
A tip box: AI analyzed the file, formatted your data, and matched columns. Review column mappings and see which records are new vs updates.
Warning boxes, when something needs attention (screen 11).
A row of filters, when your file has more than one kind of row: All records (7), New (6), Updating (1), No changes, Skipped, Invalid. Only the kinds your file has are shown.
A Search rows box.
A summary line, such as 7 records will be imported • 6 new • 1 updating. Rows with a problem are added in orange, as in 5 records will be imported • 4 new • 1 updating • 2 invalid (skipped). If every row that can be imported matches what PayHOA already has, it reads 5 records match your existing data. No changes will be made.
What you see above each column.
The heading from your file, followed by a small arrow that points to the field below. If PayHOA split a combined column or merged rows, the headings are the new ones, such as Owner 2 Email.
A small i next to some headings. Point to it for the expected format, such as max 255 characters, Email address · max 127 characters or ZIP code · max 31 characters.
A list showing the PayHOA field the column is matched to. A red asterisk marks a required field. When the file has more than one owner per row, owner fields carry the owner's number, such as Owner 1 First Name and Owner 1 Mailing Address 1. With one owner per row they read Owner First Name, Owner Phone and so on. One of your own custom fields shows its name and kind, such as Parking/Garage Number (unit field). An empty list means the column isn't matched and won't be imported. Two arrows joining mean several columns go into this one field.
Scroll the table sideways to see every column. Blank cells show a dash.
What's in the list.
Skip column (do not import), at the top.
The groups Unit, Unit Address, Owner, Owner Mailing Address, Tags and Balance, with the fields from Columns PayHOA understands.
Unit Custom Fields: your existing unit fields, then Create new custom field.
Owner Custom Fields: your existing owner fields, then Create new owner custom field.
A field already matched to another column is greyed out and marked (mapped). Unit Tag and Owner Tag can be used for several columns.
The list opens at the field the column is matched to now. Scroll up for Skip column (do not import).
What to do.
Scroll right and check every column. Compare the field above it with the values under it.
To change a match, open the list and pick the right field. For an owner column whose heading has a number, such as Owner 2 Phone, pick the plain field (Owner Phone); PayHOA keeps it on owner 2.
To leave a column out, pick Skip column (do not import).
To keep a column PayHOA has no field for, pick one of your custom fields, or Create new custom field (screen 9).
Leave the combined fields (Full Address (combined), Owners (combined data), Owner Full Mailing Address (combined)) to PayHOA. It uses them while reading the file. If a combined column wasn't split the way you expected, split it into separate columns in your spreadsheet and upload it again.
What happens next. Each change is saved straight away. The table reloads and every row is checked again, so warnings can appear or clear.
11. Edit mapped units and owners data: check the rows
Still on the same page, look at the rows.
The Status column. Each row has one of these.
Status | What it means | What the import does |
New | The unit isn't in PayHOA yet. | Creates the unit, its address and its owners. |
Updating | The unit or its owner is already in PayHOA, and something in the row is different or new. | Changes the highlighted values and adds any new owner. |
No changes | The unit or owner is already in PayHOA, and no value in the row replaces a different one. | Nothing is replaced. Tags and custom field values in the row are still saved, and details PayHOA didn't have are filled in. See What an update changes, and what it leaves alone. |
Skipped | The row couldn't be read from the file. | Nothing. |
A warning triangle | The row has a problem. The whole row is greyed out and crossed through. | The row is not imported. Point to the triangle for the reason, which starts This row won't be imported —. |
A badge with a small warning circle | The row is imported, but one detail is left out, such as a co-owner with no name. | Point to the circle for the detail. |
Marks in the cells. A legend under the table explains them.
Mark | Meaning | What you can do |
Orange i | Value updated. This value is different from what PayHOA has. Point to it to see Previous value:. | Click the x beside it to keep PayHOA's current value. Its tooltip reads Don't apply this update on a unit's value and Keep original value on an owner's value. The cell then shows PayHOA's value, and the row moves to No changes if that was its only change. Click the round arrow (Undo) to change your mind. |
Green i on an owner's name or email | Mapped to existing entity. PayHOA matched this row to a person you already have. It shows on the email cell even when PayHOA found the person by name and the email in your file is different or new. | Nothing. Check it's the right person. A different email for an owner who already has one isn't imported. |
A list icon, on an owner's first name, last name and email | New entity to be created during import. The unit exists, and this owner will be added to it. Point to it: Will be created as new. | Check you meant to add an owner. If this person is already on the unit under a different spelling, fix the name in your file so it matches. |
Blue tag | Tag will be created during import. | |
Green tag | Tag already exists and will be reused. | |
Asterisk in a column's list | Custom field will be created when import completes. | |
Round arrow on an owner's name or email | Archived owner is being restored. The row matched a person you archived, and importing brings them back. | Click it to leave them archived. It changes to a box icon: Archived owner will stay archived and won't be linked to this unit. Click again to restore them. |
Warning triangle | Row won't be imported. Hover the icon for the reason. | Fix the file and upload it again. |
2 owners under a unit | The row has more than one owner. |
Warning boxes above the table.
Required fields are not mapped: The following required fields need to be mapped: Unit Number. Match a column to the field. Start import stays greyed out, with Map all required fields before importing, until you do. For owner, balance and custom field files the box reads Need at least one identifier: Unit Number, Unit Address, Owner Email, or Owner Name.
No Unit Number column is mapped: Each new unit will be titled by its Unit Address Line 1. This is information, not a problem.
No units will be created: Map a column to Unit Number or Unit Address Line 1. Without one, this import only adds or updates owners.
1 new unit needs an address (or 3 new units need an address): Missing an address: followed by the units, then Add Unit Address Line 1, Unit City and Unit ZIP Code to these rows in your file, then upload it again. Rows for existing units import as usual.
1 detail will not be imported: These rows still import. followed by each detail, such as Lot 12: Owner 2 (grace.lee@example.com) was not added: a first and last name are needed to add a co-owner.
Import failed, in red: the reason the last attempt to start the import didn't work.
What to do.
Read any warning boxes.
Click Invalid in the filters to see only the rows with problems, and point to each warning triangle.
Click Updating and check the orange marks. For any value you don't want changed, click the x beside it.
Use Search rows to find a unit or a name. If nothing matches you see No matching records found.
Decide:
The problems matter. You can't edit cells on this page. Fix your spreadsheet, click Upload different file (screen 12) and upload it again.
The problems don't matter, or there are none. Click Start import. Rows with a warning triangle are left out; every other row is imported.
What happens next. Start import starts the import straight away, unless a row has a positive Opening Balance. Then the Opening Balances window opens first (screen 13).
Warning: If no row has a positive opening balance, Start import is the point of no return. There is no "Are you sure?" window.
Leaving. Your column matches and choices are saved as you go. If you leave this page, open the importer again and click Resume import.
12. Upload different file?
What you see. After you click Upload different file, a window asks Upload different file? with This will discard your current import progress. You can start fresh with a new file.
What to do.
Click Start fresh to throw this import away. You see Previous import cleared. Ready for a new file!
Click Cancel to stay on the mapping page.
What happens next. Start fresh returns you to the upload page (screen 2). Nothing from the discarded file was imported, and your column matches aren't kept.
13. Opening Balances
This window opens after Start import when at least one row that will be imported has an Opening Balance above zero. A file with only credits (negative balances), or no balances, skips it.
What you see.
The heading Opening Balances.
1 record has a positive opening balance. Those post as charges, so we need to know where to record them. (or 2 records have…).
Income category: a list of your income categories, by number and name. It starts empty, showing Select a category. Sub-categories are shown with a dash in front.
Deposit account: a list of your deposit bank accounts. It starts on the first one.
Cancel and Continue. Continue is greyed out until you pick an Income category.
What to do.
Pick the Income category the balances belong to, usually your dues or assessments category.
Check the Deposit account. It's the account owners' payments for these balances go to.
Click Continue to start the import, or Cancel to go back to the mapping page.
Warning: Continue is the point of no return. It starts the import.
How a balance is saved.
A positive balance becomes an invoice titled Starting Balance on the unit, for that amount, in the income category and deposit account you chose. It's dated the Balance As-Of Date, or today if the file has none, and due the same day. If that date is in the past, the invoice shows as Overdue straight away and the unit shows the amount as past due. It isn't emailed to the owner.
A negative balance becomes a credit on the unit, with the note Unit starting balance. See Account credit.
One per unit. If a unit already has a starting balance, the balance in the file is ignored and the rest of the row is still imported.
All balances in one file use the same category and deposit account.
For how starting balances appear in your books, see Starting balances and backdated invoices.
If a list won't load you see Could not load revenue categories. or Could not load deposit accounts. with Try again. Click it.
14. Importing
What you see. The table is replaced by a progress screen.
A spinner and Importing..., with Please wait while we process your records. This may take a few moments.
After a moment: You can safely leave this page. The import keeps running, and reopening it shows the latest progress.
A progress bar with a percentage, such as 50 of 200 records processed. If some rows failed or were left out, a line under it reads 48 imported · 2 failed.
Near the end: Finishing up, with Every record is in. Closing out the import now. On a large file this can take a few minutes.
What to do. Wait, or carry on with other work. A file with 6 or 7 rows takes about 15 seconds. Rows are saved in small batches, so a large file keeps going after you leave the page or close the tab. PayHOA emails you when it's done.
If it stops. If an import makes no progress for about 30 minutes, the screen changes to Import interrupted: This import stopped before it finished. Nothing has been lost — resume it to import the remaining records. Click Resume import. Rows already saved aren't imported twice. If the file has positive balances and you've reloaded the page, the Opening Balances window asks for the category again first.
What happens next. The Import complete page opens.
15. Import complete
What you see.
The Complete step is marked at the top, with a check mark and Import complete.
A pop-up message at the top left for a few seconds: Import Complete, Your data has been imported successfully.
A card for each count above zero. A card with a count of 1 is worded for one, as in Existing unit updated, Owner added and Tag created.
New units created
Existing units updated: units whose address or description changed, or that gained an owner. A unit that only gained a tag isn't counted.
Owners added: people put on a unit they weren't on before.
Existing owners updated: owners whose name, phone number or mailing address changed or was filled in. An email filled in for an owner who had none isn't counted. A detail added to a second owner on a row may not be counted either.
Tags created: every tag the import put on a unit or owner, including tags you already use. One tag added to 40 units reads 40.
Unit custom field values saved and Owner custom field values saved. These count every row that had a value for the field, including rows where the value was already the same.
Unit imports failed: rows that weren't imported, including the rows that had a warning triangle on the review page.
Units & owners skipped
If nothing needed changing: No units & owners needed changes. Every row already matched.
A red box, Some rows could not be imported., listing up to 10 rows with the reason, as Row 7: Unit ZIP Code is required to create a new unit., then And 2 more. Row 7 is the seventh row on the review page, where each unit is one row. It isn't always line 7 of your spreadsheet.
A yellow box, Owner matching did not finish for part of this file., if PayHOA couldn't check some rows against your existing people. Those rows were imported as new owners and some may be duplicates.
The Return to Units & Owners button.
Note: The count cards can sit on top of the last lines of the red box, as in the picture, where Row 7: Unit ZIP Code is required to create a new unit. is hidden. The summary email lists every row.
What to do.
Read the counts. Check they're what you expected from the summary line on the mapping page.
If rows failed, note the reasons. The same list is in the email PayHOA sends you.
Click Return to Units & Owners.
What happens next. You're back on Units, with the new units in the list. PayHOA emails you a summary titled Units Import Complete, or Units Import Completed with Errors if rows failed.
Important: Rows that were saved stay saved, even when other rows failed. To bring in the rows that failed, fix them in your spreadsheet and import the file again. The rows that already went in show as No changes.
After the import
Where the new records are. Units are on Units. Owners are on People and on each unit's page. The unit count at the top of Units goes up by the number of new units. No banner about the import is left on Units.
Check these.
Open a few units and compare them with your file: address, owners, tags and custom fields. The state is saved by its full name (KY becomes Kentucky), and the Move-In Date shows on the unit page as Last ownership change. See The unit page.
Units with more than one owner. Make sure each owner is there once.
Owners without an email. On Units they have a warning triangle beside their name: This user has no email on file.
Balances. On a unit with a starting balance, check the Starting Balance invoice or the credit. The invoice is under Current invoices on the unit page, with the Balance As-Of Date as its active date and due date. See Starting balances and backdated invoices.
New custom fields. Check who can see and edit each one. See Tags, notes and custom fields.
Archived owners. If the review page showed owners being restored, check they're the people you meant. See Archive, restore or lock a person.
What PayHOA did not do.
It didn't invite anyone. No activation emails are sent, and nothing in the importer offers to send any. A new unit's Communications tab reads No communications on record for unit. When you're ready, see Invite owners to the portal.
It didn't email any invoices. Starting balance invoices are never emailed.
It didn't create regular invoices. Set up your dues next. See Set up a recurring invoice.
It didn't remove anything. Owners, tags and values that weren't in the file are still there.
It didn't give owners an email they didn't have in the file. An owner imported without an email can't sign in until you add one. See Edit a person's contact details.
Fix a mistake.
The mistake | How to fix it |
A wrong value on a few units or owners | Edit them. See Edit, delete or combine units and Edit a person's contact details. |
A wrong value on many units or owners | Correct the spreadsheet and import it again. Matching rows are updated, not duplicated. See Update existing units and owners with the importer. |
A unit that shouldn't exist | Delete it. See Edit, delete or combine units. |
A duplicate owner | |
An owner on the wrong unit | |
A wrong starting balance | Open the unit, remove the starting balance and enter the right one. See Starting balances and backdated invoices. Importing the file again doesn't change a balance that's already there. |
A wrong tag on many units | |
A whole import that was wrong | There's no undo. Contact PayHOA support with your association's name and the date and time of the import. |
If something goes wrong
When you upload the file
Message | What it means | What to do |
Unsupported file type. Please upload a CSV, XLS, XLSX, PDF file. | The file isn't one of the four types. | Save it as CSV or Excel. A Google Sheets or Numbers file has to be downloaded or exported as CSV or Excel first. |
File is too large. The maximum file size is 10MB. or This file is 12.3MB. The maximum size we can import is 10MB. Please split it into smaller files and import them one at a time. | The file is over 10 MB. | Split it into smaller files and import them one after another. Remove pictures and extra sheets from an Excel file. |
That file is empty. Please upload a file that contains data. | The file has nothing in it. | Check you picked the right file. |
This file contains no data rows. It has column headers but nothing underneath them. Add your rows and upload it again. | Only the heading row has anything in it. | Add your units under the headings. In Excel, check the right sheet was open when you saved. |
Could not detect column headers in the file. Please check the file format. | PayHOA found no heading row. | Add a first row naming each column. |
The first row of this file looks like data, not column headers. Add a header row naming each column, or uncheck "My file has headers", then upload it again. Otherwise that first record would be lost. | The first row looks like a unit, not headings. | Do what the message says. |
We could not read this file. Please check it opens correctly as a CSV or spreadsheet, then try again. | The file is damaged or isn't really the type its name says. For a PDF, PayHOA couldn't find a table in it. | Open it in your spreadsheet program and save it again as CSV. |
Failed to process file. Please try again., Failed to process file. Check the file type and size, then try again., Failed to upload file. Please try again. or Failed to parse file | Something went wrong on PayHOA's side or with your connection. | Try again. If it keeps happening, contact PayHOA support with the file and the time you tried. |
Session expired. Please refresh and try again. | You've been signed out. | Refresh the page, sign in and try again. |
You do not have permission to import units for this organization. | You don't have Write on Units. | Ask an admin. See Give board members and staff access. |
While PayHOA reads the file
Message | What it means | What to do |
Import stopped with We could not finish analyzing this file. Please try again. or Something went wrong while we were reading your file. Please try again. | Matching owners or units failed part-way. Nothing was imported. | Upload the file again. |
The import stopped responding. Please try again. | Reading the file made no progress for 10 minutes and was stopped. | Upload the file again. For a very large file, split it. |
Your units import stopped, or the red banner Your units import stopped before it finished. | The same, while you were working elsewhere. | Click Start over. |
We could not cancel that import. Try again. | Cancel import didn't go through. | Open the importer again and click Start fresh. |
Unable to analyze import: We couldn't tell what you're importing. This step needs AI analysis, which is temporarily unavailable. Please try again later, or contact support if it keeps happening. | The AI Assistant wasn't available. | Click Cancel and try again in a few minutes. Your file is saved; use Resume import. |
Your clarification didn't change what we detected. Try describing the columns you want imported, or continue with what we found. | Your description led to the same answer. | Say which columns matter, or click Yes, that's right. |
Failed to redetect intent. Please try again. | PayHOA couldn't look at the file again. | Try again, or open the importer again and use Resume import. |
Could not refine intent. Proceeding with original. | Your description couldn't be used, and PayHOA carried on with its first answer. | Check the required fields on the mapping page. |
On the mapping page
Message | What it means | What to do |
Required fields are not mapped: The following required fields need to be mapped: Unit Number | No column is matched to Unit Number. | Pick Unit Number above the column that holds your unit numbers. If your file has no such column and is about owners, start again and choose No, let me clarify on Confirm your import. |
… Need at least one identifier: Unit Number, Unit Address, Owner Email, or Owner Name | No column says which unit or person each row is about. | Match one of those fields. |
Map all required fields before importing (on Start import) | The same. | The same. |
No units will be created | No column is matched to Unit Number or Unit Address Line 1. | Fine if you only mean to add or update owners. Otherwise match one. |
3 new units need an address | New units are missing Unit Address Line 1, Unit City or Unit ZIP Code. | Add them in your spreadsheet and upload it again. |
2 details will not be imported | Part of a row is left out; the row is still imported. | Read each detail. Fix the file if it matters. |
Failed to load mapping data | The page couldn't load the import. | Refresh the page. If it still fails, open the importer again and click Resume import. |
Failed to save mapping or Failed to save change | Your last change wasn't saved. | Make the change again. |
Reasons a row won't be imported
Point to a row's warning triangle to see these. They also appear on the Import complete page and in the email.
Reason | What to do |
Unit Number is required. | Fill in the unit number on that row. |
Need at least one identifier: Unit Number, Unit Address, Owner Email, or Owner Name. | The row has none of them. Add one, or delete the row. |
Unit Address Line 1 is required to create a new unit. Also Unit City and Unit ZIP Code. | The unit isn't in PayHOA yet, so it needs an address. If the unit does exist, its number in the file doesn't match its title in PayHOA; correct it. |
Owner first and last name are required to create a new owner. | The owner isn't in PayHOA yet and the row has no name, or only one word. Add both names. |
No unit named "Lot 99" in this organization. | An owner, balance or custom field row names a unit PayHOA doesn't have, and has no owner to add. Correct the unit number. |
Owner Email "john@" is not a valid email address. | Correct the email, or clear the cell. |
Owner Auxiliary Email "…" is not a valid email address. Separate several with a semicolon. | Correct it. Put a semicolon between addresses. |
Owner Phone "call after 5" is not a valid phone number. | Leave only the number. |
Move-In Date "02/31/2024" is not a valid date. Use a real calendar date from 1900 onward. Also Balance As-Of Date. | Correct the date. |
Opening Balance "abc" is not a valid amount. | Leave only the number. |
Unit State "ZZ" is not a recognized state. Use the two-letter code or the full state name. Also Owner Mailing State. | Correct the state. |
Unit ZIP Code "4050" is not a valid ZIP code. Use 5 digits, or 5 digits plus a 4-digit extension. Also Owner Mailing ZIP. | Correct the ZIP code. |
Owner Email is 140 characters. It must be 127 characters or fewer. The same wording is used for any field that's too long, and for Custom field "Notes" (255). | Shorten the value. |
Owner 1 email "john@" is not a valid email address., Owner 2 phone "…" is not a valid phone number. and other messages that start Owner 1 or Owner 2 | The same problems. When your owner columns are numbered, as in the sample file, the message names which owner. |
This row could not be read from the file and was skipped. | The row is damaged in the file. Retype it in your spreadsheet. |
Owner 2 (jane@example.com) was not added: a first and last name are needed to add a co-owner. | A warning, not an error. The rest of the row is imported. Add the co-owner's name and import again, or add them on the unit. |
When you start the import, and after
Message | What it means | What to do |
Choose the revenue category for the starting balances in this file. | The file has positive balances and no category was chosen. | Click Start import again and pick an Income category. |
Could not start the import. Please try again. | PayHOA couldn't start the work. Nothing was imported. | Click Start import again. |
This import session can no longer be run — it may have already completed or failed. Upload the file again to start a new import. or Cannot transition from failed to reviewing. | This import already ran. | Check Units for what went in, then upload the file again. Rows already in show as No changes. |
Lost contact with the import. Reopen this import to see where it got to. | Your browser lost touch with PayHOA. The import may still be running. | Wait for the email, or use your browser's Back button to reopen the page. Don't upload the file again until you've checked Units. |
The import finished but no summary was returned. Reopen this import to review it. | The import ran but the result didn't load. | Check Units and your email. |
Import interrupted | The import stopped part-way. | Click Resume import. |
Some rows could not be imported. with Row 3: … | Those rows failed. Everything else was saved. | Fix the rows and import the file again. |
Row 5: This email address belongs to a user in another organization you do not have access to. | In an import, this means the email belongs to a login that was deleted, and whose history is in another association you aren't an admin of. An email that is an active login in another association doesn't fail in an import: the owner is linked to that login. (When you add an owner by hand, the same message means the email is an active login in an association you aren't an admin of.) | Contact PayHOA support with the owner's name, email and unit. See Owners with more than one unit or association. |
Row 5: Failed to create owner: … | The owner couldn't be created. | Add the owner by hand. If that fails too, contact PayHOA support. |
Row 5: Cannot identify owner: need email, name, or unit number | The row had nothing to go on. | Add one of them. |
Row 5: We could not save the starting balance right now. We have been notified and are working on it. Please try again. | The unit's balance couldn't be saved. | Import the file again later, or enter the balance on the unit. |
Owner matching did not finish for part of this file. | Some rows weren't checked against your existing people and were added as new owners. | Check the owners on the imported units for duplicates. See Archive, restore or lock a person. |
Email titled Units Import Completed with Errors | Some rows failed. If more than half failed, the email starts Import failed: 6 of 10 rows failed (60.0% failure rate exceeds 50% threshold). | The rows that were fine are saved. Fix the rest and import again. |
Common questions
Is there a template? Yes. On the upload page, click Download the sample file. You don't have to use it; PayHOA reads your own headings.
Can I import a file I already imported? Yes. Rows that match what PayHOA has show as No changes, rows with differences show as Updating, and only new units show as New. Nothing is duplicated when the unit numbers and owner emails or names match. When nothing would change, the summary line reads 5 records match your existing data. No changes will be made. Start import still works; it changes nothing.
Can I change many units or owners at once? Yes. Updating is one of the importer's two jobs. Export your units or owners, get the file ready, change the cells that need changing, and import the file. Don't import the Units export exactly as downloaded: delete its balance, owner, tag and custom field columns first, because a balance column can be imported as a starting balance and automatic tags become real tags. Rows for units you already have show as Updating or No changes, not New, and nothing is duplicated. You can change unit addresses, owner names, phone numbers, mailing addresses and custom field values, add tags and co-owners, and fill in missing emails. See Update existing units and owners with the importer.
I already imported my units and owners. Can I import again just to add what was missing? Yes. Import a second, smaller file with the unit number, the owner's name where the detail belongs to an owner, and only the columns you're adding. PayHOA adds the details to the units and owners you already have and doesn't make copies of them. See Add phone numbers, emails or addresses for owners from a file, Add tags or custom fields to many units from a file and Add co-owners to units from a file.
Will importing my list again create duplicates? Not when PayHOA recognizes the rows. A unit is recognized by its title, and an owner by their email, or by exactly the same name on the same unit. A row it doesn't recognize shows as New, so check the New filter before you click Start import. See How PayHOA decides a row is an update.
Can I update phone numbers or mailing addresses for many owners at once? Yes. Import a file with the unit number, a way to find each owner (their email, or exactly the name PayHOA has) and only the columns you want to change. On the review page each replaced value has an orange mark; check them before you click Start import. The Units export has no phone numbers or mailing addresses, so start from a custom report. See the steps.
Can I change owners' emails in bulk? No. The importer never replaces an email an owner already has, because that email is their login. It can fill in an email for an owner who has none, when that owner is the first owner on the row. To change an existing email, edit the person. See Edit a person's contact details.
Does importing invite owners or send them anything? No. No activation emails, no invoices, no texts. See Invite owners to the portal when you're ready.
An owner has no email address. Can I still import them? Yes. Leave Owner Email blank. They need a first and last name. You can add an email later.
Two owners share one email address. An email belongs to one person. Put it on one owner and leave the other's blank, or put it in Owner Auxiliary Email.
An owner owns several units. Use the same Owner Email on each row. PayHOA links one person to all of them. See Owners with more than one unit or association.
An owner's email is already used in another association. When you import, the owner is linked to that person's existing login, so they keep one login for both associations. You don't need to be an admin in their other association, and the row doesn't fail. An import row fails with This email address belongs to a user in another organization you do not have access to. only when the email belongs to a login that was deleted and whose history is in an association you aren't an admin of. Adding an owner by hand, or changing ownership, is stricter: there the same message means the email is an active login in an association you aren't an admin of, and PayHOA support adds the person. See Adding someone who's already in another association.
My units don't have unit numbers, only addresses. The surest way is to add a Unit Number column that repeats the street address. Without one, it depends on how PayHOA reads the file. If it reads it as owner data, the mapping page says No Unit Number column is mapped and titles each new unit by its Unit Address Line 1. If it reads it as unit data, the mapping page says Unit Number is required, and you need to add the column.
Can I import tenants? No. Everyone in the file becomes an owner. See Tenants, renters and other contacts.
A unit was sold. Can I import the new owner? Not on its own. Importing adds the new owner next to the old one. Use Change ownership when a unit is sold.
I imported a file and old owners came back. A row matched a person you had archived, and the import restored them. On the review page those rows have a round arrow on the owner's name or email; click it before you import to leave the person archived. To archive them again, see Archive, restore or lock a person.
The import made duplicates. A row creates a new unit when its unit number doesn't match a unit title, and a new owner when neither the email nor the name on that unit matches. Check the New filter on the review page before you import; anything you already have should not be there. To tidy up afterwards, see Edit, delete or combine units and Archive, restore or lock a person.
Can I edit a value on the review page? No. You can change which field a column goes to, skip a column, keep an existing value instead of the new one, and leave an archived owner archived. To change a value, fix the spreadsheet and upload it again.
Can I leave out one row? Not on the review page. Delete the row from your spreadsheet and upload it again.
How long does it take? A few seconds for a small file. A file with hundreds of units takes a few minutes to read and a few more to import. You can keep working both times.
Can two admins import at the same time? Each admin's unfinished import is their own. Don't import the same units from two files at once.
My addresses are in Canada. Provinces are recognized, but Unit ZIP Code only accepts US ZIP codes, so a Canadian postal code stops the row. Contact PayHOA support.
The import page looks different from an old video or bookmark. An older import page (Load import file, CSV only, with Import units at the bottom) is no longer linked from PayHOA. Use Units → Add units → Import owners and units.
Can PayHOA import the file for me? Yes, as part of getting your association set up, and it doesn't cost anything. PayHOA's Onboarding Specialists import your units, owners, starting balances and custom fields and help you set up, at no charge: setup, onboarding and data import are always free. To ask for it, write to your onboarding specialist, whose name, email and phone are under Contact Us on Launchpad (see Get help from your onboarding specialist), or contact PayHOA support with your association's name and the file. If you're importing a file yourself and it won't import, contact PayHOA support with your association's name, the file and a screenshot of the message, and they'll help.

































