Client Database Organization Wizard

Client Database Organization Wizard

Overview

The DB Wizard is a guided tool for cleaning and improving a messy client database. It walks users through a fixed sequence of cleanup steps and then provides a database health scorecard. It focuses on three main areas:

• Delete: Removes inappropriate or unusable records, such as colleagues listed as clients and contacts with no phone or email.
• Consolidate: Merges duplicate people and links contacts of the same household as relationships.
• Enrich: Connects past sales to clients, creates market updates, and collects missing information such as birthdays and mailing addresses.

The first half of the Wizard makes your database smaller and cleaner. The second half makes it richer. Everything destructive happens in the first half, and everything in the first half can be reversed from the Activity Log.

Screens

There are a total of 11 stages to clean up the database. They are as follows

Remove Colleagues

Here is a list of colleagues who are also listed as clients in your database. Use this step to remove them from your client database. 

This step identifies and removes clients from the database whose contact information overlaps with known colleagues. A client is surfaced only when all three of the following conditions are met:

• Email address matches a colleague's email
• Phone number matches a colleague's phone
• First name OR last name matches the colleague's name

Clients that do not satisfy the full criteria are not shown, even if there is a partial match.

UI/What's displayed

Each card shows the matched client's contact details alongside the colleague they were matched against. A View Colleague button opens a popup with the full colleague record for verification before taking action.

Actions available to remove the clients:

• Individual selection — select/deselect one or more clients using checkboxes
• Select/deselect all — select/deselect every matched client within the loaded pages at once

Once a selection is made, clicking Remove Colleagues removes the selected clients from the database.

Navigation

You can move to the previous or next step at any time without performing any deletions. No action is required to proceed. Prev and Skip & Next will be disabled until all the selected clients are deleted. You’ll be on the same step till all the data is loaded onto the UI.

This step is recorded in the Activity Log as Remove Colleagues and can be reversed.

Previous screen: DB Wizard Start page

Next screen: Remove Incomplete Contacts.

Remove Incomplete Contacts

Contacts that have neither a phone number nor an email address can be removed from here.

UI / What's displayed

Each row on the UI shows the contacts with missing email and phone number. Rows show full name, stage, source, last activity and created date so you can sanity-check before deleting. 

Everything you have loaded arrives already ticked, so untick the ones you want to keep.

Results can be filtered using the search field, allowing you to find clients by name.

Actions available to remove the clients

• Individual selection — select/deselect one or more clients using checkboxes
• Select/deselect all — select/deselect every matched client within the loaded pages at once

Once a selection is made, clicking Remove Contacts removes the selected clients from the database. The deletion process runs in the background.

Navigation

• You do not have to load the whole list. Skip & Next is available regardless of how many pages remain, anything you did not reach stays in your database and the step is reachable again from the menu.
• Back and Skip & Next are disabled while the removal you submitted is still running, this is to prevent the same clients from being processed again in a subsequent stage.. This holds for menu jumps and direct links too.
• Auto-advance: if you are on the last page, no search is active, and your final batch completes cleanly, the Wizard moves you to the next step by itself.
• This step is recorded in the Activity Log as Incomplete Contacts and can be reversed.

Previous screen: Remove Colleagues

Next screen: Merge Contacts (email & phone)

Merge Contacts (email and phone)

This stage groups contacts by emails and phone numbers. A group is formed when contacts share any email address or any phone number. Groups can be directly linked to each other or can be indirectly linked.

Direct groups: If A shares an email/phone number with B, then A and B are direct groups.

Indirect groups: If A shares an email with B, and B shares a phone number with C, all three land in one group, even though A and C have nothing in common.

Here we select the one contact from the group as primary contact and merge all other associated contacts(secondary contacts) into that account. The merged secondary contacts will be either merged as relations or will be deleted.

There are two ways of merging the contacts.

• Merge as single contacts: The secondary contact’s data and relationships are merged into the primary contact. The secondary contact is then deleted from the local database and moved to the Trash stage in FUB.
• Merge as relationships: The secondary contact and its relationships are added as relationships to the primary contact. The secondary contact’s data remains associated with the primary contact.

Before the step opens

When entering this step, an automatic preparation screen is displayed while the system scans the database for potential duplicates. This process may take a few seconds, and the Wizard automatically moves to the next step once it is complete.

For small databases, the process completes within the request. For larger databases, it runs in the background, and the Wizard automatically proceeds once the process is complete. If you navigate back to this step, the duplicate groups are rebuilt from scratch because previous merges may have changed the duplicates list. As a result, the Loading screen is displayed again.

