SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Accounts

Manage contacts, companies, venues, and user accounts in the CRM.

Overview

Accounts is the universal entity in Signals — contacts, companies, venues, and user accounts are all stored as accounts differentiated by their account_type. This unified approach allows shared contact details, custom fields, and relationships across all entity types.

Type Description
Contact Individual people (clients, crew, suppliers)
Company Companies, businesses, trusts
Venue Physical locations for events
User System users with login credentials

API writes use owner_id for the responsible account ID. Company and Venue responses include this value at profile.owner_id, including nested account payloads and webhook data. Account ownership links to an account record; rental-project ownership links to a user record.

Subtypes and permitted conversion

All four types share the account identity and contact-point model. Default CRM lists include Company, Venue and Contact; User identities belong to staff administration. Shared storage does not make the types interchangeable.

The is_bookable flag allows an account to be selected as a resource. lawful_basis selects one of the six Article 6 processing grounds. The account form presents the fixed grounds as readable labels. The optional external_ref is an integration or import reference used by account search and duplicate suggestions. Responses group type-specific fields under profile; Company and Venue carry commercial settings and a 0–5 star rating, Contact carries job details and credit visibility, and User carries its identifier.

While you type an account's name, the form lists Possible duplicate accounts (when AI embeddings are enabled). Each match says why it is listed: Same name, Same tax number (compared ignoring spaces and case), and — when editing an account that has them — Same email or Same phone (compared on the last nine digits); otherwise Similar name. Matches that share an identifying detail are listed first, and the account being edited is never listed as its own duplicate.

Bookable accounts can carry per-day, per-hour, per-distance and flat resource rates. The location flag identifies accounts that can be used as locations. Account imports and exports expose the individual rate columns, subject to commercial-field permissions.

Ordinary editing cannot change account_type. ConvertAccountType is a separate locked command requiring accounts.identity.edit and the configured high-risk approval policy. It checks the current lifecycle and supplied expected version. A request for the current type is a no-op; conversion to or from User requires the staff identity lifecycle. Contact, Company and Venue may be converted only before material use: declared operational, financial, relationship, warehouse-assignment and identity references can prevent conversion. Successful conversion clears fields incompatible with the target subtype and records account.type_converted; it does not reinterpret existing legal history.

The current subtype invariant rejects non-neutral title and department for Company and Venue, and non-neutral peppol_id, chamber_of_commerce_number and global_location_number for Contact. User rejects both sets. These are the implemented field checks, not an exhaustive claim that every commercial field is protected by subtype.

Lifecycle diagram

Stored lifecycle states: active, inactive, archived, merged_alias, privacy_restricted, purge_pending.

New ordinary and staff identities start in active or inactive according to their active flag. Ordinary activation and deactivation require accounts.edit and keep the stored lifecycle and active flag consistent. User active flags remain profile-managed. Anonymised, erased and purged are repository outcomes, not additional stored lifecycle states.

flowchart LR
    Active[Active] -->|Ordinary deactivate| Inactive[Inactive]
    Inactive -->|Ordinary reactivate| Active
    Mutable[Active or inactive identity] -->|Guarded soft archive| Archived[Archived]
    Archived -->|Authorised restore to active| Active[Active]
    Mutable -->|Eligible merge source| Alias[Merged alias]
    Alias -->|Read through receipt| Canonical[Canonical identity]
    Privacy[Approved privacy case] -.->|Repository-specific policy and guards| Restricted[Privacy restricted]
    Privacy -.->|Destructive work pending| Pending[Purge pending]

The solid arrows describe guarded archive, restore and merge operations, not unconditional transitions. The dotted privacy outcomes require the case policy, holds, repository adapters and retention evidence described below; they are not ordinary edit or restore routes. Active/inactive identity changes do not bypass subtype, material-reference or lifecycle guards. A merged alias cannot be restored or converted independently, and privacy-controlled states do not permit ordinary identity mutation.

Canonical relationship direction and the unique primary-company rule are described under Relationships. Only eligible active endpoints may participate; User, merged-alias, held and privacy-controlled endpoints are refused. A Contact-to-Venue or Contact-to-Contact relationship cannot become the contact's primary company. The merge classification table describes declared references only, and reading an alias resolves through its recorded receipt rather than transferring every historical fact.

Accounts List

Route: /accounts

