Moss Data Model Overview

This document provides an overview of the core data models exposed through the Moss API. These entities represent the fundamental building blocks of the spend management functionalities at Moss.

Core Entities

Entity	Description	API Endpoints
Department	A higher-level organisational unit composed of multiple teams. Departments are used for broader financial controlling, budgeting, and reporting structures.	GET /v1/departments GET /v1/departments/{id}
Dimension Item	A single selectable value within a dimension (e.g., "Project A", "Dept Sales").	GET /v1/dimension-items GET /v1/dimension-items/{id}
Dimension	A tagging axis for multi-dimensional accounting (e.g., project, department, tracking category). Moss has two fixed dimensions, Cost Center and Cost Carrier, and supports additional custom dimensions.	GET /v1/dimensions GET /v1/dimensions/{id}
Expense Account	The nominal ledger account (chart-of-accounts item) to which an expense is posted (e.g., Travel, Software).	GET /v1/expense-accounts GET /v1/expense-accounts/{id}
Expense	A spend item (card transaction, invoice, or reimbursement) with accounting attributes and audit metadata. Expenses may be split into line items, each with its own expense account, tax rates, and dimensions.	GET /v1/expenses
File	A file (document) attached to an expense.	POST /v1/files/search-query GET /v1/files/{fileId}/content
Organisation	The legal entity or company account in Moss. It represents the top-level scope under which users, teams, expenses, suppliers, and financial configurations are managed.	n/a
Payment Term	The agreed conditions defining when an invoice is due (e.g., number of days after issue date or end of month). Used to calculate invoice due dates and manage accounts payable timing.	GET /v1/payment-terms GET /v1/payment-terms/{id}
Supplier	The vendor or creditor to whom payments or invoices are owed.	GET /v1/suppliers GET /v1/suppliers/{id}
Tax Rate	Tax rate object describing VAT/tax treatment (percentage, code, country). Used to calculate VAT and map tax codes to ERPs and accounting systems.	GET /v1/tax-rates GET /v1/tax-rates/{id}
Team	An organisational unit within an organisation. Every user belongs to a team, which is typically used for operational grouping, approval flows, and reporting.	GET /v1/teams GET /v1/teams/{id}
User	A person with a Moss account who can act in the system.	GET /v1/users GET /v1/users/{id}

Expense Types and Subtypes

The Moss API supports three distinct expense types, each with its own set of subtypes:

Expense Type	Subtypes	Description
Card Transaction	EXPENSE REFUND CASHBACK	Expenses originating from card transactions, including standard purchases, refunds, and cashback credits.
Invoice	EXPENSE CREDIT_NOTE	Supplier invoices and associated credit notes for returns or adjustments.
Reimbursement	EXPENSE	Employee expense reimbursements for out-of-pocket spending, including business purchases, mileage, and per diems.

Expense Status Lifecycle

Expenses progress through various statuses during their lifecycle. The following table describes each status in the order they typically occur:

Status	Description
DRAFT	Expense is being prepared (not yet submitted)
SUBMITTED	Expense has been submitted for review
REVIEWED	Expense has been reviewed (intermediate review step)
APPROVED	Expense has been approved by the approver
REJECTED	Expense has been rejected by the approver
FLAGGED	Expense has been flagged for attention (requires review or action)
APPROVAL_SKIPPED	Approval was skipped for this expense (auto-approved or no approval required)
VERIFIED	Expense has been verified (final verification step). Only applicable to invoices.
VERIFICATION_SKIPPED	Verification was skipped for this expense. Only applicable to invoices.
COMPLETED	Expense processing has been completed (final state for successful expenses)
DELETED	Expense has been deleted
INHERITED	Status inherited from parent expense (specifically for line items)
UNKNOWN_DEFAULT_OPEN_API	Unknown status value (fallback for future statuses not yet known to the API client)

Expense Line Structure

Each expense is composed of one or more line items represented as line objects within the expense object. This structure allows for:

• Itemized expenses: Breaking down a single transaction into multiple accounting lines
• Split expenses: Allocating costs across different expense accounts, tax rates, or dimensions
• Detailed attribution: Assigning specific cost centers, cost carriers, or projects at the line level

Line Subtypes

Expense lines support two subtypes to handle adjustments and corrections:

Line Subtype	Description
MAIN	Standard expense line representing actual costs or charges.
CORRECTION	Negative adjustment line that reduces the header total. Used for rounding fixes, corrections, or other reductions to reconcile the line-level detail with the header amount.

Expense Files

Files are always attached to an expense. Because expenses might have line objects, retrieving all files for a top-level expense requires traversing (recursively) its line items as well.

Common Patterns

Timestamps

All data models include timestamp fields in ISO 8601 format:

• createTime: Resource creation timestamp
• updateTime: Resource last update timestamp
• deleteTime (where applicable): Resource deletion timestamp (nullable)

Organization Scope

All resources are scoped to an organization via the organisationId field.