UI / What's displayed

A Duplicate List header with a running total, for example "48 Duplicates". This is the number of groups found across the whole database, not the number currently loaded on screen. A search box beside it filters the groups by client name.

Below the header, one card per group. Inside each card, every person in the group is shown as a tile with their information.

A person included in the merge is shown with a green border and a check badge in the corner of their tile. Clicking a tile includes or excludes that person from the merge.

Large groups are truncated. If a group holds more people than the card displays, a counter appears reading "12 of 40", with the tooltip "Large group, showing 12 persons."

Load More at the bottom pulls the next 25 groups. When there is nothing to review, the screen reads "No duplicates found."

The checkbox at the top left of each group helps to exclude or include that group with a single click.

What you set on a group before merging:

• Included people — everyone in the group is included by default. Click the tile checkbox to drop someone out; they stay in your database untouched and simply do not take part in this merge.
• Primary — the first person listed is the primary by default. This is the record that survives the merge, so it decides which record keeps its identity and history. Selecting “Primary” on an excluded person pulls them back into the group, and dropping the current primary promotes the next remaining person automatically.
• Merge mode — Merge into single contact is selected by default. The alternative is Merge as relationships.

Actions available

Merge — applies that card's settings to that group alone. The button is disabled until at least two people are selected and a primary is set.

Dismiss — nothing is merged and nothing is deleted. The group is recorded as reviewed, disappears from the list, and the group count drops by one. Use it whenever the system has grouped two genuinely different people. Dismiss is applied immediately, with no background work to wait for.

Merge Contacts (footer) — handles every group currently loaded in one action. The confirmation reads "You are about to merge 24 of 1022 groups. Are you sure you want to proceed?", where the first number counts the loaded groups still eligible to merge and the second is the total found. Each group keeps its own primary, its own exclusions and its own merge mode, groups left with fewer than two people are skipped.

Merges run in the background. The group leaves the list immediately, a message confirms "1 group queued for merging. You can keep going", and a banner reports progress while the work runs. A single submission carries at most 1,000 groups.

Navigation

Back and Skip & Next are disabled until the merges you submitted have finished running. An active search also blocks Skip & Next. Blank the search filter and press Enter to remove the filter.

This step is recorded in the Activity Log as Merge Contacts (email & phone) and can be reversed. Reversing a merge from this step restores the contacts, the Wizard rebuilds the duplicate groups when you close the Activity Log.

Previous screen: Remove Incomplete Contacts

Next screen: Merge Contacts (full name)

Merge Contacts (full name)

This is the same screen as the previous step with one rule changed. Contacts are grouped when they share an identical full name, and nothing else. No email or phone condition is applied.

Similar to the previous stage, the contacts can be merged through two ways: Merge as single contacts and Merge as relationships.

UI / What's displayed

Identical to Merge Contacts (email and phone): a Duplicate List header with a running total, a search box, one card per group with person tiles laid out two across, Make Primary radio buttons, the "12 of 40" counter on truncated groups, per-card Dismiss and Merge buttons, Load More at 25 groups a time, and the "No duplicates found" for empty state.

There is no preparation screen on this step. The groups were already built during the previous step's generation pass, so this step simply loads its list.

The checkbox at the top left of each group helps to exclude or include that group with a single click.

Actions available

The same three actions as the previous step — Merge and Dismiss on a single group, or Merge Contacts in the footer for every group currently loaded.

The defaults are also the same: everyone in the group is included, the primary is the first person listed, and the merge mode is Merge into single contact.

Navigation

Back and Skip & Next are disabled until the merges you submitted have finished running. An active search blocks Skip & Next.

Back from this step is not immediate. Going back forces the email and phone groups to be regenerated, so the Loading screen is displayed on the way.

This step is recorded in the Activity Log as Merge Contacts (full name) and can be reversed. Unlike the previous step, no rebuild is needed afterwards: the group survives the merge, so the list simply refetches.

Previous screen: Merge Contacts (email & phone), via a group rebuild

Next screen: Merge Relationships

Merge Relationships

This is the same screen as the previous two merge steps with one rule changed. This stage groups contacts by their full name.

The last name grouping rule:

