Residents/Members can edit their Preferred Name in their profiles and the following explains where and when it is used - in comparison to First Name.
Field | Meaning |
First Name | Legal / official first name. Used on enforceable documents |
Last name | Legal last name |
Full Name | Always `firstName + lastName` (recomputed when legal names change). |
Preferred name | Optional nickname or “goes-by” name. When set, replaces first name for display contexts only |
Category | Use | First Name Source | Last Name |
Display (casual) | Portal UX, navigation, dashboard welcome, resident directory, Intercom, casual email/SMS salutations |
|
|
Legal (formal / enforceable) | Postal envelopes, certified mail, violation notices, collections, invoices, coupons, election ballot mail |
|
|
Admin record (staff UI) | People list/detail views, exports, audit logs | Legal | Legal |
Search / matching | Directory search, people search, CSV re-import | Index both legal and preferred names | Index both legal and preferred names |
Self-service profile |
| Locked by default (organization setting); preferred name always editable | Same lock setting as first name |
CSV import (admin) | Bulk people import | Always writes legal name columns; optional | Admin-only management |
👉 NAME HANDLING POLICY
Category: Display (casual)
Use: Portal UX, navigation, dashboard welcome, resident directory, Intercom, casual email/SMS salutations
First Name Source: preferredName (if set), otherwise firstName
Last Name Source: lastName
Category: Legal (formal / enforceable)
Use: Postal envelopes, certified mail, violation notices, collections, invoices, coupons, election ballot mail
First Name Source: firstName
Last Name Source: lastName
Category: Admin Record (staff UI)
Use: People lists, detail views, exports, audits
First Name Source: Legal first name (show preferred name when different)
Last Name Source: Legal last name
Category: Search / Matching
Use: Directory search, people search, CSV re-import
First Name Source: Index both legal and preferred names
Last Name Source: Index legal last name
Category: Self-Service Profile
Use: /profile
First Name Source: Legal name locked by default (organization setting); preferred name always editable
Last Name Source: Same lock setting as first name
Category: CSV Import (admin)
Use: Bulk resident imports
First Name Source: Always writes legal name fields; optional preferred_name field
Last Name Source: Legal last name
👉 EMAIL & TEMPLATE MERGE FIELDS
{{firstName}} / {{first_name}}
Display first name (preferred name if set, otherwise legal first name)
{{fullName}} / {{full_name}}
Display full name
{{legalFirstName}} / {{legal_first_name}}
Legal first name only
{{legalFullName}} / {{legal_full_name}}
Legal full name
{{preferredName}} / {{preferred_name}}
Raw preferred name field (blank if not set)
IMPORTANT:
Use legal name variables for enforcement-related communications, including violations, collections, invoices, certified mail, and other formal notices.
🛠️ Platform Usage Map
DISPLAY SURFACES (Uses Preferred Name When Available)
• Dashboard Welcome
• Navbar
• Resident Directory
• Intercom
• Profile (Preferred Name Field)
CASUAL COMMUNICATIONS (Merge Fields Use Display Name)
• Email Automations
• Organization Email Templates
• Group & Campaign Emails
• TipTap Merge Field Picker
LEGAL / ENFORCEMENT (Always Uses Legal First + Last Name)
• Postal Mail / PostGrid
• Automation Postal Channel
• Dues & Invoice Mailings
• Overdue Notices & Collections
• Payment Coupons & Invoices
• Violation Certified Mail
• Election Ballot Postal Mail
• Unit Communication Settings
CSV IMPORT
Supported Columns:
• first_name (required legal first name)
• last_name (required legal last name)
• preferred_name (optional display name)
Import Behavior:
• Legal names are always imported.
• preferred_name is optional.
• Exports include preferred_name.
• If preferred_name is omitted during import, the resident’s existing preferred name remains unchanged.