Contact

What It Models

A contact models one person who can remain involved with an association across employers, chapters and responsibilities. The person’s identity joins personal information, communication choices and dated ties in one save boundary. For example, Ruth Kim can change firms while keeping her chapter affiliation and the same contact number.

Our reading is that this aggregate prevents a change in employment or address from looking like a different person. The contact owns relationship periods and contact points, while Platform owns their field definitions and presentation. A classification named Member supplies a CRM category; it does not establish membership entitlement.

Identity and Attributes

Contacts have workspace-scoped identities. Creation keeps a valid unused client identity or generates one. The service allocates a separate staff-facing contact number; clients cannot choose it, and allocated numbers are not recycled.

The table describes logical properties. Optional values can be absent; a required collection member is distinct from requiring the collection itself. Examples illustrate association information and do not establish new defaults. Service-owned values remain separate from fields that staff or integrations supply.

Property	Meaning and writer	Constraints	Example
id	A continuing identity for integrations and record references. Set by integration.	Unused workspace identity with letters, digits, underscores, hyphens or vertical bars; generated when omitted.	ruth_kim
number	The staff-facing contact reference. Set by system.	Assigned by the workspace contact counter; never chosen or recycled by a client.	10428
status	The person’s current business classification of availability. Set by staff.	Active is the default; active, inactive, deceased and duplicate are the closed choices.	active
contact type	The workspace category that selects effective forms and layouts. Set by staff.	Optional workspace contact type; retained inactive references remain valid.	Member
prefix	Title appearing before the full name. Set by staff.	Trimmed optional text up to 200 characters; first or last must contain text.	Dr.
salutation	How correspondence addresses the person. Set by staff.	Trimmed optional text; cannot replace both first and last names.	Dear Ruth
first name	Given name used in display. Set by staff.	Trimmed optional text up to 200 characters; first or last must contain text.	Ruth
middle name	Middle name reduced to an initial in derived names. Set by staff.	Trimmed optional text up to 200 characters; first or last must contain text.	Anne
last name	Family name used for display and sorting. Set by staff.	Trimmed optional text up to 200 characters; first or last must contain text.	Kim
maiden name	Earlier family name retained as personal information. Set by staff.	Trimmed optional text; cannot replace both first and last names.	Park
nickname	Familiar name included in derived presentation. Set by staff.	Trimmed optional text up to 200 characters; first or last must contain text.	Roo
suffix	Name suffix. Set by staff.	Trimmed optional text up to 200 characters; first or last must contain text.	Jr.
credentials	Professional qualifications following the display name. Set by staff.	Trimmed optional text; cannot replace both first and last names.	CAE
display name	The compact name used in ordinary record presentation. Set by system.	Derived from editable name parts. Creation refuses direct derived-name input; maintenance permits unchanged read-back values, while attempts to change them independently are refused.	Ruth A. Kim, CAE
full name	The display name with its prefix. Set by system.	Computed alongside the other derived names.	Dr. Ruth A. Kim, CAE
sort name	The family-first label for ordering people. Set by system.	Computed from the same supplied name components.	Kim, Ruth A.
job title	The title associated with the prominent organizational connection. Set by staff.	Trimmed optional text; saved contact and primary-affiliation titles are coordinated.	Executive Director
spouse	An interim reciprocal personal connection. Set by staff.	Another contact in this workspace; cannot be self or already paired to another person.	Daniel Kim
photo	The person’s image for record presentation. Set by staff.	Platform file reference made permanent before persistence; display links are returned on read.	Ruth’s portrait
gender	Optional stored gender information. Set by staff.	The observed closed choices are male and female; broader product vocabulary is not established.	female
pronouns	The person’s stated pronouns. Set by staff.	Optional trimmed text.	she/her
date of birth	The person’s birth date when known. Set by staff.	Optional ISO calendar date, without a time.	1984-04-12
date of death	The recorded death date when known. Set by staff.	Optional ISO calendar date; separate from selecting deceased status.	2026-03-01
notes	Free text that staff retain about the person. Set by staff.	Trimmed text up to 10,000 characters.	Prefers calls after the monthly board meeting.
Facebook	The recorded social-profile reference. Set by staff.	Optional trimmed text; no verified guarantee that the remote profile exists.	https://www.facebook.com/ruth.kim
Twitter	The recorded social-profile reference. Set by staff.	Optional trimmed text; no verified guarantee that the remote profile exists.	@RuthKim
Instagram	The recorded social-profile reference. Set by staff.	Optional trimmed text; no verified guarantee that the remote profile exists.	@ruthkim
LinkedIn	The recorded social-profile reference. Set by staff.	Optional trimmed text; no verified guarantee that the remote profile exists.	https://www.linkedin.com/in/ruth-kim
profile last updated	The stored time of profile review. Set by staff.	Optional ISO timestamp accepted by the record schema.	2026-10-20T14:00:00Z
social profile last updated	The stored time of social-profile review. Set by staff.	Optional ISO timestamp.	2026-10-20T14:00:00Z
region	The regional grouping selected from the deciding address. Set by system.	Regions assigns it unless automatic assignment is overridden; reference stays workspace-local.	Western Region
override automatic region assignment	Whether an explicit region choice takes precedence. Set by staff.	Optional boolean accepted on the person record.	true
national district	The label or reference supplied by district lookup. Set by system.	Metadata presents this as read-only; API enforcement is an existing unresolved finding.	CA-12
national district OCD reference	The label or reference supplied by district lookup. Set by system.	Metadata presents this as read-only; API enforcement is an existing unresolved finding.	ocd-division/country:us/state:ca/cd:12
state upper district	The label or reference supplied by district lookup. Set by system.	Metadata presents this as read-only; API enforcement is an existing unresolved finding.	California Senate District 7
state upper district OCD reference	The label or reference supplied by district lookup. Set by system.	Metadata presents this as read-only; API enforcement is an existing unresolved finding.	ocd-division/country:us/state:ca/sldu:7
state lower district	The label or reference supplied by district lookup. Set by system.	Metadata presents this as read-only; API enforcement is an existing unresolved finding.	California Assembly District 18
state lower district OCD reference	The label or reference supplied by district lookup. Set by system.	Metadata presents this as read-only; API enforcement is an existing unresolved finding.	ocd-division/country:us/state:ca/sldl:18
do not mail	A broad postal restriction recorded for the person. Set by staff.	Boolean defaults to false; storage does not prove every downstream sender honors it.	true
do not call	A broad telephone restriction recorded for the person. Set by staff.	Boolean defaults to false; storage does not prove every downstream sender honors it.	false
email opt-out	A broad email restriction recorded for the person. Set by staff.	Boolean defaults to false; storage does not prove every downstream sender honors it.	true
communication preferences last confirmed	When the person’s choices are last reviewed. Set by staff.	Optional ISO timestamp.	2026-10-22T13:00:00Z
email addresses	Ordered destinations, with the first used as primary. Set by staff.	At most three canonical lowercase addresses, each up to 254 characters; primary reservation depends on status.	["ruth@harbor.example","ruth.kim@example.org"]
phone numbers	Typed numbers with optional extension, preference and source. Set by staff.	One per type, one preferred at most; stored source distinguishes owned, copied, linked and disconnected values.	Work: +1 510 555 0134, extension 204
addresses	Typed postal details including geographic and seasonal information. Set by staff.	One per type, one ordinary preferred; seasonal month-day ranges cannot overlap or also be ordinary preferred.	Home: 42 Harbor Avenue, Oakland, CA 94612, US
mailing address	The address applicable for mail on the workspace day. Set by system.	Select an eligible seasonal-preferred address, otherwise the ordinary preferred address.	Winter residence during its selected season
communication preferences	Choices for each external communication category. Set by staff.	One entry per communication type; enabled is required; subscription is subscribed, digest, unsubscribed or absent.	Newsletter: enabled, digest, ruth@harbor.example
custom field values	Customer-defined extensions of the person’s information. Set by staff.	Active Platform contact definitions govern value types.	Professional designation: CAE
affiliations	The person’s dated organizational ties and responsibilities. Set by staff.	Saved through the contact aggregate; the affiliation design explains each nested property.	Current employer Harbor Engineering; current chapter Harbor West
primary organization	The identity and label of the primary affiliation’s organization. Set by system.	Derived on read; not a stored employer field.	Harbor Engineering
origin service	The integration that supplies the imported origin. Set by import.	Import bookkeeping cannot be edited as an ordinary profile field.	legacy-crm
origin record	The source system’s reference for this person. Set by import.	Retained with origin service as import provenance.	person-482
version	The basis against which a later correction is compared. Set by system.	System advances it for a committed aggregate change; the caller echoes its read version.	7
lock	A customer restriction on mutation of this record. Set by system.	Dedicated lock actions choose no lock, deletes, or updates & deletes; ordinary saves retain it.	deletes
created at	When this identity is first stored. Set by system.	System timestamp; unchanged by later corrections.	2026-10-20T14:00:00Z
created by	The actor responsible for creation. Set by system.	System attribution; a read can resolve its current display name.	Association coordinator
modified at	When the latest net change commits. Set by system.	A current-version no-op preserves this timestamp.	2026-10-23T15:30:00Z
modified by	The actor or system responsible for the latest change. Set by system.	Recorded with the write context; system work can invalidate an open editor.	CRM system
archived at	Whether ordinary discovery and editing exclude this identity. Set by system.	Only archive and unarchive actions control the timestamp.	2026-10-23T15:30:00Z
archived by	Who sets this record aside. Set by system.	Captured by the archive action and cleared on restoration.	CRM administrator
archive reason	The explanation for setting the record aside. Set by system.	Optional trimmed reason limited to 500 characters.	Firm closed
unarchive reason	The explanation for making the record available again. Set by system.	Optional trimmed reason limited to 500 characters.	Firm reopened

