Common Use Cases

This page describes the most common integration patterns for the Moss API, with the relevant endpoints for each.

If you are new to the API, start with the Overview and Data Model.

---

Reporting and Insights

Use the API to feed expense data into external analytics tools for reporting beyond what the Moss UI provides.

What you can build

Spend analytics dashboards — Load expenses into a data warehouse (e.g., BigQuery, Snowflake) and connect a BI tool (e.g., Looker Studio, Metabase, Power BI). Segment spend by supplier, team, expense account, cost centre, or custom dimension. For organisations with multiple entities, centralise data across all of them into a single view.

Cash flow and liquidity management — Feed bank transaction data into cash management tools (e.g., Agicap, Atlar) or spreadsheets to build forecasts and monitor liquidity across accounts and entities.

Budget holder portals — Combine expense data with revenue data to give each department or cost centre owner a real-time P&L view, removing the dependency on month-end reports.

AI-powered expense review — Send expense data to an AI tool (e.g., Claude via a custom MCP server) to detect anomalies, flag duplicate subscriptions, or generate natural-language spend summaries.

Key endpoints

Endpoint	Description
GET /v1/expenses	Card transactions, invoices, and reimbursements with full accounting detail (amounts, expense accounts, tax rates, dimensions, statuses)
GET /v1/expense-accounts	Chart of accounts — the ledger accounts expenses are posted to
GET /v1/dimensions	Accounting dimensions (cost centres, cost carriers, custom dimensions)
GET /v1/dimension-items	Values within a dimension (e.g., individual cost centres or project codes)
GET /v1/teams	Teams — useful for grouping spend by team
GET /v1/departments	Departments — useful for higher-level aggregation
GET /v1/suppliers	Supplier master data — useful for spend-by-vendor analysis
GET /v1/users	Users — useful for attributing spend to individuals

Example: daily sync to a data warehouse

A common pattern is a scheduled job (cron, Airflow, n8n) that runs daily, following an initial historical load:

1. Call GET /v1/expenses with a date filter to retrieve expenses created or updated since the last sync.
2. The response includes reference IDs for related entities (expense accounts, cost centres, suppliers). Join with the corresponding endpoints to enrich the data.
3. Load the results into your warehouse and build dashboards on top.

For large result sets, paginate using page and page_size. See Pagination for details.

---

Project and Job Management Integrations

Service businesses — agencies, consultancies, construction firms — often need to track spend against client projects or jobs. The API allows you to sync project structures into Moss and retrieve enriched expense data for downstream reporting.

What you can build

Automatic project creation — When a new project is created in your project management tool (e.g., Paprika, HelloHQ, Scoro), create a corresponding dimension item in Moss via API. This keeps project lists synchronised without manual data entry.

Project P&L tracking — Retrieve expenses tagged with project codes and load them into your data warehouse to build per-project profit-and-loss views.

Client rebilling — Expenses in Moss carry project or client codes as dimension values. Retrieve them to generate accurate client invoices based on actual costs incurred.

Key endpoints

Endpoint	Description
POST /v1/dimension-items	Create a new dimension value (e.g., a project code)
PATCH /v1/dimension-items/{id}	Update or deactivate a dimension item
GET /v1/expenses	Retrieve expenses with their dimension values to determine which project each expense belongs to
GET /v1/dimensions	List available dimensions to identify the one representing projects
GET /v1/dimension-items	List all values within a given dimension

Example: syncing projects from a project management tool

1. When a new project is created in your project management tool, call POST /v1/dimension-items to create a matching entry in the relevant dimension in Moss.
2. Your finance team tags expenses in Moss with the project code.
3. A scheduled job calls GET /v1/expenses, filters by the project dimension, and pushes the data to your warehouse for P&L tracking.

Important note: If you are using accounting integrations built by Moss, and if you have enabled automated import of dimension items data from your accounting system to Moss, you will not be able to create or update dimension items directly via the API in Moss. Requests will return ERR_MANAGED_RESOURCE_IMMUTABLE. See your accounting integration settings for details.

---

Accounting Software Integrations

If your ERP or accounting software is not natively supported by Moss, you can use the API to build a custom data sync.

What you can build

Export expenses to your ERP — Retrieve approved expenses from Moss and transform them into journal entries in your ERP. Each expense includes the expense account, tax rate, dimensions, and supplier required for a complete posting.

Import master data into Moss — Push supplier lists and dimension items from your ERP into Moss to keep expense coding consistent with your accounting system.

Two-way supplier sync — Maintain supplier data across both systems. When a vendor is created or updated in either Moss or your ERP, propagate the change to the other.

Key endpoints

Reading from Moss:

Endpoint	Description
GET /v1/expenses	Expenses with full accounting detail for creating journal entries
GET /v1/expense-accounts	Ledger account mappings
GET /v1/tax-rates	Tax and VAT rates for correct tax treatment
GET /v1/suppliers	Supplier data including addresses and payment terms
POST /v1/files/search-query	Search for files (receipts, invoices) attached to expenses
GET /v1/files/{fileId}/content	Download file content
GET /v1/dimension-items	Dimension items mappings in Moss (cost centre, project, etc.)

Writing to Moss:

Endpoint	Description
POST /v1/suppliers	Create a new supplier
PATCH /v1/suppliers/{id}	Update an existing supplier
POST /v1/dimensions	Create a new dimension
POST /v1/dimension-items	Create a new dimension item (cost centre, project, etc.)

Important limitation: Retrieving expense data via the API does not update the expense's export status in Moss. Moss's native accounting integrations (DATEV, Xero, etc.) mark expenses as "exported" when synced — the API does not. There is currently no option to set the export status via API.

Your integration will work for data synchronisation, but you will need to manage export tracking separately (e.g., by updating the export status manually in the Moss UI).

---

Document Retrieval and Archiving

Retrieve receipts, invoices, and other documents attached to expenses for archiving, compliance, or automated processing.

What you can build

Document archiving — Pull receipts and invoices from Moss into a document management system (e.g., SharePoint, Docuware, ELO) with full metadata linking each document to its source transaction.

Audit preparation — Programmatically retrieve document samples for external auditors, replacing manual collection.

AI document analysis — Feed invoice PDFs to an LLM for data extraction, compliance validation, or duplicate detection.

Key endpoints

Endpoint	Description
POST /v1/files/search-query	Search for files attached to expenses
GET /v1/files/{fileId}/content	Download file content (PDF, image)
GET /v1/expenses	Expense data including file references at each line item

Example: archiving receipts

1. Call GET /v1/expenses to retrieve expenses for a given period.
2. For each expense, traverse the line items to collect file IDs (see Expense Files).
3. Call POST /v1/files/search-query and GET /v1/files/{fileId}/content to retrieve each document.
4. Store the document in your archive with expense metadata (supplier, amount, date, expense account) as index fields.

---

Quick Recipes

Common smaller automations built with the API.

Auto-create suppliers

Use POST /v1/suppliers to push new vendors from your accounting or procurement system into Moss before invoices arrive. Include address, payment terms, and tax information so that expenses are correctly attributed from the start.

Keep dimension items in sync

Use POST /v1/dimension-items to create new entries when cost centres, projects, or clients are added in your source system. Use PATCH /v1/dimension-items/{id} to rename or deactivate items that are no longer current.