Customers, Accounts & Properties

"The customer" means three different things in a field business, and a CRM that stores them as one record breaks the first time they come apart. There's the person who answers the phone and signs things. There's the account, the relationship that's billed and has a history. And there's the property, the place where the work happens, with its own gate code, square footage and dog. A couple shares one account; a landlord has one account and twenty properties; a family moves and the account follows them to a new property while the old one gets a new owner who may become a customer too. Each of those is ordinary, and each needs the three to be separate records.

This chapter is the customer model: what each record is, how they relate, and the rules (unique contacts, validated addresses, merges, alerts) that keep a million of them usable.

Account, Person, Property#

• Account. The relationship: what's billed, what's scheduled, what has a history. It owns subscriptions, notes, alerts and a balance. It has a timezone and a country, taken from its service property, and a stable identifier everything else references. Customer-facing extras such as a referral code live here, because referrals are relationships, not people.
• Person. A human with names, contact methods and, if the business uses them, birthdays and anniversaries for marketing. A person can belong to several accounts (a property manager, a parent paying for a child's home) and an account can have several people.
• Property (or service address). The place. It's validated, geocoded, and placed into the business's geography: which service area it's in, which county and city, which timezone. Properties are shared records, so two accounts can point at the same address over time (the seller and then the buyer of a house) and the property's own facts (structure, size, access notes, regulatory status) survive the change of owner.

Subscriptions (the agreements in Service Agreements & Plans) hang off the account, and each names a service address and a mailing address. They're often the same and must not be assumed to be: rental owners, snowbirds and businesses receive mail somewhere other than where the work happens. Mailing address defaults to the service address and can be changed without touching anything operational.

In a platform split into domains, these records have different owners. The CRM owns accounts, people and contacts; billing owns its own customer object for the payment processor; field service owns the operational facts about the property. The names collide (billing's "customer" maps to the account's owner, not to every person on it), so write down which is which before anyone builds an integration.

Household Roles#

People join an account through a role, and the role decides what they can do:

Role	Can
Owner	Everything, including cancelling, changing the plan and managing other people
Manager	Schedule, pay, update payment methods, invite others below them
Editor	Schedule, add notes and special requests
Viewer	See appointments and invoices

Exactly one person is the owner: the one who signed, the one notifications default to, and the one with authority to end the agreement. Ownership moves explicitly (a transfer, recorded) and never by inviting someone with the owner role. Invitations carry the role, expire after a short time, can be re-sent with a cooldown, and can't target an email that already belongs to someone, because that someone should be added, not duplicated.

Commercial accounts stretch this model: one account, many properties, a facilities manager who approves work and an accounts-payable contact who never sees a schedule. The same roles work if they're scoped to the account, and properties are listed under it.

Contacts and the Primary Rule#

People have several emails and phones, each with a type (mobile, home, work), a verified timestamp, and one marked primary. The rule that keeps contacts usable:

A primary email or primary phone belongs to exactly one person across the whole system. Non-primary duplicates are allowed (a shared family landline, a work email on two accounts), but the primary is what login, notifications and lookup trust. If the incoming primary contact is already someone else's primary, the new record gets it as non-primary, and someone decides whether these are the same person.

Why so strict:

• Login. Customers sign in with a code sent to their email or phone. Two people with the same primary contact means a code that could open either account.
• Lookup. A call center rep searches by the number on caller ID. One match is an answer; two is a conversation about privacy.
• Messaging. Consent is recorded per contact and channel (Customer Communications), and a phone that's primary on two people has two consent histories that disagree.

Keep history for every contact change: who changed it, when, from what. Disputes about "you texted the wrong number" and fraud through changed contact details both need it.

Addresses Are Places#

A typed address is a guess. Before it becomes a property it's validated, standardized and geocoded, because everything downstream depends on where it actually is: whether it's serviceable, which area and technician it belongs to, which licenses and rules apply, which timezone its appointments are in.

• Validation and standardization. In the US, address software certified under the USPS CASS program matches addresses to ZIP+4 and to a delivery point. Delivery point validation says whether the USPS knows the address at all, whether the unit number was recognized or missing, and whether it's vacant. A residential delivery indicator says residential or commercial, which can matter for pricing and for which product line applies. Providers such as Smarty return all of these with the standardized address.
• Geocoding precision. A coordinate is only as good as its precision. ZIP-level coordinates are interpolated from nearby addresses and can put a property in the wrong service area near a boundary; rooftop or parcel coordinates put it on the building. Store the precision with the coordinate and treat anything coarser than street level as unconfirmed for routing.
• Fingerprints and versions. Hash the normalized address to recognize repeats (folding ZIP+4 down to the five-digit ZIP so a missing extension doesn't make a new address), and version addresses instead of editing them in place, so a past appointment still points at where it actually happened.
• The geography it lands in. On save, resolve the point into the business's polygons (service area, zone) and into regulatory jurisdictions (state, county, city), and store the result. Recompute when the polygons change (Territories & Capacity).

Validation fails for real places. New construction isn't in postal data yet, rural routes have odd formats, and some properties have no deliverable address at all. Allow an override with a reason and a person attached, pin the coordinate by hand on a map, and flag the property for review.

Time Lives at the Property#

Every appointment window, reminder, quiet hour and billing anchor is local to somewhere, and that somewhere is the property. Store an IANA timezone identifier on it (derived from its coordinate, with an override for the rare property where the derivation is wrong) and compute every local time from it. Not the service center's timezone (centers near a timezone line serve properties on both sides), not the customer's phone, and never a fixed offset, since offsets change with daylight saving and occasionally with legislation. The IANA database is updated several times a year for exactly that reason, so pin the version you ship and update it deliberately (Time).

Property Attributes#

What the technician needs to know before arriving lives on the property, not in a free-text note on the account:

Attribute	Why it's structured
Access: gate code, lockbox, where to park	Read on the way in; a gate code is a secret and shown only to whoever's assigned
Pets	Safety, and some treatments require animals to be kept away
Size: square footage, lot size, linear feet	Pricing, product amounts, and some states' application records
Structure: construction type, crawlspace, slab, pool	Which services apply and how long they take
Hazards: aggressive dog, steep roof, standing water	Technician safety, shown before arrival
Regulatory status: on a pesticide notification or hypersensitivity registry	Whether neighbors or occupants must be notified before treatment (Regulated Materials)
Photos	Where the bait stations are, what the problem looked like

Structured attributes can be validated, priced against and shown at the right moment. Free text gets ignored on the hundredth stop of the week.

Duplicates and Merges#

A customer who signs up at the door, then calls in, then logs in to the portal can easily become three records. Prevent what you can at creation:

1. Match the person by any existing email, then by any phone, before creating a new one.
2. Match the property by its fingerprint before creating a new address.
3. Match the account by property and person together: the same person at the same property is probably the same relationship.

What gets through is fixed by merging, and merging is a pointer, not a delete. The losing record keeps its identifier and gains a merged_into reference; lookups follow the pointer; everything that referenced the old record (appointments, messages, invoices, notes) keeps working and is reassociated where it matters. Message history in particular keeps a "merged from" association, so the customer's timeline still shows what was sent to the record they used to be. A merge is permissioned (it rewrites a customer's history), audited, and, where it can be, reversible.

Don't match on name alone. Two people named the same at different properties are common; one person with two names (a nickname, a maiden name) is common too. Contacts and properties are far better evidence than names.

Alerts, Flags and Notes#

Operational knowledge about an account comes in two kinds, and they need different records:

• Notes are history: what happened, what was said, what the technician saw. They're append-only, attributed and timestamped, can carry attachments, and can be linked to the appointment they're about so the technician sees them on that visit.
• Alerts (flags) are state: something everyone touching this account should know right now. A billing problem, a VIP, a problem pest the sales rep noted at the door, a follow-up due, a customer who was just talked out of cancelling. An alert has a category (with a color and icon so it's visible at a glance), an optional due date, an expiry, and an owner who closes it.

Expiry is what keeps alerts meaningful. An alert with no end date becomes wallpaper; one that expires on its own (a retention save that matters for a year, a billing problem that should be resolved within a month) stays a signal. Give each category a default duration, auto-close at expiry with a recorded reason, and let a closed alert be converted into a note so its content isn't lost.

Other domains create alerts too, and that's where they earn their keep. A bank account that returned a payment creates a billing alert with the return reason in plain words; a sale that captured a specific pest problem creates an alert the first technician sees. Make those idempotent (one alert per payment method while it's open, one per sale), since events arrive more than once.

Search#

Customer service lives in search: a name, part of an address, a phone number read off caller ID, an email, an invoice number. Make each of those fast and exact where it should be exact (identifiers and contact methods) and forgiving where it should be forgiving (names and addresses, with trigram or similar fuzzy indexes). Search results show enough to tell two similar customers apart (property, status, last service) without opening each one, and access to search is itself permissioned and logged, since it's the easiest way to browse other people's information.

Deletion and Retention#

People ask to be deleted, and some of what's stored about them must be kept anyway: service records for regulated treatments, financial records for tax and audit. Separate the two. Purging a person removes their names, contacts, sessions and personal notes, and is refused while they still belong to an account, because an account must always have an owner. Records the business must keep are retained under the account with the personal details stripped or minimized. Every purge emits an event so the other domains (communications, billing) remove their copies too, and the event itself carries no personal data (Data Retention).

What This Means for the System You Build#

• Accounts, people and properties as separate records, with subscriptions naming both a service and a mailing address.
• Roles on the account, exactly one owner, and invitations that expire.
• One person per primary email and phone, contact history kept, and verification timestamps.
• Validated, geocoded properties with stored precision, fingerprints, versions, and the polygons and jurisdictions they fall in.
• An IANA timezone on the property, used for every local time.
• Structured property attributes, with secrets like gate codes shown only to whoever's assigned.
• Match before create, merge by pointer, and keep history reachable through merges.
• Alerts with categories, due dates and expiry, created idempotently by other domains, separate from append-only notes.
• Purge that strips people but keeps required records, announced by an event.

References#

Specifications

• USPS: Publication 28, Postal Addressing Standards, how US addresses are formatted
• USPS: CASS, certification of address-matching software for ZIP+4, delivery point validation and the residential delivery indicator
• IANA: Time Zone Database, the history of local time by location, updated as governments change rules

In practice

• Smarty: US Street Address API, delivery point match codes, residential or commercial, geocoding precision from ZIP to rooftop, and timezone fields