Detail collection properties

Each entry belongs to its aggregate and has its own identity and system lock/stamps. These child properties explain the exposed value and source fields without creating independent domain objects. Organization values supply linked contact values only through the verified affiliation and source references.

Property	Meaning	Example
contact addresses / disconnected_from_organization_id	Original organization retained after the live source is removed.	Ohio Association Council
contact addresses / disconnected_at	Service-owned timestamp of the disconnection.	2026-10-23T14:00:00Z
contact addresses / disconnected_reason	Service-owned source-removal or organization-merge cause.	organization_address_removed
contact addresses / address_type_id	The workspace address purpose, subject to one-per-type and applicability validation.	business
contact addresses / line1	First postal delivery line.	410 Association Way
contact addresses / line2	Second postal delivery line.	Suite 200
contact addresses / line3	Additional postal delivery context.	Member Services
contact addresses / city	City in the postal value.	Columbus
contact addresses / state	State or province in the postal value.	OH
contact addresses / postal_code	Postal routing code.	43215
contact addresses / county	County supplied with the postal value.	Franklin
contact addresses / country	Country code; storage defaults to US.	US
contact addresses / latitude	Optional latitude supplied with the postal value.	39.96
contact addresses / longitude	Optional longitude supplied with the postal value.	-83.00
contact addresses / time_zone_id	Optional time-zone identity associated with the location.	America/New_York
contact addresses / seasonal_start	Recurring month-and-day beginning the seasonal period.	11-01
contact addresses / seasonal_end	Inclusive recurring month-and-day ending the season; the period can cross the year boundary.	03-31
contact addresses / seasonal_preferred	The seasonal address is requested as the mailing destination while eligible and in season.	true
contact addresses / is_preferred	Preferred selection within this owner’s collection.	true
contact addresses / source_mode	Owned, copied, linked or disconnected explains the origin and live-resolution behavior.	linked
contact addresses / source_affiliation_id	The contact’s affiliation through which a live source is supplied.	Current employer relationship
contact addresses / source_organization_id	The organization supplying a live source through that affiliation.	Ohio Association Council
contact addresses / source_organization_address_id	The supplying organization address, confined to the selected organization.	Headquarters address
contact addresses / copied_from_organization_id	Informational organization identity retained with a one-time copy.	Ohio Association Council
contact addresses / copied_at	The timestamp at which the organization values were copied.	2026-10-23T14:00:00Z
contact phone numbers / phone_number_type_id	The workspace telephone purpose, subject to one-per-type and applicability validation.	direct
contact phone numbers / phone_number	The telephone value; linked contact entries obtain their effective value from the organization source.	+1 614 555 0100
contact phone numbers / is_preferred	Preferred selection within this owner’s collection.	true
contact phone numbers / source_mode	Owned, copied, linked or disconnected explains the origin and live-resolution behavior.	linked
contact phone numbers / source_affiliation_id	The contact’s affiliation through which a live source is supplied.	Current employer relationship
contact phone numbers / source_organization_id	The organization supplying a live source through that affiliation.	Ohio Association Council
contact phone numbers / source_organization_phone_number_id	The supplying organization telephone entry, confined to the selected organization.	Main office phone
contact phone numbers / copied_from_organization_id	Informational organization identity retained with a one-time copy.	Ohio Association Council
contact phone numbers / copied_at	The timestamp at which the organization values were copied.	2026-10-23T14:00:00Z
contact phone numbers / disconnected_from_organization_id	Original organization retained after the live source is removed.	Ohio Association Council
contact phone numbers / disconnected_at	Service-owned timestamp of the disconnection.	2026-10-23T14:00:00Z
contact phone numbers / disconnected_reason	Service-owned phone-source removal or organization-merge cause.	organization_phone_number_removed
contact email addresses / position	Service-owned email slot from one through three; slot one is primary.	1
contact email addresses / email_address	The required email value in an ordered contact email entry.	ruth@association.example
contact communication preferences / communication_type_id	Communication classification identity within the preference collection.	legislative-updates
contact communication preferences / enabled	The saved preference’s enabled choice, separate from global email opt-out.	true
contact communication preferences / subscription_email_address	Optional email value for this subscription.	ruth@association.example
contact communication preferences / subscription_status	Optional subscribed, digest or unsubscribed value.	digest
contact communication preferences / subscription_last_updated	Optional timestamp associated with subscription state.	2026-10-23T14:00:00Z

