Skip to content

Customers, contacts and recipient roles

A customer is a household or an organization with a relationship to the company providing the service. A contact is a person linked to that customer. Contact, quote recipient, invoice recipient and household-work deduction recipient are separate roles. One person can hold several roles, but selecting one role does not establish the others.

Toolora separates shared party identity from the active company’s relationship and private profile. The customer’s projects refer to that party within their own company context. A contact relationship does not itself grant customer portal access.

The record model connects these identities with their key, scope and enforcement rules across commercial and financial records.

Record Owns Relationship and cardinality
parties, with organizations or persons Shared identity and party kind A party can be referenced by several companies. A party UUID is not a login or a company membership.
party_tenant_relationships (PTR) One company’s customer relationship, status, responsibility, payment settings and recipient defaults At most one row per party/company pair. Relationship types include leads as well as customers; is_customer determines the customer classification.
organization_tenant_profiles, household_tenant_profiles Company-specific customer presentation Profiles belong to a company and the relevant organization/household. A household has no organization number; its local profile supplies its name and address.
person_tenant_profiles A company’s contact name, email and phone for a person-party At most one profile per company/person-party pair. Several customer memberships in that company can use the same profile.
party_memberships The person’s role at one customer, title, validity dates and primary-contact flag Unique company/person/customer combination. A person can have several customer memberships; a customer can have several contacts.
auth.users, people Login identity and the person’s membership in a company These support authentication, staff/worker roles and capabilities. A contact profile can exist without either a login or a people row.
flowchart TD
C[Company] -->|0..many| R[Customer relationships]
R -->|exactly one| P[Shared household or organization party]
C -->|0..many| CP[Customer profiles]
CP --> P
C -->|0..many| M[Customer memberships]
M -->|one customer| P
M -->|one person| PP[Shared person-party]
C -->|0..many| TP[Contact profiles]
TP -->|one person| PP
C -->|0..many| PE[People company memberships]
PE --> PP
PE -->|optional login link| U[Auth user]
Customer and contact relationships. Shared parties are referenced through company-owned relationships and profiles; arrows identify references rather than access grants.

Sharing a party does not share a company’s contact details, notes or commercial relationship. Reads must retain company scope; resource authorization is separate from the existence of a foreign key. Display views resolve current presentation; they do not own the customer or replace its underlying records.

Current customer creation uses an organization or household. Even a private customer consisting of one person uses a household customer and a person contact. The database’s person-PTR trigger rejects new bare-person customer relationships. Existing person-customer rows can still appear through historical read compatibility. They are not a pattern for new customer creation.

The organization helper can reuse an organization identified by its Swedish registration number and adds the company relationship if absent. Company profile edits remain separate from shared organization identity. A household has no equivalent natural registration key. The current form uses create_household_with_first_member with a request UUID: customer creation and the optional first member commit together, and the same actor/request can retry the same input without creating another household.

For household contacts, add_household_member creates a distinct person from an explicit request identity. Alex and Sam can share household@example.test and remain two people. Reusing a request UUID with different input is rejected. link_existing_person_to_household instead links a specifically selected active, non-worker staff person in the company. It preserves an existing active membership and seeds a contact profile only if missing. This operation is not a general email-based identity merge.

Organization contact creation still uses ensure_person_contact. That legacy body looks for a case-insensitive email match in the company’s contact profiles and can reuse and update the matched person’s profile. It differs from explicit household identity creation. Do not assume every contact path preserves two people who share an email address. Changing organization identity matching requires its own migration and product decision.

Import identifiers are also scoped. A household profile’s non-null source_external_id is unique within its company. The later bygglet_customer_refs table can map several source customer IDs to one party; one profile field is therefore not an exhaustive record of imported identities. These constraints preserve source references rather than proving current contact or agreement authority.

