SIGNALS Docs
Reader View

Account API contracts

Account command contract and outcome codes, expected versions and cleared fields, merge endpoints and reference manifest, operation events, and tag list validation.

Overview

This page is the integration reference for account commands over REST and MCP. For the account screens and how to use them, see Accounts.

Account fields and profiles

lawful_basis is nullable and accepts exactly consent, contract, legal_obligation, vital_interests, public_task, or legitimate_interests. These Article 6 values are fixed, with readable labels in the account form. Purpose-specific privacy assignments retain their evidence, expiry and review controls independently.

external_ref is an optional reference supplied by an integration or import to match account identities. Account search and duplicate suggestions use it with identity permissions. is_bookable controls resource selection and rental venue eligibility; is_location identifies a location. Both are booleans. Saved views and exports use is_bookable for booking filters and sorts. The account list endpoint retains its own published filter and sort allowlists.

Account customer_tax_profile_id and supplier_tax_profile_id both reference /v1/customer_tax_profiles; include customerTaxProfile or supplierTaxProfile to read the related profile’s id and name.

REST, MCP and account webhook responses return a typed profile. Company and Venue share the commercial field set; Contact and User have their own shapes. Create and update payloads accept the documented individual fields such as account_number, rating, title and department at the top level. Fields restricted by identity, commercial or credit permissions are omitted from the response profile.

Profile field Type Meaning and account types
id integer Account identifier; all types.
number string Customer or supplier account number; Company and Venue. Empty when unassigned.
customer_tax_profile_id integer or null Customer tax profile; Company and Venue.
cash boolean Payment required without credit; Company and Venue, with credit visibility.
on_stop boolean Credit commitments blocked; Company and Venue, with credit visibility.
rating integer, 0–5 Account star rating; 0 means unrated. Company and Venue.
owner_id integer or null Responsible staff account; Company and Venue.
rate_band_id, rate_band_tier_id, discount_group_id integer or null Assigned pricing category, tier and discount group; Company and Venue.
tax_number string Tax registration number; Company and Venue. Empty when unassigned.
tax_number_validated boolean or null Most recent tax validation outcome; Company and Venue.
tax_number_validated_at ISO 8601 string or null Tax validation time; Company and Venue.
tax_number_validation object or null Provider tax validation evidence; Company and Venue.
peppol_id string Electronic invoicing participant identifier; Company and Venue. Empty when unassigned.
chamber_of_commerce_number string or null Company registration identifier; Company and Venue.
global_location_number string Global location identifier; Company and Venue. Empty when unassigned.
invoice_term integer or null Invoice payment term identifier; Company and Venue.
invoice_term_length integer Payment term duration in days; Company and Venue.
credit_limit integer or null Credit ceiling in minor currency units; null means unlimited. Company, Venue and Contact, with credit visibility.
title, department string or null Contact job title and department; Contact.

User profiles contain only id. Profile schemas enumerate the allowed fields for each account type and reject additional properties.

Expected versions and cleared fields

Account responses include aggregate_version and lifecycle_state. API and other interactive callers may send the version back as expected_version; a stale version rejects the complete update. Omitting the version provides no concurrency guarantee. Nullable fields use null-means-unchanged behaviour. To clear one, send its name in clear_fields. Account type changes use the separately authorized, locked conversion command and are rejected after material use.

Account create and update commands accept tag_list as a list of strings, null, or an omitted field. Associative or sparse tag maps are refused on tag_list without echoing their keys into validation messages or stored idempotency responses. Invalid items in a valid list retain numeric field paths such as tag_list.0.

Merge endpoints

Generic MCP execute-endpoint refuses account deletion, archive, merge and anonymisation with mcp_confirmation_required. Use the dedicated tool with explicit confirmation when available, or the authenticated API.

Use POST /api/v1/accounts/{account}/merge-preview before POST /api/v1/accounts/{account}/merge. Send secondary_id to both. For a protected execution, also send the preview's manifest_digest, preview_hash, canonical_version as expected_primary_version, source_version as expected_secondary_version, a UUID command_id, and an operator reason. An idempotency key is required at the HTTP boundary.

Reading a merged source ID through GET /api/v1/accounts/{source} returns the canonical account and meta.merge_resolution with the source ID, canonical ID, and receipt ID. The canonical search index also retains merged source names and IDs. A compensating unmerge plan lists only pre-declared mutable references and expires after seven days; it is a plan for controlled remediation, not an automatic reversal.

