Required Data

Understanding Required Data

Getting your system operational requires two dimensions of data:

Breadth: Which entity types you need
Depth: Which fields within each entity are required

Required Breadth: Core Entities

These 11 entity types must be included in your data submission:

Order	Entity	What It Is	Why It's Required
1	Organization	Your management company	Set up by TownSq
2	Implementation Waves	Phased rollout groups	Organizes associations for migration
3	Associations	HOAs you manage	Links all properties
4	Wave Associations	Association wave assignments	Links associations to waves and stores operational setup
5	Units	Individual properties	Defines what you manage
6	Unit Types	Property classifications	Determines assessment amounts
7	Accounts	Financial accounts	Tracks balances and payments
8	Members	People (owners, tenants, occupants)	Who to bill and contact
9	Operating Bank Accounts	Primary bank accounts	Processes payments
10	Recurring Charges	Automated fee schedules	Defines regular assessments
11	Delinquencies	Late fee configurations	Handles late payment processing

Load Order Matters

Load entities in the order shown above to maintain data integrity.

Why? Each entity depends on the previous ones:

Implementation Waves must exist before Wave Associations
Associations must exist before Wave Associations can link to them
Wave Associations link Associations to Waves and store operational setup
Units need Associations to exist
Members link to Accounts
Accounts link to Units
Bank Accounts link to Associations

Required Depth: Minimum Fields

Each entity type has required fields that must be populated.

Quick Reference

Organization

Name
Your unique ID

Implementation Waves

Name (e.g., "Wave 1 - Pilot", "Q1 2025 Rollout")
Organization ID (links to your company)
Status (planned, in_progress, completed, failed, rolled_back)
Go-live date (optional but recommended)

Associations

Name
External ID (your unique ID for this association)
Organization ID (links to your company)

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

Wave Associations

Organization ID (links to your company)
External ID (matches the association's external_id)
Name (association name)
Wave ID (optional - which implementation wave)
Operational Setup (optional - JSON configuration for delinquency, billing, fiscal settings)

Units

Unit number
Unit ID (your unique ID)
Association ID (which HOA it belongs to)

Members

Name (first and last)
Member ID (your unique ID for this person)
Account ID (which account they're associated with)
Roles (OWNER, TENANT, or OCCUPANT)
Primary contact information (email or phone)

Accounts

Account number (your unique ID)
Unit ID or Unit Number (which property)
Current balance

Unit Types

Name (e.g., "SFH", "2BR Condo")
Association ID (which HOA it belongs to)

Operating Bank Accounts

Association ID (which HOA it belongs to)
Account number
Routing number
Partner bank name
Is primary (true/false)

Recurring Charges

Association ID (which HOA it belongs to)
Unit type (which units this charge applies to)
Charge type (e.g., "HOA Dues")
Assessment amount
Frequency (Monthly, Quarterly, Annual)
Begin date

Delinquencies

Association ID (which HOA it belongs to)
Late fee active (true/false)
Late fee method (if applicable)
Late fee amount (if applicable)

Optional Entities (Future Growth)

These can be added later as needed:

Helpful for Standardization (Recommended):

Standard GL Accounts - Associa's standard chart of accounts (reference data)
Corporate GL Accounts - Your organization's GL accounts that map to standards
Association GL Accounts - Association-specific account overrides
Standard Vendor Types - Associa's standard vendor classifications (reference data)
Vendor Types - Your organization's vendor types that map to standards
Vendor Type Mappings - Mappings between your vendor types and standards
Vendors - Vendor master data

Helpful for Automation (Recommended):

Investment Bank Accounts - Reserve and investment accounts
Direct Debits - Automatic payment processing

Helpful for Advanced Features:

Account Addresses - Mailing addresses for accounts
Account Transactions - Historical transaction data
Account Notes - Important account documentation
Emergency Contacts - Emergency contact information
Account Units - Explicit account-to-unit relationships (if needed)

Why This Structure Matters

Without the required breadth (entities) and depth (fields), the system cannot:

Missing Breadth:

❌ Can't track properties without Units entity
❌ Can't bill without Accounts entity
❌ Can't process payments without Bank Accounts entity

Missing Depth:

❌ Can't link data without unique IDs
❌ Can't contact members without primary contact fields
❌ Can't maintain relationships without foreign key fields

Required vs. Optional Fields

Required Fields

Must be provided to import the entity
System will reject records missing required fields
Marked as "Required" in detailed entity pages

Optional Fields

Can be added later to enhance functionality
System will work without them
Enable additional features when populated

Questions?

See FAQs for common questions about entity requirements and load order.

On this page