--- id: FEAT-CRM-ENT-03 title: Contact Details and Communication Preferences product_area: crm module: entities revision: 1 status: approved product_intent: proposed source_sha: services-crm: 7ea48a414c42eade10d60753b8bcc323b1dd726f react-console: da63075876b2c5f4a6af07d457bb24ea8bf4c0c7 purpose: >- Staff maintain ways to reach people and organizations. They can also record how a person wants to receive communications. outcomes: - Staff maintain ways to reach people and organizations. concepts: - CON-CRM-ENT-034 actors: - ACT-CRM-001 - ACT-CRM-002 - ACT-CRM-003 - ACT-CRM-004 - ACT-CRM-005 acceptance: FAS-CRM-ENT-03 capabilities: - CAP-CRM-ENT-005 - CAP-CRM-ENT-006 - CAP-CRM-ENT-007 journeys: [] related_concepts: - CON-CRM-ENT-001 approved_by: Andrew approved_at: 2026-10-22T00:00:00.000Z narrative: status: verified review: NARRATIVE-REVIEW-2026-10-23 narrative_sources: - section: Why It Exists provenance: inferred source: CAP-CRM-ENT-005; CAP-CRM-ENT-006; CAP-CRM-ENT-007 note: >- Operational consequences are the reviewer’s reading of the child contracts, not attributed historical motivation. The affiliation milestone supplies the current-membership distinction where named. - section: Decisions and Tradeoffs provenance: inferred source: "CAP-CRM-ENT-005; CAP-CRM-ENT-006; CAP-CRM-ENT-007" note: The tradeoffs interpret the child contracts; no historical motive is attributed. - section: How It Works provenance: observed source: >- services-crm:modules/entities/tests/integration/services/persistence/contacts.integration.spec.js#refuses a fourth e-mail address; services-crm:modules/entities/tests/integration/db/contact-email-addresses.table.integration.spec.js#refuses to make an inactive contact active while another contact holds its primary address; services-crm:modules/entities/tests/integration/services/persistence/contacts.integration.spec.js#refuses two numbers of the same type; services-crm:modules/entities/tests/integration/services/persistence/contacts.integration.spec.js#formats a valid US number, drops a blank one and marks the default preferred number; services-crm:modules/entities/tests/integration/services/persistence/contacts.integration.spec.js#marks the first address of the tenant’s display order as preferred, never one with a seasonal period; services-crm:modules/entities/tests/integration/services/persistence/contacts.field-rules.integration.spec.js#refuses an unknown country, naming the address’s country; services-crm:modules/entities/tests/integration/services/persistence/contacts.field-rules.integration.spec.js#leaves a contact saveable after the type of an address it holds became organizations-only; services-crm:modules/entities/tests/unit/services/contacts/seasonal-addresses.spec.js#refuses overlapping seasons naming both addresses; services-crm:modules/entities/tests/e2e/contacts.e2e.spec.js#answers the seasonal address in season when the contact marks it, with the workspace date; services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#A9; services-crm:docs/disconnected-information.md#What changed; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#refuses a link to a record of an organization other than the affiliation’s; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#refuses a new link through an upcoming affiliation, naming the path; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#refuses a value that differs from the organization’s in letter case, naming the field (A19); services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#writes nothing to the contact: its version is the one before; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#turns the linked work address into a disconnected row holding its last value, not a copy (D-25); services-crm:modules/entities/tests/e2e/contacts-disconnected.e2e.spec.js#refuses a client that asks for a row to be disconnected, naming the field; services-crm:modules/entities/tests/e2e/contacts-disconnected.e2e.spec.js#is refused 409 on a row that is no longer disconnected; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#makes an independent copy of the resolved value when the row is saved as copied with no value of its own; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#refuses a save that removes the affiliation and keeps the rows linked through it; services-crm:modules/entities/tests/integration/services/persistence/contact-information-sources.integration.spec.js#links nothing when the choice is an empty list; services-crm:modules/entities/tests/integration/services/affiliations/affiliation-date-reconciliation.follow-ups.integration.spec.js#links every default of its type on the start day when the save stated no choice; FND-CRM-ENT-010; services-crm:modules/entities/db/contacts.table.ts:do_not_mail; services-crm:modules/entities/tests/integration/services/persistence/contacts.integration.spec.js#refuses a communication type listed twice, naming the second entry; services-crm:modules/entities/tests/integration/db/contact-communication-preferences.table.integration.spec.js#refuses a subscription value that is not shaped like an address by the domain’s email_address_format_check; services-crm:modules/entities/tests/integration/db/contact-communication-preferences.table.integration.spec.js#refuses a subscription status outside the closed list by contact_communication_preferences_status_check; services-crm:modules/entities/services/persistence/contacts.ts:communicationPreferenceProblems; services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#2. Scope acceptance_suite: FAS-CRM-ENT-03 --- # Contact Details and Communication Preferences ## Overview Contact Details and Communication Preferences records the ways association staff can reach people and organizations, together with a person's stated communication choices. A phone number's type, an address's purpose, and a preferred contact point help staff interpret information rather than treating every value as interchangeable. Some details belong directly to the person. Others come from an affiliated organization, either as a deliberate copy or as a live link. The distinction becomes visible when the organization changes or removes its source information. ## Why It Exists Our reading is that an address or number needs operational context before staff can use it confidently. A retired member's winter residence can be correct in January and inappropriate in July. A work address may follow a firm rather than belong independently to the person. If staff treat those values as interchangeable strings, they can use the wrong destination or retain an apparently plausible address after the source has been removed. Preferences answer another question: a reachable member may still ask not to receive postal mail or may choose a particular subscription address. Recording that instruction gives staff information to inspect, but storage alone cannot prove a sender honors it. The feature keeps destination, source reliability and member choice understandable while leaving actual message delivery to the communication boundary. ## Who Uses It The CRM Editor maintains e-mail addresses, typed phone numbers, addresses, and communication choices. The CRM Reader inspects the saved details and restrictions. The CRM Administrator maintains the address and phone classifications used by those entries. The Data Importer submits contact information through record saves, while the CRM System resolves shared values and records disconnections. ## How It Works Staff save contact points with the person or organization. Rhythm normalizes supported values, checks classifications and preferred choices, and retains element identities when entries are corrected. Seasonal address selection uses the workspace calendar and the person's explicit seasonal-use choice. For shared details, staff connect a destination type on the person to a source on a currently effective affiliation. A link resolves the organization's latest value on read. Removing the source preserves its last value on the person as disconnected information requiring verification. Staff can verify that retained value, relink it, or remove it. Communication restrictions and per-type subscription choices are stored separately from the message sender's enforcement. Staff first choose the purpose of each contact point. Home and Work address types identify different uses; preferred is a selection among those entries, not another address type. Phone preference likewise chooses one number. E-mail addresses are ordered, with the first as primary, rather than using the address and phone preference flags. The active-contact primary-e-mail constraint remains separate from per-subscription address choices. Moving an address to a secondary slot does not make it the primary destination, and a communication choice does not change the stored ordering. Seasonal mailing adds time to selection. Staff retain a regular preferred address and enter a recurring month-and-day window for a seasonal one. The window can cross December. A seasonal address becomes the mailing choice only during its window and when explicitly marked for seasonal use. It does not become the regular preferred address, and overlapping seasonal windows are refused. The workspace calendar supplies the day, so the answer does not depend on where the coordinator's browser is running. Sharing adds a source question. An owned value belongs to the person; a deliberate copy records its origin but no longer follows later organization corrections. A live link follows its source through an effective affiliation. An ended affiliation can leave an unresolved link without a current value, which differs from disconnection after source removal. Removing the source preserves the last value and provenance and changes affected contacts' versions. Recovery therefore begins by reading the latest contact, not by resubmitting an older form. Verify makes the retained value independent, relink chooses one eligible current source, and remove discards the detail; each uses the version-aware action appropriate to a disconnected entry. ## Examples Ruth Kim uses her member firm's main address as her work address through a live affiliation link. When the firm moves, Ruth's next read resolves the new address without another contact save. If the firm instead removes that source, Rhythm retains the old value with a disconnected state. A coordinator investigates and either confirms it as Ruth's independent address or links it to the firm's replacement. Retired engineer Daniel Ruiz keeps his regular home address in Albany and a winter address in Tucson from December 1 through March 31. The coordinator marks seasonal use and reads the mailing selection for January 15: Tucson applies. On April 1 the regular preferred address applies again. A second season sharing March 31 is refused because that day belongs to the first season too. Daniel's seasonal address remains available as information without being his year-round preferred address. Daniel also requests no postal mail and chooses an address for a particular newsletter subscription. The coordinator saves and reads back both choices, rather than inferring that the seasonal mailing selection changed the subscription address. These checks establish stored preference information. They do not establish that a downstream sender applies a particular precedence among restrictions, subscriptions and destination choices. That enforcement belongs to the communication contract and remains an explicit boundary. ## Decisions and Tradeoffs Our reading is that destination, provenance and consent answer different operational questions and need separate representations. A single preferred string cannot explain whether it is primary e-mail, regular mailing preference, seasonal selection or an address chosen for one subscription. Keeping those meanings distinct makes staff inspection possible without inventing sender policy. Live links avoid maintaining a copy on every employee when a firm moves. Copies provide independence when that is wanted. Disconnection preserves useful information while exposing lost source reliability; silently retaining an apparently live address would conceal the need to investigate. Version-aware recovery prevents the investigation from overwriting a colleague's newer decision. The tradeoff is that a successful contact read requires interpretation of source state, rather than treating every visible value as equally current. ## Scope and Boundaries The feature owns contact-point values, shared-source interpretation, and preference storage. Classification Types and CRM Settings owns the catalogues that describe their purposes, and Affiliations and Roles owns the ties that permit sharing. Platform owns communication delivery. Recording an opt-out here does not establish that every downstream sender applies it; that boundary remains explicit in the formal contract. ## Outcomes Staff can distinguish a current shared value from an independent copy and from information needing verification. They can also inspect a person's communication choices alongside the contact record. The Contact Details and Communication Preferences acceptance suite exercises storage, source changes, and preference persistence across these capabilities, with outstanding proof gaps retained in the findings register. ## Its Capabilities Maintain reliable contact points validates and organizes the addresses, phone numbers, and e-mail addresses staff save. Share organization contact points with affiliated people resolves live sources and provides recovery when a source disappears. Capture a person’s communication choices stores contact-wide restrictions and per-type subscription information without taking over message delivery.