Lifecycle states are active, inactive, archived, merged_alias, privacy_restricted, and purge_pending. The API DELETE endpoint performs a soft archive and publishes account.deleted; the explicit archive action publishes account.archived.

Association scope in a merge

AccountReferenceManifest classifies each registered reference as repoint, resolve, preserve, block, or drop. These classifications are separate from its privacy disposition: moving an association does not erase its personal data.

Manifest classification Examples and boundary
repoint Rental customer, venue and owner references; relationships; warehouse access; direct contact details and custom-field associations. The executor applies the declared adapter and conflict policy.
resolve Membership conflicts and invoice ownership. The invoice adapter repoints mutable invoices and preserves issued invoices.
preserve Rental-version recipients and accepting parties, merge receipts, credit decisions and overrides, audit records and document provenance. These facts remain associated with their recorded source.
block Staff identities and account API identities. A CRM merge cannot silently transfer authentication ownership.
drop Declared favourites, recently viewed items and recent searches. This does not authorize deletion of legal or historical evidence.

Read the actual preview's manifest digest, counts and conflict policies before execution. A new plugin or schema reference must be classified; this table is a guide to the declared manifest, not a promise that every association has been transferred or erased.

Operation events and delivery

Account writers publish typed AccountOperationOccurred facts internally after the owning transaction commits. Each operation uses schema version 1 and a deterministic event ID derived from its type and persisted operation identity. The existing encrypted account_mutation_effects repository retains publication intent; a listener failure leaves the same intent pending for recovery. Subscribers must deduplicate by event ID because recovery can invoke a listener again after a partial failure. A rollback discards the intent and its callback.

External publication is a separate catalogue decision. Credit decisions, reservation release and history rebuild remain internal facts. Protected relationship and privacy events are withheld from webhook and plugin subscriptions; an override grant is webhook-visible but not plugin-visible. Account webhook payloads retain recipient field redaction and ref, with an event_id and schema_version stamped once before subscriber fan-out when the producer did not supply them. Delivery retries retain the persisted outbox payload and identifier. HTTP delivery is at least once.

Identical persisted operation identities are retries. An unchanged relationship, a completed merge command and an already released reservation do not create a second operation. Hold placement and override grant have no universal command key: separate equal-payload calls create distinct UUID identities. History rebuild reports an internal fact only when projection freshness changes; it does not introduce an external subscription. Existing command-specific strict or best-effort outbox failure policies remain in force.

Creation, ordinary updates, type conversion, VAT validation, merge and credit overrides require their outbox persistence to succeed. Archive and restore retain best-effort external delivery. Protected privacy and relationship operations require the internal intent to persist, but have no external outbox entitlement. A committed listener failure leaves that intent pending rather than undoing the business command. This does not make webhook HTTP delivery transactional or exactly once.

Command and operations contracts

The command-contract discovery endpoint publishes schema version 2 and describes each route's request and result contract. The publication version is not a required mutation field. Each HTTP route rejects fields outside its declared payload with HTTP 422, including schema_version, command_id and canonical_account_id on account update. expected_version supplies stale-write protection and is required when accounts.require_expected_version is enabled. Merge has its own command-id/replay rules; MCP execute-endpoint uses its invocation idempotency key. There is no universal command_id guarantee.

Archive and restore accept nullable non-negative expected_version, with the interactive version requirement controlled by accounts.require_expected_version; undeclared schema_version, command_id and canonical_account_id fields return HTTP 422. Merge and merge preview take the primary account from the route and require secondary_id. Both validate an optional nullable UUID command_id; preview does not use it, while new merge execution honors it or generates one when omitted. A merge execution requires current manifest_digest and preview_hash except on matching completed replay, and the interactive version guard applies independently to both accounts. These merge fields are separate from HTTP Idempotency-Key; undeclared schema_version and canonical_account_id fields return HTTP 422. MCP applies the same HTTP request rules after its operation-specific confirmation checks.

