Field Mapping Reference

What This Page Is For

Your source system likely uses different field names than TownSq. This reference shows common mappings to help you identify which of your fields correspond to our required fields.

For data format requirements (dates, phone numbers, currency, etc.), see Preferred Data Formats.

Implementation Wave Mappings

TownSq Field	Common Source Field Names	Notes
`name`	wave_name, phase_name, rollout_group	e.g., "Wave 1 - Pilot", "Q1 2025 Rollout"
`description`	wave_description, notes, details	Optional description of wave scope
`go_live_at`	cutover_date, go_live_date, migration_date	Target date for TownSq cutover
`status`	wave_status, phase	planned, in_progress, completed, failed, rolled_back
`organization_id`	org_id, company_id	Your organization identifier

Wave Association Mappings

TownSq Field	Common Source Field Names	Notes
`external_id`	association_id, community_id	Must match the association's external_id
`name`	association_name, community_name	Association name
`wave_id`	wave_number, phase_id, rollout_group_id	Which implementation wave (optional)
`operational_setup`	config, settings, operational_config	JSON containing delinquency, billing, fiscal settings
`organization_id`	org_id, company_id	Your organization identifier

Note: wave_id and operational_setup were moved from associations to wave_associations in the SDM-271 schema refactor.

Association Mappings

TownSq Field	Common Source Field Names	Notes
`external_id`	association_id, community_id, property_id, hoa_code	Your unique identifier
`name`	association_name, community_name, hoa_name, legal_name	Use legal entity name
`federal_tax_id`	ein, tax_id, federal_id	Format: XX-XXXXXXX
`address`	physical_address, street_address, property_address	Primary street address
`number_of_units`	total_units, unit_count, property_count	Total residential units

Schema Note: wave_id and operational_setup are no longer stored on associations. Use Wave Associations table instead.

Member Mappings

TownSq Field	Common Source Field Names	Notes
`member_id`	person_id, contact_id, homeowner_id	Your unique identifier for this person
`account_id`	account_number, billing_id	The billing account this person is associated with
`first_name`	fname, first, given_name	Person's first name
`last_name`	lname, last, surname, family_name	Person's last name
`roles`	member_type, role, relationship_type	Can be OWNER, TENANT, or OCCUPANT (can have multiple)
`is_primary_contact`	primary_flag, main_contact	Whether this person is the main contact for the account
`ownership_percentage`	ownership_pct, percentage, share	For owners only; must total 100% per property

Unit Mappings

TownSq Field	Common Source Field Names	Notes
`unit_id`	property_id, lot_id, parcel_id	Your unique identifier
`unit_number`	lot_number, address_number, unit_name	Display identifier
`unit_type`	property_type, dwelling_type, classification	e.g., SFR, Condo, Townhome
`square_footage`	sqft, area, size	In square feet

Account Mappings

TownSq Field	Common Source Field Names	Notes
`account_id`	account_number, ledger_id, ar_id	Your unique identifier
`account_balance`	current_balance, ar_balance, outstanding	Current balance due
`billing_address`	mailing_address, statement_address	Where to send bills

Unit Type Mappings

TownSq Field	Common Source Field Names	Notes
`association_id`	community_id, hoa_id	Which association this unit type belongs to
`name`	unit_type, property_type, classification	Type name (e.g., "SFH", "2BR Condo")
`description`	type_description, notes	Optional description of this unit type
`square_footage`	sqft, area, size	Standard square footage for this type
`assessment_amount`	monthly_fee, dues_amount	Standard assessment for this type

Operating Bank Account Mappings

TownSq Field	Common Source Field Names	Notes
`association_id`	community_id, hoa_id	Which association owns this account
`account_number`	bank_account, account_no	Bank account number (SENSITIVE)
`partner_bank`	bank_name, institution	Name of the banking institution
`is_primary`	primary_flag, main_account	Whether this is the main operating account
`checking_routing_number`	routing_number, aba_number, transit_number	9-digit ABA routing number (SENSITIVE)
`bank_name`	institution_name, bank	Full name of the bank
`ach_account`	ach_enabled, electronic_payments	Whether account supports ACH/electronic payments

Investment Bank Account Mappings

TownSq Field	Common Source Field Names	Notes
`association_id`	community_id, hoa_id	Which association owns this investment
`institution`	bank_name, investment_firm, financial_institution	Name of the financial institution
`type`	account_type, investment_type	Type of investment (CD, Money Market, Savings)
`account_number`	account_no, investment_account	Account number at the institution
`rate`	interest_rate, apy, yield	Interest rate or annual percentage yield
`term`	maturity_period, duration	Investment term (e.g., "6 months", "1 year")
`active`	is_active, status	Whether the account is currently active

Recurring Charge Mappings

TownSq Field	Common Source Field Names	Notes
`association_id`	community_id, hoa_id	Which association this charge applies to
`unit_type`	property_type, classification	Type of unit this charge applies to
`charge_type`	assessment_type, fee_type, charge_category	Category of charge (e.g., "HOA Dues", "Maintenance")
`assessment_amount`	amount, fee_amount, charge_amount	Dollar amount charged per period
`frequency`	billing_frequency, period	How often charged (Monthly, Quarterly, Annual)
`begin_date`	start_date, effective_date	When this charge schedule begins
`include_on_direct_debit`	auto_pay_eligible, ach_included	Whether included in automatic payments (Yes/No)

Delinquencies Mappings

TownSq Field	Common Source Field Names	Notes
`association_id`	community_id, hoa_id	Which association these policies apply to
`is_late_fee_active`	late_fees_enabled, charge_late_fees	Whether late fees are charged (true/false)
`late_fee_method`	late_fee_calculation, fee_method	How late fees are calculated (Fixed, Percentage, etc.)
`late_fee_amount`	late_fee, default_late_fee	Dollar amount for fixed late fees
`late_fee_cutoff_day`	due_date, payment_due_day	Day of month when late fees apply
`is_late_interest_active`	interest_enabled, charge_interest	Whether interest is charged (true/false)
`late_interest_rate`	interest_rate, annual_rate	Annual interest rate for late payments

Direct Debit Mappings

TownSq Field	Common Source Field Names	Notes
`account_id`	account_number, billing_account	The account that authorized automatic payment
`start_date`	enrollment_date, effective_date, begin_date	When automatic withdrawals begin
`bank_transit_id`	routing_number, aba_number	Homeowner's bank routing number (SENSITIVE)
`bank_account_no`	account_number, bank_account	Homeowner's account number (SENSITIVE)
`end_date`	expiration_date, termination_date	When authorization expires (optional)

Vendor Mappings

TownSq Field	Common Source Field Names	Notes
`vendor_id`	supplier_id, contractor_id, payee_id	Your unique identifier
`name`	vendor_name, supplier_name, company_name	Legal or business name
`vendor_type`	service_type, category, classification	Type of service provided
`contact_name`	primary_contact, contact_person	Main contact at vendor
`contact_phone`	phone, vendor_phone, office_phone	Primary phone number
`contact_email`	email, vendor_email	Primary email address
`tax_id_number`	ein, tax_id, ssn	Federal tax ID for 1099 reporting

How to Use This Reference

Find your source field in the "Common Source Field Names" column
Map it to the TownSq field in the first column
Check the notes for any specific requirements
Verify the format using Preferred Data Formats

Can't Find Your Field?

If your source system uses different field names:

Look at the "Notes" column for context
Check your entity's detailed page in Entities
Contact your onboarding coordinator for clarification

Next Steps

Review Preferred Data Formats for format requirements
Check Required Data for what entities and fields are required
See detailed specs in Entities

On this page