Browse all accounts with search, type filtering, archive filtering, sorting, and bulk operations. The list is powered by the reusable DataTable component.

  • Search — filter by name (debounced, case-insensitive)
  • Type filter — chip buttons to show All, Companies, Venues, or Contacts with counts
  • Archive filter — chip buttons to show Active, Archived, or All accounts The archive filter’s Active option means not soft-deleted; it includes inactive identities. The Status column shows the active flag separately.
  • Column sorting — click column headers to sort by Name, Type, Status, or Created date
  • Column filtering — inline filters on Name (text), Type (select), and Status (select)
  • Column toggle — show or hide individual columns via the toolbar toggle button
  • Export — export the current filtered result set to CSV via the toolbar
  • Pagination — 12 accounts per page (configurable: 12, 24, 48)
  • Row selection — checkbox selection with shift-click range support
  • Bulk actions — archive selected accounts, or merge when exactly 2 are selected
Column Description
Avatar Account initials avatar
Name Clickable link to account detail page
Type Account type badge
Primary Email First primary email, or first available
Primary Phone First primary phone, or first available
Status Active or Inactive badge
Tags Associated tags
Created Creation date

Row Actions

Each row has a dropdown menu with the following actions:

  • View — open the account detail page
  • Edit — open the account edit form
  • Archive — soft-delete the account with a confirmation modal (can be restored later)
  • Restore — available when viewing archived accounts; restores the account to active

Bulk Actions

Select multiple accounts using checkboxes, then use the bulk action bar:

  • Archive Selected — archives all selected accounts with a confirmation modal
  • Merge — appears only when exactly 2 accounts are selected; opens the merge modal

Merge Modal

Selecting exactly 2 accounts and clicking Merge opens a merge modal. Choose which account to keep as the canonical record. Both accounts must have the same account_type and must be free of lifecycle holds and staff/API identity links. Preview the merge first. The preview is non-mutating and returns the manifest version and digest, account versions, conflict lists, reference counts, resolution policies, and a preview hash.

Execution locks both accounts in ID order and rejects any changed version, preview, manifest, type, state, hold, or prohibited reference. Mutable operational references move to the canonical account. Duplicate contact points, relationships, custom fields, memberships, and warehouse assignments use the recorded keep-canonical policy. Issued invoice and other legal-history references remain linked to the source record and resolve through its alias. The source becomes a soft-deleted merged_alias; it cannot be edited, restored, anonymised, or archived independently.

Adding Accounts

The toolbar Add Account button offers Add Company, Add Contact and Add Venue, each opening its creation modal. Enter the name and visible essentials, expand More details for optional fields, then save.

Account Detail

Route: /accounts/{account}

The detail page shows the account name, type and status, with the shared record navigation above and below the content. Overview is a direct link; Relationship, Trade, Docs and More group the subpages. Privacy and credit standing are available on Relationship → Governance.

Overview Tab

  • Headlines — four cards: Lifetime value, Location, Relationships and Briefing. Location opens the map when the primary address has coordinates; Relationships opens its relationship panel. In Briefing, expand the credit or outstanding verdict and choose Open the credit register or Open the invoice register. The financial registers also accept ?register=value, ?register=owed or ?register=credit. Credit uses the same tenant-wide projection as commercial decisions: open receivables, remaining active-order commitments, and live reservations in company base currency. It removes only viewer warehouse scope, keeps tenant and document-validity boundaries, and reports contributing warehouses separately. Missing currency evidence makes the result incomplete instead of mixing raw minor units. Individual invoice rows keep their own document amount and currency label — see Multi-Currency & Tax.
  • Open work — pipeline stack by state and a table of open rentals/orders
  • Briefing — up to four graded verdicts: credit standing, payment behaviour, outstanding, and next event (omitted when nothing is scheduled)
  • Sidebar — one Account panel with the account's key contact details and facts.
  • Footer — Created, Updated, and Last contact stamps.

Use Relationship → Information for profile and contact details, Relationship → Contacts for linked people or companies, Relationship → Governance for canonical identity, credit policy, privacy restriction, credit evidence and merge conflicts, and Trade → Performance for revenue and payment behaviour.

The header New Rental action opens the full rental form. An eligible Company or Contact is passed as account_id; a Contact remains the customer even when it has a primary linked Company. A Venue is passed separately as venue_id and prefills the venue only when it is active and bookable; choose an eligible Company or Contact customer separately. The New rental modal still offers Company customers only. These selections do not authorize a later commercial commitment.