REST returns each route's actual response body; MCP execute-endpoint wraps that body and HTTP status with invocation metadata. Stale account update returns version_conflict/409 with message, code, current_version, expected_version and errors. Relationship creation returns account.relationship.endpoint_inactive/422 or account.relationship.endpoint_type/422 with message, errors and code. Held anonymisation returns422 with account.lifecycle.hold or account.privacy.disposition_held as a prefix in message and errors.account, without a top-level code. For shared lifecycle and privacy refusals, the errors field is command-specific: ordinary account commands use account; merge and merge preview use primary_id or secondary_id. A privacy-hold message names the requested disposition. Relationship commands instead return a top-level code with errors.related_account_id: user-type endpoints refuse with "User-type accounts cannot have relationships.", while a company/venue pair refuses with "Companies and venues cannot be linked directly. Link them through a shared contact." The subtype catalogue describes both refusals. Related-account lifecycle holds and protected identities also retain their top-level relationship code. Published retryable values describe recovery guidance, not an emitted response field.

All nine categories remain visible. Updates through a merged alias refuse with422 and account.lifecycle.not_mutable as a message/errors.account prefix; they do not return an alias-resolved200 result. Merge execution with an already merged secondary account refuses a different canonical target with account.merge.alias_target_mismatch in message/errors.secondary_id. For its recorded canonical target, a new command identity refuses with account.merge.replay_command_required in message/errors.command_id; recover by replaying the original command identity with its matching actor, pair, versions, preview evidence and reason. That replay returns the retained merge result without another merge or version increment. The real rental convert-to-order boundary returns six qualified policy refusals with422, message, errors.credit and a specific code, and records an override_required credit decision: on stop, new exposure paused, cash settlement required, credit limit exceeded, incomplete currency evidence and incomplete pricing evidence. These are recovery-guidance retryable outcomes, not a response retryable field. Repeating the same decision identity replays its immutable refusal; correcting policy or evidence alone does not replace that decision. The installed route derives its decision identity from rental ID and aggregate version and does not accept a credit command ID or override ID. After an authorized rental correction advances the aggregate version, a new commitment evaluates the current evidence. The credit_denied category is explicitly unavailable on published transports: customer eligibility is checked before this credit producer, and its policy refusals are recorded as override_required. The internal service can record rental_identity_ineligible/denied; this publication does not invent a direct credit-decision endpoint. The read-only purge-eligibility endpoint exposes the existing retained-dependency refusal as422, with account.lifecycle.retained_dependency prefixed in message and errors.account. It neither deletes the account nor authorizes a later purge. Account-bound privacy-case progress returns207/privacy_case_partial when the case or any repository is failed or blocked, and200/privacy_case_status otherwise. These permission-protected named routes are callable through MCP execute-endpoint. Progress includes only case/account IDs, case state and per-state repository counts; it does not execute repositories or expose private authority, reasons, verification references, exceptions or payloads. The command map includes every account-scoped write route that can reach the shared merged-alias refusal: account create/update/archive/restore/anonymise, merge execution and preview, relationship create/delete, address/email/phone/link create/update/delete, statement email, conversation create, and notification preferences update. The global address create/update/delete routes are also listed because they enforce the same account-owner lifecycle guard. Their addressable parent must remain an authorized mutable account. It also includes the rental commitment producer and the two account-bound progress reads. Each map entry is an existing named REST route callable through MCP execute-endpoint. A merged alias refuses before a nested resource is looked up; this map does not promise alias resolution or a successful write. This publication is unfinished qualification evidence, not proof of every producer.

Rental commitment eligibility has additional plain validation variants: message plus errors.account_id or errors.venue_id, without a top-level code or code prefix. A Venue, User or other non-customer account type refuses with "The rental customer must be a Company or Contact." Staff-linked and previously anonymised customers refuse with "The rental customer must be active and eligible for commercial work." A supplied venue must be an active bookable Venue; a wrong subtype, inactive or unbookable venue returns the same venue validation message. The category's validation_variants publish these actual fields and messages separately from relationship codes. Correct the selected identity and retry with a new MCP invocation key; the original completed refusal remains immutable.

The schema2 uncoded rental variants are:

Category Variant Command HTTP status Retry guidance Envelope Field Message Transports
account_inactive rental_customer rental.commitment 422 false validation account_id The rental customer must be active and eligible for commercial work. REST, MCP
account_inactive rental_venue rental.commitment 422 false validation venue_id The rental venue must be an active bookable Venue. REST, MCP
account_wrong_subtype rental_customer rental.commitment 422 false validation account_id The rental customer must be a Company or Contact. REST, MCP
account_wrong_subtype rental_venue rental.commitment 422 false validation venue_id The rental venue must be an active bookable Venue. REST, MCP

