API Docs / Schemas / MtdForeignPropertiesDto

MtdForeignPropertiesDto

The foreign properties HMRC hold registered against one foreign property income source for a
tax year, and the fact that decides whether the register applies at all.

A foreign property income source holds several lets, and HMRC changed how a let is named
between two adjacent tax years: by country code up to 2025-26, by a registered property id from
2026-27. The register is where that id comes from, so for 2026-27 onwards a property must exist
before anything can be filed against it, and for 2025-26 there is no register at all.

SodiumHQ.DTOs.MtdSubmissions.MtdForeignPropertiesDto.IsKeyedByProperty is on the response rather than re-derived by every consumer:
the boundary is a fact about the tax year and getting it wrong does not fail loudly — HMRC
answer that a field is malformed, not that it belongs to another year.

Properties

Name Type Description
clientCodestring

The Sodium client the income source belongs to, stamped by the API on the way out.

The Sodium client the income source belongs to, stamped by the API on the way out.

businessIdstring

HMRC's identifier for the foreign property income source.

HMRC's identifier for the foreign property income source.

taxYearstring

The tax year, in HMRC's format, e.g. 2026-27.

The tax year, in HMRC's format, e.g. 2026-27.

isKeyedByPropertyboolean

Whether this tax year identifies a let by its registered property rather than by country.
False for 2025-26 and earlier, where SodiumHQ.DTOs.MtdSubmissions.MtdForeignPropertiesDto.Properties is always empty because HMRC
keep no register — not because the client has no lets.

Whether this tax year identifies a let by its registered property rather than by country.
False for 2025-26 and earlier, where SodiumHQ.DTOs.MtdSubmissions.MtdForeignPropertiesDto.Properties is always empty because HMRC
keep no register — not because the client has no lets.

propertiesarray of MtdForeignPropertyDto

The properties HMRC hold for the year. Empty is an answer — a source with no properties
registered yet — and for a year keyed by country it is the only possible answer.

The properties HMRC hold for the year. Empty is an answer — a source with no properties
registered yet — and for a year keyed by country it is the only possible answer.

JSON Example

{
  "clientCode": "string",
  "businessId": "string",
  "taxYear": "string",
  "isKeyedByProperty": false,
  "properties": [
    {
      "propertyId": "...",
      "propertyName": "...",
      "countryCode": "...",
      "endDate": "...",
      "endReason": "..."
    }
  ]
}

Used By Operations