Help center

Residents & households

Everything you'll do day-to-day with the household list — add, edit, invite, archive.

The model

A resident in HOAPortal represents a household, not a person. One row per house number. The fields that matter:

  • House number and street — the identity of the household. Residents are grouped by street in the admin UI.
  • Primary name— usually the head of household / owner of record. This is what appears on emails ("Hi John").
  • Secondary name (optional) — spouse / co-owner. Listed alongside but not separately addressable.
  • Email and phone — at least one is required for the portal to invite/contact them. Adding both gives more channels for delivery.
  • Alt phone (optional) — secondary number for emergency / family contact.
  • Monthly dues — defaults to the community default but can be overridden per household (e.g. a corner plot pays more, a long-term member is grandfathered into an older rate).
  • Dues start date — when this household first owed dues. Used as the starting period in their statement. Falls back to move-in date, then to the current period.
  • Active — when false, the household is excluded from reminders, dues calculations, polls, and group sends. Use this for moved-out residents you want to archive without deleting.

Adding residents

One at a time

/admin/residents → Add resident. Fill the form, save. Useful for move-ins after the initial launch.

Bulk import

/admin/residents → Bulk import. The tool accepts CSV with columns matching the resident fields. Download the template, fill in from your spreadsheet, upload. The importer:

  • Validates required fields (house_number, street, primary_name, email or phone).
  • Reports a row-by-row preview before committing.
  • Refuses to overwrite existing house numbers — fix the CSV or delete first.
  • Treats blank cells in optional columns as "no value" (won't overwrite existing data with blanks).

Editing a household

/admin/residents/[id]. Edit any field. Saving updates the household record. Changes to monthly_dues apply going forward (current and future periods); past periods on the statement keep their original dues for an accurate history.

If you want to retroactively reprice past periods (rare), use a Levy to add the difference rather than editing dues — keeps the audit trail clean.

Inviting residents

An invite is a one-time URL (14-day expiry) that lets a resident set their own password. Two ways to send:

  • One resident: open their profile → Generate invite link → Send via email + WhatsApp + SMS. The link is also copyable for manual share.
  • Whole community: /admin/residents → Invite everyone. Generates (or reuses) an invite for every active resident without a login and fires it on all channels they have.

Notes:

  • The link is a bearer token — anyone who opens it can claim that household's account. Don't post it in group chats. The auto-send goes directly to the resident's personal email/WhatsApp/SMS.
  • Safe to re-send. The same token is reused, so a resident already mid-flow on their original link doesn't get kicked out.
  • To force a fresh link (e.g. you suspect a leak), click Regenerate on the resident's profile.

Handling move-outs

When a household moves out:

  1. Mark them as inactive(uncheck the "Active" toggle on their profile). They stop appearing in dues calculations, reminders, and notices.
  2. Their history stays intact — past payments, past dues, the full statement remain viewable.
  3. If a new family moves into the same house, add them as a new resident with the same house number. The old (inactive) record is automatically renamed in queries by date so there's no collision.

Deleting a resident outright is possible but loses all their payment history — almost always you want "inactive", not delete.

Setting an admin role

Some residents are also community admins (treasurer, chairman, secretary). To grant them admin access, after they've set up their portal login, edit their user record and set the role:

  • admin / chairman / secretary / treasurer — full admin access. Differences are cosmetic right now (shows on the audit log), with finer-grained permissions coming.
  • resident — default. Only sees their own household.
Need a hand? Email us — or check the FAQ for quick answers.