Skip to main content
All Docs
FeaturesMaking Tax DigitalUpdated April 1, 2026

AgentOS Integration

AgentOS Integration

The AgentOS People Portal integration imports property transactions, tenancy records, and property details directly into the platform and maps them to HMRC-compliant income and expense categories for quarterly MTD ITSA submissions.

Transaction Classification

When transactions are imported from AgentOS, each one is assigned a transactionType using the classifyTransactionType() function. This type determines how the transaction is counted in quarterly tax summaries.

How Classification Works

AgentOS returns the NominalCode field as numeric GL codes (e.g. "4000", "7000"). Because numeric codes do not contain keywords, the classifier uses a two-pass approach:

  1. Primary pass — attempt to match the NominalCode value against known keywords (rent, fee, maintenance, etc.).
  2. Fallback pass — if no keyword match is found, classify using the human-readable Description field (e.g. "Rent Payment", "Management Fee").

This ensures transactions are always given the most accurate possible type, even when AgentOS provides only numeric codes in the primary field.

Example:

NominalCodeDescriptionClassified as
"rent"—rent
"4000""Rent Payment"rent
"4000""Management Fee"fee
undefined"Maintenance Work"maintenance

Classification Priority in Promotion

When promoted transactions are categorised for HMRC, the priority order is:

  1. transactionType membership — if the type is in EXPENSE_TYPES (fees, maintenance, deposits, etc.), it is classified as an expense regardless of amount sign.
  2. Amount sign — positive amounts are treated as income, negative as expenses, for any type not explicitly in EXPENSE_TYPES.

Security deposits ("deposit" type) are classified as expenses/liabilities, not taxable income, in line with HMRC guidance.

Sync Behaviour

Bulk Import

A full historical import can be triggered manually. All transactions are upserted — if a transaction already exists, its transactionType, description, amount, currency, and related fields are updated from the AgentOS source.

Incremental Sync

A daily incremental sync runs at 03:00 UTC and can also be triggered manually per organisation. It fetches transactions from the last 48 hours (or since the last successful sync, with a 1-hour buffer).

On each sync, transactionType is re-evaluated using the updated classification logic. Transactions previously stored as "other" due to numeric NominalCode codes will be automatically re-classified on the next sync run.

Impact on User Categorisation

Sync operations update transactionType (the system classification) but never overwrite hmrcCategory (the user-assigned HMRC category). Manual categorisation decisions are always preserved.

Quarterly Summaries

Quarterly tax summary totals are derived from promoted transactions. With correct transactionType values in place:

  • Rent and other income flows correctly into the income total.
  • Fees, maintenance, and deposits flow correctly into the expenses total.
  • The income/expense split displayed in the quarterly summary reflects the actual AgentOS data.

If income was previously showing as zero or lower than expected, running a manual incremental sync after updating to v1.0.476 will re-classify existing transactions and correct the summary totals.

Setup Requirements

  • An active AgentOS People Portal account with API access enabled.
  • At least one landlord link configured in the platform with sync enabled.
  • The platform connected to AgentOS via OAuth (Settings → Integrations → AgentOS).