Relationships

A person owns any number of affiliations, and each affiliation names one organization. Multiple ties can connect that person to the same body when their kinds or periods differ. Deleting the person removes these live children; archiving preserves them. An organization cannot be deleted while any affiliation still names it, even one that has ended.

Addresses and phones can reference an organization-owned source through a tie. Removing that source preserves its last value as disconnected information on the contact. The spouse reference is at most one reciprocal pair: deleting one person clears the survivor’s link with system attribution. Versions, archive metadata, locks and history belong to the person’s safeguards; retained revisions survive ordinary deletion.

Lifecycle

The contact record lifecycle distinguishes active, inactive, deceased and duplicate status from the separate archive flag. Ruth can be inactive and also archived; restoring her availability does not make her active automatically. The lifecycle model explains the accepted transitions and the status-sensitive email and automatic-role effects.

Hard deletion removes the live aggregate, while history retains its explanation. There is no restore operation for a deleted contact. The allocated number remains spent. A direct read of an archived identity can still succeed, even though ordinary selection and correction are restricted.

Invariants

A person’s continuing identity separates correction from creation. Changing a name or telephone number must leave affiliations, spouse context and revision inspection attached to the same person. Workspace-local references keep a valid-looking classification or relationship from pointing into another customer’s records. A duplicate refusal is therefore a prompt to inspect identity, rather than permission to reuse another person’s associations.