Information Tab

A two-column reference grid: Profile, Commercial terms, Addresses (full width), Emails, Phones, Links, and Custom fields. Profile and commercial values edit through the account form. Addresses, emails, phones, and links keep their create/edit/delete actions on this tab. Empty contact panels show "None recorded."

Activities Tab

An itinerary spine rather than a data table: future commitments sit above a NOW rule, recorded history below. Category filters narrow the spine (All, Commitments, Financial, Communications). Audit-trail history is under Relationship → Activity.

Tabs

Tab Route Description
Overview /accounts/{account} Headlines, briefing, Open work and the Account sidebar
Governance /accounts/{account}/governance Relationship group: identity, credit and privacy standing, shown according to your permissions
Performance /accounts/{account}/performance Trade group: revenue and payment behaviour
Information /accounts/{account}/information Two-column reference grid: Profile, Commercial terms, Addresses, Emails, Phones, Links, Custom fields
Contacts /accounts/{account}/account-contacts Linked contacts or companies
Activity /accounts/{account}/activity Relationship group: audit history
Activities /accounts/{account}/activities More group: itinerary spine (future above NOW, history below)
Rentals /accounts/{account}/rentals Rental and sales rentals
Invoices /accounts/{account}/invoices Invoices linked to this account
Documents /accounts/{account}/documents Documents on the account and on its rentals and invoices, unanswered first
Custom Fields /accounts/{account}/custom-fields Custom fields for the Account module
Files /accounts/{account}/files Attachments and documents
Communications /accounts/{account}/communications Communications logged against this account

Creating & Editing Accounts

Routes: /accounts/create, /accounts/{account}/edit

The form leads with identity and the sections relevant to the account type. Expand More details for optional settings, including Tax & Pricing, Resource and Regional where applicable. Resource contains Bookable, Location and resource rates; Regional contains Locale and Default currency. Custom fields follow the main form.

Field Description Required
Name Account's name Yes
Account Type Contact, Company, Venue, or User; immutable through ordinary edit Yes
Active Whether the account is active No (default: true)
Description Free-text description No
Locale Language/region code (e.g. en-GB) No
Default Currency ISO 4217 currency code No
Customer tax profile Tax profile for billing No

Responses carry a version so a stale save is refused rather than overwriting newer work; reload the account and apply your change again. Version, clear-field and conversion rules for API callers are in Account API contracts.

Contact Details

Each account can have multiple addresses, emails, phones, and links. These are polymorphic — the same system is shared across accounts, warehouses, and future entities.

Addresses

Each address can have a label (e.g. "Head Office"), street, city, county, postcode, country, type (from the AddressType list), and a primary flag. Normalized fingerprints prevent an owner/type duplicate, and shared actions plus database keys enforce at most one primary address per owner/type. Contact-point collisions are recorded for operator review rather than silently discarded. For the global address list, geocoding, and import/export how-tos, see CRM & Addresses.

Emails

Each email has an address, type (from the EmailType list), and a primary flag. Case and surrounding whitespace are normalized for duplicate detection while the entered display value is retained.

Phones

Each phone has a number, type (from the PhoneType list), and a primary flag. Formatting punctuation is normalized for duplicate detection while the entered display value is retained.

Each link has a URL, optional display name, and type (from the LinkType list).

Relationships

Contacts can be linked to companies, venues, or another contact with a relationship type label (e.g. "employee", "contractor"). Storage is canonical: Contact→Company and Contact→Venue always save the contact first; Contact↔Contact uses ID order. One unordered pair can exist once. Only Contact→Company may be the unique primary company for that contact. Both endpoints must be active, and User accounts cannot participate. Duplicate or ambiguous rows are held for review rather than guessed.

Duplicate or ambiguous relationships held for review are inspected with the operator commands in Account data repair.

Custom Fields

Custom fields configured for the "Account" module appear on the Custom Fields tab and in the Information grid, grouped by their custom field group. On the Custom Fields tab, empty fields display "Not set".

Merge

