Match portal memberships to CRM contacts

Purpose

Contact matching can attach a portal member to an existing CRM contact or create a new one. Ambiguous candidates require verification using a channel belonging to the chosen contact.

How It Works

After registration, the member asks for contact matching. An eligible exact address match can be linked directly; otherwise the member reviews masked candidates or receives a new contact. Choosing a candidate starts proof through an available channel belonging to that contact. The member enters the code and sees either the linked result or a refusal explaining the remaining action. Declining all candidates creates a new contact and records the possible duplicate. When CRM matching functions are unavailable, the operation links nothing. Fresh authorization reads the current link, while an existing signed result keeps its own claim until expiry.

Relationships

Portal identity establishes the membership.
Derived access uses its linked contact as a subject.
CRM owns the contact records and matching inputs.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: A portal membership can identify the association contact behind it.Ambiguous links require proof delivered through the candidate’s channel.A declined match can leave a possible-duplicate pair for later review.
Surfaces: portalapi
Intent sources: services-platform:docs/security/portal-contact-claim.md#D-26

Controls

30 controls apply, from the corpus control catalogue.

TC-AVL-005 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.security-self.read`	api	record

Business Rules

9 rules, 8 to be proved before approval. A rule's product intent is derived from its origin: 1 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A single eligible contact sharing the member’s email address, compared without case, is linked automatically. If CRM returns no likely match, signup details are used to create and link a new contact. no proof recorded yet	calculation	service	test services-platform:modules/security/tests/integration/services/portal/contact-match.integration.spec.js#links the one contact holding the member’s own address without asking
`02`must prove Proposed	A contact already linked to another portal member in that workspace cannot be selected or linked again. no proof recorded yet	invariant	service	test services-platform:modules/security/tests/integration/services/portal/contact-match.integration.spec.js#never offers a contact another member of the tenant already links
`03`must prove Proposed	Ambiguous matching returns no more than three distinct candidates ordered by score. Responses expose masked hints and available verification channels without contact identifiers. no proof recorded yet	policy	service	test services-platform:modules/security/tests/unit/services/portal/contact-match-rules.spec.ts#offers at most three, highest score first, each contact once
`04`must prove Proposed	An offered candidate is represented by a sealed token scoped to the member, workspace and expiry. Candidates or channels outside that offer are rejected. no proof recorded yet	validation	service	test services-platform:modules/security/tests/unit/services/portal/candidate-token.spec.ts#refuses another member’s token
`05`must prove Proposed	Verification sends a code to the candidate contact’s email, or to its phone only when SMS is enabled. Challenges last ten minutes, replace earlier live challenges, allow at most five starts per hour and are exhausted by five incorrect codes. no proof recorded yet	validation	service, database	test services-platform:modules/security/tests/integration/services/persistence/portal-contact-challenges.integration.spec.js#refuses a sixth start within an hour
`06`must prove Proposed	A valid verification code establishes the contact link. Linked members cannot start another challenge, and persisted challenges contain a code digest rather than the code. no proof recorded yet	lifecycle	service	test services-platform:modules/security/tests/integration/services/portal/contact-match.integration.spec.js#links the member to the contact on the right code
`07`must prove Proposed	Declining all candidates creates and links a contact from signup details. The highest-ranked declined candidate is retained as a possible duplicate for staff review. no proof recorded yet	lifecycle	service	test services-platform:modules/security/tests/integration/services/portal/contact-match.integration.spec.js#names the best declined candidate, so staff review the pair
`08`must prove Confirmed	A fresh authorizer evaluation includes the portal member’s current contact link and excludes that claim for console users. Gateway caching can retain a previous link for sixty seconds; signed authority retains its claim until expiry. origin: services-platform:docs/security/portal-contact-claim.md#D-26 no proof recorded yet	invariant	api	documented services-platform:docs/security/portal-contact-claim.md#When a change is seen
`09` Proposed	When CRM matching functions are absent, the service returns no matching state and creates no contact link.	policy	service	test services-platform:modules/security/tests/integration/services/portal/contact-match.integration.spec.js#answers none and links nothing

Scenarios

Id	Given	When	Then	Provenance
`01`	CRM returns two plausible contacts for a portal member.	The member selects one and supplies the code delivered to that contact’s email.	The verified contact becomes the membership’s link, and further matching returns the linked state.	test services-platform:modules/security/tests/integration/services/portal/contact-match.integration.spec.js#refuses another challenge once the member is linked

Planning

Match portal memberships to CRM contacts ​

Purpose ​

How It Works ​

Relationships ​