Contact replacement and nested relationship changes belong to the contact transaction. The current version protects a coordinator from overwriting another editor’s intervening work, while collection validation prevents a partial save from leaving an unusable primary or shared detail. Computed name and primary-organization context must agree with the editable source values. Derived values returned by a read are not independent instructions to rename the person.

Communication details preserve distinctions that affect interpretation: e-mail order supplies primary identity, phone and address purposes support preferred selections, and seasonal address choice is separate from the ordinary preference flag. A retained disconnected value records source loss; it is not evidence that staff verified a new independently maintained value. Reads and revisions let staff distinguish those states without discarding the person’s continuing context.

Permissions

The CRM authorization model separates workspace access from permission for a particular action. crm.contacts.read is granted to Administrator, Power User, Standard User, Read Only. crm.contacts.create is granted to Administrator, Power User, Standard User. crm.contacts.update is granted to Administrator, Power User, Standard User. crm.contacts.archive is granted to Administrator, Power User. crm.contacts.delete is granted to Administrator, Power User. crm.contacts.lock is granted to Administrator, Power User. crm.contacts.unlock is granted to Administrator, Power User. crm.contacts.history is granted to Administrator, Power User, Standard User, Read Only.

The service checks these grants at the corresponding operation boundary. Additional record guards still apply: grants do not bypass archive, customer restrictions, dependencies, version comparison or Rhythm protection. Read access and history access are separate; record history checks the applicable read authority as well as the history grant.

How It Is Stored and Shared

Entities persists the person row and its owned collections together, including contact custom values, affiliation periods and responsibilities. Effective address and phone reads resolve organization links instead of copying every organization change into every person. Derived names and primary-organization context shape the returned record.

Platform supplies metadata, access evaluation, actor display names and file handling. Contact events carry committed changes to search, region and other CRM consumers after the record transaction. Those consumers can lag or fail without undoing the person’s committed revision; a saved record and a refreshed projection are separate outcomes.

Open Design Questions

API enforcement of read-only civic districts is not established. Communication-type identity and downstream honoring of restrictions also remain open evidence boundaries. The existing findings cover those gaps and the missing dedicated refresh-recovery proof. The implementation of a field or callback does not confirm its product intent.