Direct curated MCP command discovery is published separately in mcp_commands. The Account custom-field command is account.custom_fields.update → set-entity-custom-field-values. It requires module_type=Account, entity_id and values, accepts nullable non-negative expected_version subject to accounts.require_expected_version, and ignores schema_version, command_id and canonical_account_id. Stale writes return JSON error content with status409, message, code=version_conflict, current_version, expected_version and errors. Merged aliases return status422 with the lifecycle prefix in message/errors.account. These are direct tool bodies, without an execute-endpoint wrapper or HTTP idempotency receipt; retry against the canonical account and its current version.

The schema2 outcome catalogue is:

Outcome code HTTP status Retry guidance
version_conflict 409 true
account.relationship.endpoint_inactive 422 false
account.relationship.endpoint_type 422 false
credit_account_on_stop 422 true
credit_new_exposure_paused 422 true
credit_cash_settlement_required 422 true
credit_limit_exceeded 422 true
credit_currency_incomplete 422 true
credit_pricing_incomplete 422 true
account.lifecycle.not_mutable 422 false
account.merge.alias_target_mismatch 422 false
account.merge.replay_command_required 422 true
account.lifecycle.hold 422 true
account.privacy.disposition_held 422 true
account.lifecycle.retained_dependency 422 true
privacy_case_partial 207 true

The schema2 category catalogue is:

Category State Available Outcome codes Command Envelope Transports Reason
account_version_conflict mapped - version_conflict account.update version_conflict REST, MCP -
account_alias_resolved mapped - account.lifecycle.not_mutable, account.merge.alias_target_mismatch, account.merge.replay_command_required account.update validation REST, MCP -
account_inactive mapped - account.relationship.endpoint_inactive account.relationship.create coded_validation REST, MCP -
account_wrong_subtype mapped - account.relationship.endpoint_type account.relationship.create coded_validation REST, MCP -
credit_denied OPEN false - - - - No denied-decision transport is published. Rental commitment checks customer identity before credit evaluation; policy refusals record override_required.
credit_override_required mapped - credit_account_on_stop, credit_new_exposure_paused, credit_cash_settlement_required, credit_limit_exceeded, credit_currency_incomplete, credit_pricing_incomplete rental.commitment coded_validation REST, MCP -
privacy_subject_held mapped - account.lifecycle.hold, account.privacy.disposition_held account.anonymise validation REST, MCP -
retention_blocked mapped - account.lifecycle.retained_dependency account.purge.eligibility validation REST, MCP -
privacy_case_partial mapped - privacy_case_partial account.privacy.case.status privacy_case_status REST, MCP -

The read endpoints are GET /api/v1/accounts/{account}/purge-eligibility (accounts.view, accounts.privacy.purge and accounts:read) and GET /api/v1/accounts/{account}/privacy-cases/{privacyCase} (accounts.view, accounts.privacy.case and accounts:read). Purge eligibility includes retained soft-deleted accounts; case progress requires the exact canonical account/case association and returns404 for another account. Neither read creates a mutation idempotency receipt. Privacy-case creation, approval and execution remain separate internal operations.

Ownership and rates

Account requests, responses, filters and webhook objects use owner_id for ownership. It references an account, including a linked user account. Nested company and venue links use the same identifier. Rental-project owner_id references a user; report audiences and schedule recipients also reference users.

is_location is boolean. The rates object groups per_day, per_hour, per_distance and flat. Requests accept non-negative integer minor currency units; responses return decimal strings. A partial update changes only supplied rates. The account id is its identity. Command contracts identify their format with publication_format; spreadsheet imports use spreadsheet_migration and migration_ref.

Integration identities and synchronisation

Use PUT /api/v1/accounts/by-external-ref/{ref} to create or update an account by its integration reference, or GET /api/v1/accounts?filter[external_ref][eq]=sync-company-42 to read it. Accounts also support nested provider mappings and reverse lookup. See Integration identities for request and response examples.

For incremental reads, use filter[updated_at][gte] and include_deleted=true. List rows expose deleted_at and merged identities expose merged_into_account_id; follow that ID to the canonical account instead of creating a replacement. Timestamp filters, cursor paging, identity permissions and normal list restrictions still apply. See sync conventions.