Account

Account represents a bank or financial account (deposit, credit, loan, investment, payroll, or other) held by a workspace, company, or individual. It is the primary model the connector layer (Plaid, Qonto, etc.) writes synced bank accounts into, and it is also used to record counterparty accounts extracted from invoice payment means. Key associations are to Workspace (tenant scope), Company (account holder or the workspace's own company), People (individual holder), a bank Company via bank_company, a source WorkspaceConnector tracking provenance, and one-to-many AccountWorkspaceConnectors for multi-connector sync audit. The ownership field distinguishes workspace-held accounts from counterparty accounts from unclassified legacy rows.

API operations

Data model

Attributes

Relationships

System-computed

• account_id: generated via gen_random_uuid() on INSERT; unique constraint enforced at the database level.
• created_at: set once on INSERT via MikroORM onCreate lifecycle hook; never supplied by callers.
• updated_at: set on INSERT and refreshed on every UPDATE via MikroORM onCreate/onUpdate lifecycle hooks.
• deleted_at: soft-delete sentinel. When set, the account is excluded from all standard queries. The partial index idx_accounts_workspace_external_id_active uses WHERE deleted_at IS NULL AND account_external_id IS NOT NULL for the Plaid-sync hot-path dedup lookup.
• ownership default: defaults to 'unknown' at the database level for all new rows. Backfilled to 'workspace' by Migration20260527120000_account_ownership where source_workspace_connector_pk IS NOT NULL, or where a PaymentMeans row links the account to the workspace's own company (payment_means.account_pk = accounts.pk AND payment_means.company_pk = workspace.own_company_pk).
• account_external_id dedup: the partial unique index idx_accounts_workspace_external_id_active on (workspace_pk, account_external_id) WHERE deleted_at IS NULL AND account_external_id IS NOT NULL is the connector-layer dedup key. Plaid sync uses this to find an existing account before creating a new one, preventing re-linking on reconnect.
• source_workspace_connector provenance: when source_workspace_connector_pk IS NOT NULL, the account was created by the connector pipeline and ownership should be 'workspace'. A NULL source_workspace_connector_pk means the account was created via a fallback path (manual entry, invoice payment means extraction) and ownership defaults to 'unknown' pending classification.
• bank_company recovery: when bank_company_pk IS NULL, the bank identity may be recoverable from raw_data (look for raw_data->>'institution_name' or raw_data->'institution'->>'name') or inferred from the IBAN bank code prefix (FR IBANs: positions 5–9 = CIB) or BIC first 4 characters.
• Composite composites.yml definitions: two composites are defined for the accounts root — composite_account_summary (source_fields: account_id, bank_company.primary_media.url, account_name, currency, iban, account_number; display_type: account_summary) and composite_latest_balance_currency (source_fields: account_id, account_balances.accounting_balance; display_type: currency_amount).

Example

{
  "data": {
    "type": "account",
    "id": "a3f7c2e1-84b0-4d5e-9f12-6c8a1b0e3d7f",
    "attributes": {
      "account_external_id": "qonto_acc_EU84QNTO00001234567890",
      "type": "deposit",
      "subtype": "checking account",
      "account_name": "Qonto EUR — Operating",
      "iban": "FR7616958000010000012345678",
      "account_number": null,
      "bic": "QNTOFRP1XXX",
      "routing_number": null,
      "sort_code": null,
      "currency": "EUR",
      "digital_wallet_provider": null,
      "digital_wallet_id": null,
      "digital_wallet_type": null,
      "ownership": "workspace",
      "raw_data": {
        "institution_id": "ins_qonto",
        "institution_name": "Qonto",
        "official_name": "Qonto Business Current Account"
      },
      "created_at": "2025-03-14T09:22:11.000Z",
      "updated_at": "2026-02-01T14:05:33.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "b1e9d4f2-3301-4a8c-b7e0-9f4c2d1a5e88" }
      },
      "company": {
        "data": { "type": "company", "id": "c2a8f5e3-7712-4b9d-a1f2-8e3d0c6b4a21" }
      },
      "people": {
        "data": null
      },
      "bank_company": {
        "data": { "type": "company", "id": "d4b7e8f1-2290-4c3a-b5e7-1f9d0a2c8b64" }
      },
      "source_workspace_connector": {
        "data": { "type": "workspace_connector", "id": "e5c9d1a2-4403-4e7b-c2f3-2a4b5d0e9c77" }
      },
      "workspace_connector": {
        "data": { "type": "workspace_connector", "id": "e5c9d1a2-4403-4e7b-c2f3-2a4b5d0e9c77" }
      },
      "account_workspace_connectors": {
        "data": [
          { "type": "account_workspace_connector", "id": "f6d0e2b3-5514-4f8c-d3g4-3b5c6e1f0d88" }
        ]
      }
    }
  }
}