• Single-character last names are not allowed.
• Numbers are not allowed.
• Other special characters are not allowed.
• Leading or trailing apostrophes (') or hyphens (-) are not allowed.
• Accent Latin letters, apostrophes ('), and hyphens (-) are supported because they are valid in real-world last names.
  • Examples: Alexander-Yzaguirre, Boyér, Adán, O'Brien, etc.

UI / What's displayed

It's the same as the previous two merge screens.

Actions available

Merge and Dismiss on a single group, or Merge Relationships in the footer to handle every group currently loaded.

The default merge mode is different on this step. Merge as relationships is pre-selected here, rather than Merge into single contact.

Navigation

Back and Skip & Next are disabled until the merges you submitted have finished running. An active search blocks Skip & Next.

This is the last step with an Activity Log. It is recorded as Merge Relationships and can be reversed.

Previous screen: Merge Contacts (full name)

Next screen: Fetch Sales

Fetch Sales

This step pulls your past closings into the Wizard so the remaining steps have something to work with. You choose how far back to look, and the fetch runs in the background. Nothing is deleted and no contact record is changed here.

How the data is fetched

The Wizard pulls your closings from three places and combines them.

Deals — your closed and completed transactions, taken from the records we already hold. These are limited to deals closed on or after your joining date, and on or after the start date you selected.

The MLS — closings where your MLS ID appears as either the buyer's agent or the listing agent. Whether a sale is recorded as a buyer or a seller is decided by which of those two roles your MLS ID holds on the listing.

Tax records — for each property address found, the Wizard looks up the property and tax record. This supplies the property details shown on the Match Sales screen, bedrooms, bathrooms, square footage, year built, assessments, tax history and sale history. For buyer-side sales where no client with a mailing address is already attached, it also supplies the tax owner names and the owner's mailing address, which are what appear in the Tax Owners / Deal Clients column.

Re-running the fetch is safe. Sales already fetched are updated rather than replaced, and details captured on an earlier run are kept even if a later lookup returns nothing for that property. Nothing is duplicated and nothing is lost.

UI / What's displayed

A centred panel with a dropdown offering 1 Year through 10 Years, a Fetch button, and a live count underneath that updates as the dropdown changes: "182 transactions found in the last 5 years."

If the agent's MLS ID is missing, the dropdown, the Fetch button and the count are replaced by a warning: "The Wizard requires your MLS ID to fetch your past sales. Without it, you will not be able to proceed to  the next step. You can add it under the Account Settings tab in your profile."

Every step from here to the end of the Wizard depends on fetched sales, so a missing MLS ID makes Fetch Sales through DB Health unreachable. Navigating directly to a later step redirects back to this screen with the warning shown.

Navigation

The footer's contextual button is hidden on this screen. The Fetch button in the page body is the action. Prev and Skip & Next are available.

If the fetch fails, you are returned to this screen rather than left on the syncing screen.

Previous screen: Merge Relationships

Next screen: Match Sales

Match Sales

This step connects each closing to the client it belongs to. It is what makes the rest of the second half of the Wizard work. Market Updates, the missing info emails and the db health all depend on a sale having a client attached to it. It is also where a client's rating, mailing address and household details are recorded.

UI / What's displayed

A table of closings with the columns Client Type (buyer or seller), Property, Source (MLS or Deal), Closing date, Tax Owners / Deal Clients, and Action.

The whole row is clickable, and the Client Info button opens the same panel. 

The Client Info panel contains:

• Unmatched and Matched tabs with counts, so you can see how much is left. Prev, Next and Skip move within the active tab only.
• Client Name – search your existing clients, or Create Client when the person is not yet in the database.
• Ratings - the client's grade is set here.
• Mailing Address – select one, manage the list, or Skip for now. Only one mailing address is allowed, so selecting a new one changes the type of the existing mailing address to Other. The panel warns before it does this.
• Kids at home? – Yes, No or Not Sure.
• Property Details – tax and property data for the address, which can be printed.

Saving a match also creates a recurring yearly closing anniversary event for that property.

Where a sale is linked to a client who has since been deleted, the panel says so and offers to relink it: "Pick the client this sale belongs to, then save."

Leaving it as it is also acceptable, a sale on a deleted client is already left out of Market Updates and Missing Info.

Actions available

For each sale you can link an existing client, create a new client, or leave the sale unidentified.

Skip and Skip & Finish leave a sale exactly as it is, without saving.

After the last sale in a tab, a prompt asks "You've reviewed the last sale. Do you want to move to the next step?"

Navigation

The footer's primary button on this step is Update Client Info, which opens the panel at the first unmatched sale. Prev and Skip & Next are available.

Previous screen: Fetch Sales

Next screen: Create Market Updates

HPA Matching

If there are already created HPA events, the system matches sales with it using address and auto-link to that client.

When it runs

During the wizard's sales fetch, each time a new sale row is created. Sales already in the table are not matched again.

Which wizard sales it applies to

Only sales that have no linked client yet:

1. Deals: only when the deal has no client attached.
2. MLS sales: always, because MLS sales never come with a client.

Events used

The agent's Closing Anniversary events (buyer and seller) that have a property address.

Matching steps

1. The street number must match exactly.
2. The street name must be a close match. It passes if any of these is true:
   1. at least half the words are the same
   2. text similarity is 60% or more
   3. edit-distance similarity is 70% or more (Levenshtein distance - handles typo)

Short forms are expanded first (for example, "St" becomes "Street" and "Dr" becomes "Drive"). Unit numbers are ignored.

3. Only one event matches the address: the sale is linked to that client. No date check is done.
4. More than one event matches the address:
   1. Keep only events within ±30 days of the sale's close date. For events stored with the year 1904 (year unknown), only the month and day are compared.
   2. If any of those events are on the same side as the sale (buyer or seller), keep only those.
   3. Pick the event nearest to the close date.

5. Nothing qualifies: the sale stays unlinked.

Result. It sets linked_person_id on the sale and client_unknown = 0.

Market Updates

This step turns matched closings into recurring weekly market updates for the

linked clients. Nothing is deleted, this step only creates.

UI / What's displayed

A and A+ ratings are selected automatically and the user can change it from the top right.

The table then lists Create Market Update? (checkbox), Client Type, Client Name, Rating, Property, Closing and Existing Market Updates. The Existing Market Updates column shows up to two update titles and can be clicked to review or delete them.

Every row arrives selected. There is one row per sale, so a client with two closings in range appears twice. This is correct, because an update is created per property. Seller-side sales are excluded from this list.

Actions available

Deselect any sale that should not have an update created, then click Create Market Updates in the footer. The frequency will be set to weekly by default. Create Now performs the action.

With nothing selected, the footer button simply moves you to the next step.

Existing market updates can be reviewed and deleted from the same screen.

Navigation

Previous screen: Match Sales

Next screen: Email for Missing Info

Market Updates Creation Logic

A sale is used only if:

• it has a linked contact,
• it is a buyer sale, and
• that contact still exists.

Sales that fail any of these are skipped without an error.

Finding the property

1. It uses the sale's MLS ID. If there isn't one, it takes the MLS ID from the linked deal.
2. With an MLS ID: it loads the listing and saves it as the agent's subject property, or reuses it if already saved. The search area is picked in this order:

• the neighbourhood(s) that contain the property
• otherwise, its elementary school
• otherwise, its zip code

3. Without an MLS ID: it uses the RentCast data cached during the wizard's sales sync, looked up by address. The search area is a 1-mile radius around the property plus its zip code. It also saves a RentCast subject property, or reuses an existing one.
4. If neither source has the property, the sale is skipped.

Search filters

1. Same property type and sub-type (MLS path only)
2. Living area within ±15% of the subject property
3. Statuses: New, Pending, and Closed in the last 365 days
4. The agent's default MLS feed

What gets saved

1. One market update per sale
2. Title: the property address
3. Emails: weekly, with the agent not CC'd
4. source = 'wizard'

All records in a batch are inserted in one go.

After saving, for each update:

1. a market-update tag is added to the contact
2. the filter usage count is updated
3. a "created" note is posted to the contact

Errors. A failure on one sale is logged and skipped. The rest of the batch carries on.

Email for missing info

This step emails your clients to ask for the details you do not hold — their birthday, their mailing address and their household information.

Four ready-made templates exist, and the system selects the right one per client based on what is missing.

UI / What's displayed

Ratings must be selected first, as on the previous step. A running count appears in the header reading "8 of 14 selected", alongside the Ratings Filter button.

The table lists Send Email? (checkbox), Client Type, Client Name, Rating, Mailing Addresses, Birthday, Kids and Closing, so it is clear which details are missing for each client. Missing values read Unknown.

Unlike Create Market Updates, there is one row per client rather than one per sale, because this step emails the person rather than the property. A client with several closings appears once.

Some rows cannot be emailed. They arrive greyed out and unselected, with an information icon giving the reason. Two reasons occur:

• "Not emailed — we already have this client's birthday, and every template is a request for it." There is no template left to send, even where the mailing address is still missing.
• The client has no valid email address on file.

Where no row on the page can be emailed, the select-all checkbox is disabled with the tooltip "None of these clients can be emailed."

Only rows that can actually be reached arrive pre-selected, so the count in the header is the number that will really be sent.

Actions available

Clicking Review Emails in the footer opens all four templates so they can be read before anything goes out. Send then performs the action, with the confirmation "You have selected 9 client(s), and the system will send an email for the missing info."

With nothing selected, the footer button simply moves you to the next step.

Templates

1. Has Address . Needs Birthday . Has Kids
2. Has Address . Needs Birthday . No Kids
3. No Address . Needs Birthday . Has Kids
4. No Address . Needs Birthday . No Kids

Navigation

Previous screen: Create Market Updates

Next screen: Other Controls

Other Controls

This step switches on the reminder emails – the daily and weekly digests covering upcoming events.

The working control appears as an overlay reading "Now that your database is clean, we can email you a digest of the client events coming up, so none of them slips past.", with Daily and Weekly checkboxes and Skip and Save buttons.

Toggle either switch and save. The footer's primary button is Save.

Each switch is applied independently, so changing one does not affect the other.

This prompt will not appear if both the events are already subscribed.

DB Health

This is the final screen, and the one to return to. Five scorecards measure how complete the database is, each with a button leading straight to whatever is still missing.

The percentages are measured over A and A+ rated clients only, not the whole database. Closing clients is the exception, which measures closings linked to a client record.

UI / What's displayed

Five cards — Market updates, Birthdays, Mailing addresses, Closing clients and Kids at home. Each shows a live percentage, how many records are still incomplete, and an information icon explaining exactly what the percentage measures.

Empty states are shown in place of a misleading number. A card with no population to measure reads "No A/A+ clients yet" or "No closings yet" rather than claiming 0%. Where nothing at all can be measured, the whole screen reads "Insufficient data to form analytics."

Actions available

Four of the five cards open an editor directly on the page:

• Market updates – lists closed clients with no active update, and allows create one per client
• Birthdays – pick a date and save
• Mailing addresses – fill in the address fields and save
• Kids at home – answer yes or no, and on yes add each child's relation, name and date of birth. "Not sure" is not counted as complete on the Kids at home card. The client stays on the list until a definite yes or no is recorded. The birth year is mandatory as the system needs this to understand whether the person is a kid or not.

Rows fade out of the list as they are completed.

The Closing clients card is the exception: it navigates back to Match Sales.

Navigation

The footer button is Finish. There is no Activity Log on this screen. The scorecards are a legitimate route back into the earlier steps, so this screen doubles as the Wizard's home once the first pass is complete.

There are no Prev and Skip & Next routes. This is the final step. Clicking Finish routes back to the welcome screen.

Activity Log and Rollback

The activity log is the Wizard’s undo history. It records every forward wizard actions such as removal, merges performed in the first 5 stages for the DB Wizard. Each one of the recorded steps can be reversed in descending order(Newest first).

A removal records the contact that is deleted and a merge records the primary contact with every contact merged to it.

The Activity Log button appears in the header section.

The operation/action will be visible in the activity log only after it is completed successfully.

UI / What's displayed

• Filter chips: A filter chip is available for each stage, displaying the number of forward actions recorded for that stage. By default, the All chip is selected, showing all reversible actions across all stages.
• Action history: Each action is displayed as a separate row, showing the specific operation performed. For example:
  • Sam merged into Joseph
  • John moved to Trash
• Reverse action: Each action has a Reverse button to initiate the rollback. Once clicked, the button changes to a Reversing loader and then to Reversed after the rollback is completed successfully in the background.
• Pagination: The page displays 25 actions at a time. A Load more button is available to load the next 25 actions.
• Disabled Reverse: The Reverse button is disabled for actions that depend on subsequent actions. To enable the button, the dependent actions must be reversed first.

  • Example:

    Action 1: John is merged into Sam.

    Action 2: Sam is merged into Joseph.

  • In the Activity Log, the actions are displayed in reverse chronological order: Action 2 followed by Action 1.
  • The Reverse button for Action 1 is disabled because Sam is currently involved in the newer Action 2. Action 2 must be reversed first to make Sam an independent contact again. Once Action 2 is reversed, Action 1 can be reversed.
• Deadline: Actions can be reversed for 14 days after they were performed. Past that they are no longer listed, and no longer reversible.

Actions available

• Reverse – restores what the action changed.
• Filter by stage – the chips narrow the list to one stage.

FUB Hard deletion

A contact that was permanently deleted in FUB does not block the reversal. Everything else in the action is restored normally, only that contact's stage cannot be put back in FUB.

Navigation

The log opens over the stage you are on and closes with Back to the wizard, the header close control, Escape or a click outside it.

Closing it reloads the stage underneath, so what you are looking at matches the database rather than the pre-reversal view.