Skip to content

Borrower Management

The apps.borrowers module manages borrower entities and their associated data, including contact information, identities, consents, payment instruments, and loan party associations.

Borrower Profiles

Core Fields

Field Type Description
first_name String First name
last_name String Last name
date_of_birth Date Date of birth
ssn_last_four String Last 4 digits of SSN (full SSN never in API responses)
employer String Current employer
annual_income MoneyField Annual income
language_preference String ISO 639-1 code (default en)
communication_preferences JSONB Preferred communication channels
do_not_contact Boolean Cease and desist flag
metadata JSONB Extensible data

SSN Protection

Full SSN is never returned in API responses. Only ssn_last_four is available. The field-level RBAC system includes a deny rule on SSN write access for all roles.

do_not_contact Flag

When set to True, the borrower receives zero automated communications:

  • All dunning communications are suppressed
  • Automated payment reminders are blocked
  • Collection actions cannot generate outbound contacts
  • Manual communications must be explicitly overridden

This flag is respected system-wide across Communications, Collections, and Case Management.

Language and Communication Preferences

  • language_preference drives template resolution for Communications and PDF generation
  • communication_preferences determines the preferred channel (email, mail, phone, SMS) for automated messages
  • Both are used by the borrower portal for personalization

Contacts (Generic Relations)

Addresses, email contacts, and phone contacts attach to borrowers (and other entities) via Django's contenttypes framework (GenericForeignKey):

Addresses

  • Street line 1 and 2, city, state, postal code, country
  • Labels: home, work, mailing
  • One marked as primary per borrower
  • Used for letter delivery and compliance reporting

Email Contacts

  • Email address with label (home, work)
  • One marked as primary
  • Verification tracking (is_verified)
  • Used for email communications

Phone Contacts

  • E.164 format via django-phonenumber-field
  • Labels: home, work, mobile
  • Phone type: mobile, home, work, fax
  • One marked as primary
  • Used for SMS and phone-based collection actions

Loan Parties

Multiple parties can be linked to a single loan with specific roles and liability types:

Role Liability Description
borrower Primary One required per loan
co_borrower Joint or individual Shared liability
co_signer Joint or individual Credit support
guarantor Full, limited, or partial Guarantee amount checked during servicing
authorized_representative None Can act on borrower's behalf

Liability types determine how obligations are shared:

Liability Type Description
primary Full responsibility for the loan
secondary Responsible only if primary defaults
joint Equally responsible with other parties

Payment Instruments

Payment methods stored for borrowers:

Field Description
instrument_type Bank account or credit/debit card
account_number_masked Masked account number for display
routing_number Bank routing number (ACH)
is_default Default payment method

Payment instruments are used by Payment Processing and auto-pay plans.

Autopay Plans

Recurring auto-payment configuration linked to a borrower's payment instrument:

Field Description
frequency Monthly, bi-weekly, weekly, quarterly
next_payment_date Next scheduled payment
amount_type Minimum due, full balance, or fixed amount
fixed_amount Amount (if fixed)
is_active Whether autopay is currently enabled

Borrower Identities

Identity documents for KYC/compliance:

Document Type Examples
passport International passport
drivers_license State-issued driver's license
ssn_card Social Security card
state_id State identification card
military_id Military identification

Each record stores document number, issuing authority, issue date, and expiration date.

Borrower Consents

Consent records for regulatory compliance:

Consent Type Purpose
credit_check Authorization to pull credit report
electronic_communications E-SIGN consent for electronic delivery
privacy_policy Acknowledgment of privacy policy
terms_of_service Agreement to terms
marketing Opt-in for marketing communications

Each consent records the type, granted date, IP address, and user agent.

Business Detail

For commercial borrowers, additional business information:

  • Business name, EIN, entity type (LLC, corporation, sole proprietorship, etc.)
  • Formation date, state of formation
  • Industry, annual revenue
  • Number of employees

Legal representative records for borrowers under legal representation:

Representative Type Use Case
attorney Legal counsel
executor Estate management
power_of_attorney POA holder
guardian Legal guardian
trustee Trust management

When a legal representative is active, communications may need to be directed through them.

Portal User Mapping

Borrowers can be linked to a portal user account via the portal_user FK, enabling self-service access through the borrower portal. See the portal backend (apps.portal) for the self-service API.

See Also