> ## Documentation Index
> Fetch the complete documentation index at: https://docs.command.cleargrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Borrower Management
> Complete 360-degree borrower profiles with smart search, bulk import, and full audit trails
Every collection operation starts and ends with the borrower. Command's Borrower Management module gives you a complete, 360-degree view of every individual in your portfolio — their contact details, account balances, payment history, communication logs, and timeline of every interaction your team has ever had with them. No more switching between spreadsheets, email inboxes, and phone logs. Everything lives in one place.
Whether you're onboarding thousands of borrowers via bulk import or updating a single phone number, Borrower Management is built to handle it efficiently and accurately.
## The Borrower Data Model
Understanding how borrower data is structured in Command helps you navigate profiles faster and make the most of search, filters, and reporting. Here's how the key entities relate to each other:
```mermaid theme={null}
erDiagram
BORROWER ||--o{ CONTACT : "has"
BORROWER ||--o{ ACCOUNT : "owns"
BORROWER ||--o{ COMMUNICATION : "receives"
BORROWER ||--o{ DEAL : "linked to"
BORROWER ||--|| TIMELINE : "tracked in"
BORROWER {
string id PK
string firstName
string lastName
string email
string phone
date dateOfBirth
string address
date createdAt
}
CONTACT {
string id PK
string type "Phone, Email"
string value
string label "Primary, Work, Personal"
boolean isPrimary
}
ACCOUNT {
string id PK
string accountNumber
decimal balance
decimal amountPaid
string status "Active, Partial, Paid, Defaulted"
date dueDate
}
COMMUNICATION {
string id PK
string channel "WhatsApp, Email, SMS, Voice"
string direction "Inbound, Outbound"
string content
datetime timestamp
}
DEAL {
string id PK
string stage "New, Contacted, PTP, Paid, Closed"
string assignedAgent
decimal amount
date lastActivity
}
TIMELINE {
string id PK
string eventType
string description
datetime timestamp
string triggeredBy
}
```
**How borrowers, deals, and accounts relate:** A single borrower can have multiple accounts (e.g., a personal loan and a credit card). Each account can be associated with one or more deals. Deals track the collection effort for a specific debt, while accounts represent the financial instrument itself. This separation lets you manage complex portfolios where one borrower may have debts across different products or lenders.
## Key Capabilities
Command's Borrower Management module is packed with features designed for collection teams of any size. Here's what you can do:
Every borrower has a rich profile containing personal information, addresses, identification documents, custom attributes, and notes. Profiles are fully editable with a complete audit trail — every change is logged with a timestamp and the user who made it.
Find any borrower in seconds. Search by name, phone number, email, account number, or any custom field. Results appear as you type, with fuzzy matching to handle typos and partial inputs. Save frequent searches as presets for one-click access.
Track every financial account associated with a borrower: balances, payment status, due dates, and transaction history. Sub-accounts let you manage multiple debts under a single borrower profile without losing granularity.
Import thousands of borrowers from CSV files with intelligent column mapping and duplicate detection. Bulk-assign borrowers to agents, update stages, or export filtered lists for external reporting. Built for portfolios of any scale.
A chronological record of everything that has happened with a borrower — from the moment they were created through every call, message, stage change, payment, and note. The timeline is the single source of truth for any compliance or audit question.
Every organization has unique data needs. Custom fields let you add borrower attributes specific to your business — whether that's a loan product type, a regional code, a risk score, or anything else. Custom fields are fully searchable and filterable.
## The Borrower Profile
When you click on a borrower from the list view, you open their full profile — a multi-tabbed interface that organizes information into logical sections.
The Overview tab is your starting point. It shows:
**Personal Information**
* Full name, date of birth, and identification details
* Primary and secondary addresses
* Preferred language and communication preferences
**Account Summary**
* Total outstanding balance across all accounts
* Total amount paid to date
* Last payment date and amount
* Number of active accounts
**Quick Actions**
* Send WhatsApp message
* Compose email
* Initiate voice call
* Add a note
* Move to a different stage
The Overview tab is designed for speed. You should be able to assess a borrower's situation and take the next action within 30 seconds of opening their profile.
The Accounts tab lists every financial account associated with this borrower, each displayed as an expandable card.
**For each account, you'll see:**
* Account number and type
* Current balance and original amount
* Payment status (Active, Partial Payment, Paid in Full, Defaulted, Written Off)
* Due date and days past due
* Transaction history (payments, adjustments, fees)
**Actions:**
* Add a new sub-account
* Edit account details
* Record a manual payment
* View full transaction history
* Download account statement
Accounts are color-coded by status. Green borders indicate Paid in Full, amber indicates Partial Payment, and red indicates Defaulted. This visual coding helps agents prioritize at a glance.
The Communication tab is a unified inbox for every interaction with this borrower, across every channel.
**Channels displayed:**
* WhatsApp messages (with read receipts)
* Email threads (with open/click tracking)
* SMS messages (with delivery status)
* Voice call logs (with duration, recording links, and notes)
**Features:**
* Filter by channel, date range, or direction (inbound/outbound)
* Search within conversation history
* Replay call recordings inline
* View email open and click analytics
* Send a new message directly from this tab
Before calling a borrower, always check the Communication tab to see what was discussed in previous interactions. Context prevents redundant conversations and shows the borrower you value their time.
The Timeline tab provides a chronological, event-by-event history of everything that has ever happened with this borrower.
**Event types tracked:**
| Event | Icon | Example |
| ----------------- | ---- | ------------------------------------------------------ |
| Profile created | 🟢 | "Borrower created via bulk import" |
| Stage change | 🔄 | "Moved from New → Contacted by Agent Sarah" |
| Communication | 💬 | "WhatsApp message sent: Payment reminder" |
| Payment received | 💰 | "Payment of \$500.00 recorded on Account #1234" |
| Note added | 📝 | "Agent Mike: Borrower requested callback Thursday" |
| Assignment change | 👤 | "Reassigned from Agent Tom to Agent Lisa" |
| Account update | 📊 | "Account #1234 balance adjusted from $5,000 to $4,500" |
Each event includes a timestamp, the user who triggered it, and a link to the related entity (deal, account, or communication).
The Timeline is immutable — events cannot be edited or deleted. This ensures a complete and trustworthy audit trail for compliance purposes.
## Account Statuses Explained
Every account in Command has a status that reflects its current state. Understanding these statuses helps you prioritize outreach and report accurately.
The account has an outstanding balance and is within its normal collection window. These are your primary targets for outreach — the borrower has an obligation and it's not yet overdue (or only recently overdue).
The borrower has made one or more payments, but the balance is not fully settled. This is a positive signal — the borrower is engaged. Follow-up communication should acknowledge the payment and encourage completion.
The account balance has been fully recovered. No further collection action is needed. These accounts remain in the system for record-keeping and reporting but are typically excluded from active worklists.
The account has passed its final collection deadline without being resolved. Defaulted accounts may be escalated to legal proceedings, transferred to a secondary agency, or written off depending on your organization's policies.
The account has been deemed uncollectible and removed from active collection efforts. Written-off accounts are retained in the system for regulatory reporting and audit purposes.
Account status transitions are logged in the Timeline and cannot be reversed without admin approval. Be certain before marking an account as Written Off or Defaulted.
## Data Integrity and Relationships
**Duplicate detection:** When you create or import a borrower, Command automatically checks for existing records with matching phone numbers or email addresses. If a potential duplicate is found, you'll be prompted to merge the records or proceed with the new entry. This prevents fragmented data and ensures every borrower has a single, complete profile.
Command enforces referential integrity across all entities. Deleting a borrower (which requires Super Admin permission) cascades through related records according to your organization's data retention policies. In most configurations, borrower records are soft-deleted — they're hidden from active views but preserved in the database for compliance.
## Finding Borrowers
Command offers three ways to find borrowers, each designed for different situations. Whether you need to pull up a specific person in two seconds or narrow down a list of thousands, there's a tool for the job.
The search bar at the top of the Borrowers page is your fastest path to any record. Start typing and results appear instantly.
**What you can search by:**
* Full name or partial name (e.g., "John" matches "John Doe" and "Johnny Smith")
* Phone number (with or without country code)
* Email address (full or partial)
* Account number (exact match)
* Custom field values
**How it works:**
1. Click the search bar or press `/` to focus it
2. Start typing — results appear after 2 characters
3. Results are ranked by relevance, with exact matches at the top
4. Click a result to open the borrower's profile
5. Press `Esc` to clear the search
Quick Search supports fuzzy matching. If you're not sure about the spelling ("Mhd" vs "Mohamed"), type what you know — Command will find the closest matches.
Filters let you narrow the borrower list based on specific criteria. They're ideal for building worklists — for example, "show me all borrowers in the Contacted stage assigned to me with balances over \$5,000."
**Available filter options:**
| Filter | Description |
| ------------------ | ------------------------------------------------------------- |
| **Stage** | Filter by deal stage (New, Contacted, Promise to Pay, etc.) |
| **Date Range** | When the borrower was created or last updated |
| **Lender** | Which lender the borrower belongs to (admin only) |
| **Assignment** | Filter by assigned agent |
| **Amount Range** | Outstanding balance minimum and/or maximum |
| **Account Status** | Active, Partial Payment, Paid in Full, Defaulted, Written Off |
| **Last Contact** | How recently the borrower was last contacted |
| **Custom Fields** | Any custom attributes your organization has defined |
**Combining filters:** All filters are additive (AND logic). Selecting Stage = "Contacted" and Amount > \$5,000 shows borrowers who match both criteria.
Save frequently used filter combinations as **Presets**. Click the star icon next to the filter bar to name and save your current filters. Access them from the **Saved Filters** dropdown.
Advanced Search gives you the most control. It opens a dedicated panel where you can build complex queries with multiple conditions, grouping, and sorting.
**Features:**
* Combine conditions with AND / OR logic
* Group conditions with parentheses for complex queries
* Sort results by any field (ascending or descending)
* Choose which columns to display in results
* Export search results directly to CSV
**Example query:**
> Show borrowers where (Stage = "Promise to Pay" AND last contact > 7 days ago) OR (Stage = "Contacted" AND balance > \$10,000), sorted by balance descending.
Click the **Advanced** button next to the filter bar, or press `Ctrl + Shift + F`.
Click **+ Add Condition** to add a filter row. Select the field, operator, and value.
Select multiple conditions and click **Group** to wrap them in parentheses with an AND/OR connector.
Choose a field to sort by and select ascending or descending.
Click **Search**. Results appear in the table below with your chosen columns.
Advanced Search queries can be saved as presets just like regular filters. They also generate a shareable URL — send it to a colleague so they see the same results.
## Creating a New Borrower
Adding a borrower to Command takes less than a minute. Here's the full process:
Creating borrowers requires the **CREATE\_BORROWER** permission. If you don't see the "New Borrower" button, contact your admin to check your role configuration.
The button is in the top-right corner of the Borrowers page. Clicking it opens a slide-out form on the right side of the screen.
Enter the borrower's core details:
| Field | Required | Notes |
| ----------------- | -------- | -------------------------------------- |
| **First Name** | Yes | Legal first name |
| **Last Name** | Yes | Legal last name |
| **Phone** | Yes | Include country code (e.g., +1 for US) |
| **Email** | No | Used for email communications |
| **Date of Birth** | No | Helps with identity verification |
| **Address** | No | Street, city, state, zip code |
The phone number is used as a unique identifier for duplicate detection. Always include the country code to avoid false duplicate matches.
Below the personal information section, click **+ Add Account** to attach the borrower's first financial account.
| Field | Required | Notes |
| ------------------- | -------- | ------------------------------------ |
| **Account Number** | Yes | Your internal reference number |
| **Original Amount** | Yes | The original debt amount |
| **Current Balance** | Yes | Outstanding amount owed |
| **Due Date** | No | When the payment is due |
| **Lender** | Yes | Which lender this account belongs to |
You can add multiple accounts at creation time or add them later.
Choose the starting deal stage for this borrower. Most new borrowers begin at **New**, but if you have prior context (e.g., they were transferred from another system where contact was already made), you can select a more advanced stage like **Contacted**.
Scroll through the form to verify all information is correct. Click **Create Borrower** at the bottom. Command will:
1. Check for duplicate phone numbers and emails
2. Validate all required fields
3. Create the borrower profile
4. Create the associated account(s)
5. Generate a timeline entry: "Borrower created by \[your name]"
6. Redirect you to the new borrower's profile page
After creation, the borrower is immediately available in search, filters, and reports. If the borrower is assigned to a lender, they'll also appear on that lender's Dashboard metrics in real time.
## Editing Borrower Information
Keeping borrower data accurate is critical for effective collections. Here's how to update any field:
Find the borrower using Quick Search, filters, or your worklist. Click their name or card to open the full profile.
Look for the pencil icon in the top-right corner of the profile page, or click the **Edit** button next to any section header.
The form switches to edit mode. Update any field — name, phone, email, address, custom fields, or notes. Changed fields are highlighted with a blue border so you can see what you've modified.
Click **Save** at the bottom of the form. Command automatically:
* Validates the updated data
* Checks for duplicate conflicts (if phone or email changed)
* Saves the changes
* Logs the edit in the Timeline with a before/after diff
* Updates all related views and reports
Every edit is logged in the borrower's Timeline, including who made the change, when, and what the old and new values were. This audit trail is immutable and available to admins for compliance review.
## Managing Multiple Contacts
Borrowers often have more than one phone number or email address — a personal cell, a work number, a spouse's email, etc. Command supports unlimited contacts per borrower.
### Adding a New Contact
1. Open the borrower's profile and navigate to the **Contact Information** section
2. Click **+ Add Phone** or **+ Add Email**
3. Enter the contact value
4. Select a label: **Primary**, **Work**, **Personal**, **Alternate**, or **Other**
5. Click **Save**
### Setting a Primary Contact
The primary contact is used by default for all outbound communications (WhatsApp, SMS, email).
* Click the **star icon** next to the contact you want to make primary
* The previous primary contact is automatically demoted to "Alternate"
* A confirmation toast appears: "Primary contact updated"
### Contact Best Practices
| Do | Don't |
| ---------------------------------- | ---------------------------------------- |
| Verify numbers during each call | Assume old numbers are still valid |
| Ask about preferred contact method | Send messages to every number |
| Update labels when roles change | Leave generic "Alternate" labels forever |
| Mark invalid numbers as inactive | Delete numbers — deactivate them instead |
Deactivating a contact (rather than deleting it) preserves the communication history associated with that number or email. Deleting a contact removes it permanently.
## Bulk Import
When onboarding a new portfolio or migrating from another system, bulk import lets you add hundreds or thousands of borrowers in a single operation.
Download the import template from Command (click **Import** → **Download Template**) or structure your CSV to match the required format:
```csv theme={null}
first_name,last_name,phone,email,account_number,original_amount,current_balance,due_date,stage
John,Doe,+12125551234,john.doe@example.com,ACC-001,5000.00,4500.00,2026-03-15,New
Jane,Smith,+12125555678,jane.smith@example.com,ACC-002,12000.00,12000.00,2026-04-01,New
Robert,Johnson,+12125559012,r.johnson@example.com,ACC-003,3200.00,1600.00,2026-02-28,Contacted
Maria,Garcia,+12125553456,m.garcia@example.com,ACC-004,8750.00,8750.00,2026-05-10,New
```
**Required columns:** `first_name`, `last_name`, `phone`, `account_number`, `current_balance`
**Optional columns:** `email`, `original_amount`, `due_date`, `stage`, `date_of_birth`, `address_line_1`, `city`, `state`, `zip_code`, and any custom fields defined by your organization.
Phone numbers must include the country code (e.g., +1 for US, +91 for India). Rows without a valid country code will be flagged during validation.
On the Borrowers page, click the **Import** button in the top toolbar. This opens the import wizard — a step-by-step modal that guides you through the entire process.
Drag and drop your file into the upload area, or click **Browse** to select it from your file system. Command accepts `.csv` and `.xlsx` files up to 10 MB (approximately 50,000 rows).
For files larger than 10 MB, split them into multiple files and import sequentially. Each import runs independently.
Command auto-detects column mappings when your headers match the template. For non-standard headers, manually map each column:
* Select a Command field from the dropdown next to each CSV column
* Mark columns to skip with **Ignore this column**
* Preview the first 5 rows to verify the mapping looks correct
Double-check the phone number mapping. If phone numbers are mapped to the wrong column, duplicate detection won't work and you may create duplicate records.
Click **Validate** to run a pre-import check. Command scans every row for:
* Missing required fields
* Invalid phone number formats
* Invalid email formats
* Duplicate records (both within the file and against existing borrowers)
* Data type mismatches (e.g., text in a number field)
A validation report shows the number of valid rows, warnings, and errors. You can download the report as a CSV for review.
| Status | Meaning | Action |
| ---------- | ------------------------------------------------- | ---------------------------- |
| ✅ Valid | Row passes all checks | Will be imported |
| ⚠️ Warning | Non-critical issue (e.g., missing optional field) | Will be imported with a note |
| ❌ Error | Critical issue (e.g., missing phone) | Will be skipped unless fixed |
Review the validation summary and click **Start Import**. Command processes the file in the background — you can navigate away and return later.
* A progress bar shows real-time status
* Successfully imported borrowers appear in the list immediately
* Skipped rows are collected in an error report you can download
* A summary email is sent to you when the import completes
After import, spot-check 5–10 random borrower profiles to verify data quality. Look at phone formats, account balances, and stage assignments.
## The Borrower Creation Flow
Here's a visual overview of what happens when a new borrower is created — whether manually or via import:
```mermaid theme={null}
flowchart TD
A[New Borrower Data] --> B{Validate Required Fields}
B -->|Missing fields| C[Return Validation Error]
B -->|All valid| D{Check for Duplicates}
D -->|Duplicate found| E{User Decision}
E -->|Merge| F[Merge with Existing Record]
E -->|Create anyway| G[Create as New Record]
E -->|Cancel| H[Abort Creation]
D -->|No duplicate| G
G --> I[Create Borrower Profile]
I --> J[Create Associated Account]
J --> K[Assign to Lender]
K --> L{Agent Assignment}
L -->|Auto-assign| M[Assign to Agent via Round-Robin]
L -->|Manual| N[Admin Assigns Agent Later]
M --> O[Borrower Ready]
N --> O
O --> P[Appears in Dashboard & Worklists]
style A fill:#3b82f6,stroke:#2563eb,color:#fff
style G fill:#10b981,stroke:#059669,color:#fff
style O fill:#10b981,stroke:#059669,color:#fff
style C fill:#ef4444,stroke:#dc2626,color:#fff
style H fill:#6b7280,stroke:#4b5563,color:#fff
```
## Best Practices
Outdated phone numbers and email addresses are the single biggest time-waster in collections. Make it a habit to verify contact details at the start of every interaction. If a number is disconnected, mark it as inactive and ask the borrower for an updated contact. Clean data means fewer wasted calls, fewer bounced emails, and higher engagement rates.
Every interaction should leave a trail. After a call, jot down the key points: what was discussed, what the borrower promised, and what the next step is. Notes are visible to any agent who works with the borrower in the future, which means smoother handoffs and no repeated conversations. Treat notes as a conversation with your future self (or your colleague).
Custom fields aren't just extra data — they're a segmentation tool. Add fields like "Risk Score," "Product Type," or "Region" and use them in filters to build targeted worklists. For example, filter by "Risk Score = High" and "Last Contact > 7 days" to find your highest-priority, least-recently-contacted borrowers.
Schedule a monthly review of your borrower data. Look for profiles with no activity in 90+ days, accounts that should be written off, and contacts marked as inactive. Clean portfolios generate more accurate metrics and prevent agents from wasting time on dead-end records.
Speed matters when you're working through a worklist of 100+ borrowers a day. Learn the shortcuts:
| Shortcut | Action |
| ---------- | ----------------------------- |
| `/` | Focus the search bar |
| `N` | Open "New Borrower" form |
| `E` | Edit current borrower profile |
| `Ctrl + S` | Save changes |
| `Esc` | Close modal or cancel edit |
| `↑` / `↓` | Navigate borrower list |
| `Enter` | Open selected borrower |
When you need to reassign 200 borrowers to a new agent, don't do it one by one. Select multiple borrowers using checkboxes (or `Ctrl + A` to select all in the current filter view) and use the **Bulk Actions** menu to reassign, change stage, or export. Bulk operations are logged individually in each borrower's timeline for full traceability.
## Troubleshooting
**Possible causes:**
1. **Permission issue:** You need the `EDIT_BORROWER` permission. Check with your admin.
2. **Record is locked:** Another user may be editing the same borrower. Command locks records during editing to prevent conflicts. Wait a moment and try again, or ask your admin to release the lock.
3. **Borrower belongs to another lender:** If you're a lender-level user, you can only edit borrowers assigned to you. Contact a super admin if you need access to a borrower outside your portfolio.
4. **Browser issue:** Try refreshing the page or clearing your browser cache. In rare cases, a stale session can prevent edits from saving.
When Command detects a potential duplicate (matching phone or email), you'll see a warning dialog with three options:
1. **View the existing record:** Click the link to open the existing borrower's profile. Compare it with the data you're trying to enter.
2. **Merge:** If it's truly the same person, click **Merge**. Command will combine the two records, keeping the most recent data and merging communication histories.
3. **Create anyway:** If it's a different person with the same phone/email (e.g., a shared family number), click **Create Anyway**. The new borrower will be created with a note about the potential duplicate.
To prevent duplicates during bulk import, always run the validation step and review the duplicate report before starting the import.
**If the import fails entirely:**
1. Check that your file is a valid CSV or XLSX (open it in a text editor to verify formatting)
2. Ensure the file is under 10 MB
3. Check that required columns (`first_name`, `last_name`, `phone`, `account_number`, `current_balance`) are present
4. Verify there are no encoding issues (save as UTF-8)
**If the import partially completed:**
1. Download the error report from the import summary screen
2. Review each failed row — the report includes the specific error for each
3. Common errors: missing required fields, invalid phone format, duplicate records
4. Fix the issues in your CSV and re-import only the failed rows
Do not re-import the entire file if the import partially completed — this will create duplicates for the rows that succeeded the first time. Only re-import the failed rows.
**Possible causes:**
1. **Typo in the search query:** Try searching by phone number or account number instead of name.
2. **Active filters hiding the result:** Check if any filters are applied (look for the filter badge in the toolbar). Click **Clear Filters** to reset.
3. **Borrower belongs to another lender:** If you're a lender-level user, you can only see your own borrowers. Ask a super admin to verify.
4. **Borrower was soft-deleted:** If a super admin deleted the borrower, they won't appear in normal searches. Admins can check the "Deleted Records" section.
5. **Indexing delay:** Very recently created borrowers (within the last 30 seconds) may not yet appear in search results. Wait a moment and try again.
Custom fields need to be explicitly marked as "filterable" when they're created. Contact your admin and ask them to:
1. Go to **Settings** → **Custom Fields**
2. Find the field in question
3. Toggle **Searchable** and **Filterable** to ON
4. Save the changes
After this, the field will appear in the filter dropdown on the Borrowers page.
## Frequently Asked Questions
Command is built for scale. Customers routinely manage portfolios of 100,000+ borrowers with no degradation in search speed or page load times. The underlying database is optimized for collection-specific query patterns, and search indexing is updated in near-real-time.
Yes — if the borrower was soft-deleted (the default). Super admins can restore soft-deleted borrowers from the **Deleted Records** section in Settings. Hard deletions (permanent removal from the database) are irreversible and require explicit Super Admin confirmation.
Command checks for duplicates based on phone number and email address. During manual creation, the check happens in real time as you type. During bulk import, the check runs during the validation step. The matching algorithm normalizes phone numbers (removing spaces, dashes, and standardizing country codes) to catch duplicates even when formatting differs.
Yes. Use the **Export** button on the Borrowers page to download the current filtered view as a CSV or Excel file. Exports include all visible columns plus any custom fields. For full-portfolio exports, apply no filters before exporting. Large exports (50,000+ rows) are processed in the background and delivered via email.
Merging combines two profiles into one. Command keeps the most recent personal information, merges all contacts (deduplicating), combines account records, and unifies the communication history and timeline from both profiles. The "source" profile is soft-deleted after the merge, and a timeline event records the merge with a link to the original record.
Each organization can create up to 50 custom fields. Each field can be a text, number, date, dropdown (single or multi-select), or boolean type. If you need more than 50 fields, contact support — we can increase the limit for enterprise accounts.
***