Open Admin → System → Merge recommendations (/admin/settings/merge-recommendations) with accounts.merge permission. Recommendations are advisory: choose Preview merge, review the pair, then confirm only when both records represent the same identity. The paginated table shows each pair, its match score and the signals you are allowed to see. Row actions include Preview merge, which opens the merge preview with both accounts selected, and Not a duplicate, which asks for confirmation before dismissing a recommendation. Links to /accounts/merge-recommendations redirect here. You can also select exactly two rows on the Accounts list and choose Merge.

Two eligible accounts of the same type can be merged into one canonical identity. This is a classified-reference merge, not complete transfer of every association or historical fact. The canonical account retains its fields. A versioned manifest decides which references move, which conflicts are resolved, which legal facts remain on the source, and which references prohibit the merge. Each successful merge writes an immutable receipt and a source-to-canonical alias. Retrying the same command_id returns the same result without applying side effects twice.

Preview a merge before running it. The merge endpoints, protected-execution fields, alias reads and the reference manifest are described in Account API contracts.

Baseline merge limitations

The current executor moves classified mutable references and resolves declared conflicts. For example, mutable invoice ownership can move, while issued invoices retain their source account and historical display facts; rental-version recipients, audit/credit evidence, and merge receipts also preserve provenance. Canonical fields win field conflicts, and duplicate contact points can keep the canonical row rather than copy both. Staff-linked identities and prohibited references block CRM merge. The source remains a merged alias, not an erased identity.

A preview, manifest classification, alias or receipt records what that merge command did; it does not guarantee that every polymorphic, serialised, plugin, external or previously partially merged reference moved. Historical partial merges and split ownership may still need separate remediation. Complete merge transfer is not yet guaranteed.

Lifecycle and retained data

These operations have different meanings and must not be treated as synonyms:

Operation/state Meaning
Inactive The identity still exists, but it is not eligible for new customer or venue work.
Archived A reversible soft archive. Ordinary selection hides the account; authorised restore is allowed when lifecycle guards pass.
Merged alias The source identity points to its canonical account. The source record and legal references remain; the alias cannot be independently edited or restored.
Privacy restricted A privacy lifecycle and repository disposition. Verify the actual adapter outcome and consumer access controls; the state label alone does not prove restriction of every retained copy. The authentication adapter can revoke credentials and sessions.
Anonymised or erased A privacy-case disposition for registered records. Mutable identifiers may be removed or pseudonymised; retained exceptions and records without full controls must be reviewed. This is not a guarantee of complete PII erasure.
Purge pending Destructive work is authorised but not yet complete. The account must not return to ordinary use.
Purged An outcome for eligible records, subject to adapter and retention evidence. Signed case evidence, legal records, merge aliases, and other explicitly retained classes are not silently deleted; the label does not prove that every subject copy is gone.

Physical purge requires purge_pending, the privacy disposition fence, complete manifest classification and no retained dependency. A merged alias cannot be purged independently. A purge receipt for one eligible repository does not authorize deleting the canonical history or another retained repository.

Archive and merge never claim that personal data has been erased. Anonymisation and purge are controlled privacy-case outcomes, not ordinary account deletion. A completed case receipt records the policy, legal basis, repository result, affected count, and any retained exception. Review those results within their demonstrated scope; a signed receipt alone is not whole-system erasure proof.

Credit control

The Overview headlines and credit register show tenant-wide exposure and headroom. These are presentation values: every new commercial command rechecks credit at the point of action. On-stop and cash-account flags, credit limits, overrides and rollout modes are configured and explained in Account credit control.

Privacy cases, holds, and subject exports

Open Admin → Users & Security → Privacy Operations to handle subject access, restriction, anonymisation, erasure and purge requests, and to place legal holds. The case workflow, repository registry, retention policies and completion evidence are described in Account privacy and erasure.

Permissions

Permission Description
accounts.view View account details
accounts.create Create new accounts
accounts.edit Edit existing accounts
accounts.delete Permission for the account soft-archive endpoint
accounts.identity.view / accounts.identity.edit View or edit identity and subtype fields
accounts.contact-pii.view / accounts.contact-pii.edit View or edit addresses, emails, and phone numbers
accounts.commercial.view / accounts.commercial.edit View or edit tax, terms, and commercial fields
accounts.credit.view / accounts.credit.decide / accounts.credit.override View exposure, make a decision, or perform a separately authorized override
accounts.merge / accounts.archive / accounts.restore Run distinct lifecycle operations
accounts.privacy.* Manage privacy cases, exports, anonymisation, holds, and purge; Admin-only by default