Membership validity uses inclusive valid_from and valid_to dates; a missing endpoint is open. The contact list can include historical memberships. Recipient selection considers the currently valid ones. A primary flag is a selection hint, not a guarantee that exactly one primary contact exists.

The contact editor updates a company profile and, when requested, the selected customer membership’s role/title. It binds the membership to the person, customer and company before saving the profile. Its compensating rollback uses the same identity scope. Profile editing does not change the Auth email or a staff people record. Because the profile is per person/company, its current values are also used by that person’s other customer memberships in the company.

The membership and profile updates are separate HTTP transactions. A failed profile update triggers an attempted membership rollback; this is not a database transaction or a general concurrency guarantee. Profile-only editing checks the membership but leaves its role unchanged. The sent-quote editor can use this path to correct current contact details without modifying an earlier accepted agreement.

Role Current source What the role establishes
Customer contact PTR contact choice, otherwise one active primary or sole member Default communication contact. Ambiguous membership sets remain unresolved.
Quote recipient PTR quote choice, otherwise the contact selection A default for a new quote choice. The quote’s recipients and acceptance evidence have their own lifecycle.
Invoice recipient PTR invoice choice, otherwise the contact selection; explicit invoice_email takes precedence Default delivery address. An invoice can have a separate mailbox without a selected person.
Deduction recipient Saved recipient catalogue, then an explicit allocation for the job Candidate identity and a reviewed share for ROT/RUT. No implicit contact fallback or catalogue default percentages.
Portal reader Customer grant/historical self-access, or an independently qualifying direct project contact under the current portal contract Admission to customer information, subject to the portal’s own checks and publication.

Communication-role defaults resolve through v_customer_recipient_roles. For contact, quote and invoice, an explicit role choice takes precedence, followed by the saved contact and an unambiguous active member. One active primary wins; otherwise one sole active member can be used. An explicit choice whose membership has expired stays unresolved instead of selecting someone else. Invoice delivery can fall back to the shared organization’s email when there is no selected person; an explicit billing mailbox still has first priority.

The view’s rot row retains an explicit legacy role field, but the current recipient editor only offers the three communication roles. The saved deduction catalogue has its own API, revision and selected people. The current workflow does not infer a deduction recipient from the communication contact. See deduction allocations for the financial subject and its distinct source/evidence limits.

Defaults help create records. They do not continuously rewrite saved documents. A new native invoice draft captures billing_email_snapshot and fk_billing_recipient_party. Changing its customer resets those choices through the draft rules; changing a PTR default does not rewrite an existing invoice. The invoice guard locks the recipient after numbering, export lock or movement out of draft. Sent quote and accepted recipient evidence likewise remain owned by their versioned records. Correcting today’s contact profile is not proof that an earlier document was sent to the corrected address.

Alex Example is the contact, quote recipient, invoice recipient and sole selected deduction recipient for Household Example. These choices can all reference Alex’s person-party. The deduction still needs verified person/property data and a job-specific allocation. Current portal admission requires a qualifying customer relation or direct project contact; being a recipient alone supplies neither.

At Example Organization, Alex coordinates work, Sam receives quotes and an accounts mailbox receives invoices. The mailbox need not identify either person. Removing Sam’s current membership makes a saved default unresolved but does not erase an accepted quote or revoke a separate portal grant. Publication determines which project version an admitted reader sees; see publication and record ownership.

The focused contact, recipient-editor and work-order hook selection passed 22 frontend tests with substituted Supabase clients. The new membership/person mismatch case fails against the previous role-edit implementation and passes with the person predicate. These tests establish browser query construction and error handling, not live RLS, transaction rollback or concurrent edits.

Database tests for contact isolation/audit, household retries, linking staff and source identity were inspected alongside active migrations. They were not run in this documentation review. The portal reference now owns the November 17 replacement: shared discovery/detail admission over paired live identities, independent customer and direct-project bases, and stronger operation checks. This update supersedes the earlier discovery mismatch; the editor tests above retain their original scope.