This version is in beta - expect some breaking changes.

Property Business (MTD) API

Dates and amounts
Date Amount
Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

This API allows developers to:

  • list, retrieve, create or amend an individual’s UK Property Income & Expenses Period Summaries
  • retrieve, create, amend or delete an individual’s UK Property Annual Submissions
  • list, retrieve, create or amend an individual’s Foreign Property Income & Expenses Period Summaries
  • retrieve, create, amend or delete an individual’s Foreign Property Annual Submissions
  • retrieve, create, amend or delete an individual’s Historic FHL and Non-FHL UK Property Business Annual Submissions
  • list, retrieve, create or amend an individual’s Historic FHL and Non-FHL UK Property Business Income & Expenses Period Summaries

The “historic” endpoints are for data relating to tax years from 2017-18 to 2021-22. For later years, use the standard endpoints.

For information on how to connect to this API see the Income Tax MTD end-to-end service guide.

Send fraud prevention data

HMRC monitors transactions to help protect your customers' confidential data from criminals and fraudsters.

Warning You are required by law to submit header data for this API. This includes all associated APIs and endpoints.

Check the data you need to send. You can also use the Test API during initial development and as part of your quality assurance checks.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Single errors will be returned in the following format:
{     "code": "FORMAT_FIELD_NAME",     "message": "The provided FieldName is invalid" }

Where possible, multiple errors will be returned with INVALID_REQUEST in the following format:
{     "code": "INVALID_REQUEST",     "message": "Invalid request",     "errors": [         {      "code": "RULE_FIELD_NAME",      "message": "The provided FieldName is not allowed"         },         {      "code": "FORMAT_FIELD_NAME",      "message": "The provided FieldName is invalid"         }     ] }

Where it is possible for the same error to be returned multiple times, message will describe the expected format and paths will show the fields which are invalid.

Where arrays are submitted a number indicates the object in the array sequence, for example, /arrayName/1/fieldName.

An example with single error:
{     "code": "FORMAT_STRING_NAME",     "message": "The provided field is not valid",     "paths": [ "/arrayName/0/fieldName" ] }

An example with multiple errors:
{     "code": "INVALID_REQUEST",     "message": "Invalid request",     "errors": [      {      "code": "FORMAT_VALUE",      "message": "The value should be between 0 and 99999999999.99",      "paths": [ "/objectName/fieldName1", "/arrayName/0/fieldName2" ]      },      {      "code": "FORMAT_STRING_NAME",      "message": "The provided field is not valid",      "paths": [ "/arrayName/0/fieldName3", "/arrayName/1/fieldName3" ]      }     ] }

Changelog

You can find the changelog in the income-tax-mtd-changelog GitHub wiki.

Support

Testing

You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.

It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.

If you have a specific testing need that is not supported in the sandbox, contact our support team.

Some APIs may be marked [test only]. This means that they are not available for use in production and may change.

Skip to main content

Endpoints

UK Property Business Annual Submission

Resources relating to an individual's UK Property Business Annual Submission

UK Property Business Annual Submission resources

/individuals/business/property/uk/{nino}/{businessId}/annual/{taxYear}

Retrieve a UK Property Business Annual Submission
GET

This endpoint allows a developer to retrieve adjustments and allowances for a UK property business. For either or both of Furnished Holiday Letting (FHL) or other UK property submissions. A National Insurance number, business ID and tax year are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer.

Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies. For example: 2022-23. The start year and end year must not span two tax years. The minimum tax year is 2022-23. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2022-23

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

All Other Allowances Response

{
  "submittedOn":"2020-06-17T10:59:47.544Z",
  "ukFhlProperty":{
    "adjustments":{
      "privateUseAdjustment":454.45,
      "balancingCharge":231.45,
      "periodOfGraceAdjustment":true,
      "businessPremisesRenovationAllowanceBalancingCharges":567.67,
      "nonResidentLandlord":true,
      "rentARoom":{
        "jointlyLet":true
      }
    },
    "allowances":{
      "annualInvestmentAllowance":123.45,
      "businessPremisesRenovationAllowance":345.56,
      "otherCapitalAllowance":345.34,
      "electricChargePointAllowance":453.34,
      "zeroEmissionsCarAllowance":123.12
    }
  },
  "ukNonFhlProperty":{
    "adjustments":{
      "balancingCharge":565.34,
      "privateUseAdjustment":533.54,
      "businessPremisesRenovationAllowanceBalancingCharges":563.34,
      "nonResidentLandlord":true,
      "rentARoom":{
        "jointlyLet":true
      }
    },
    "allowances":{
      "annualInvestmentAllowance":678.45,
      "zeroEmissionsGoodsVehicleAllowance":456.34,
      "businessPremisesRenovationAllowance":573.45,
      "otherCapitalAllowance":452.34,
      "costOfReplacingDomesticGoods":567.34,
      "electricChargePointAllowance":454.34,
      "structuredBuildingAllowance":[
        {
          "amount":234.34,
          "firstYear":{
            "qualifyingDate":"2020-03-29",
            "qualifyingAmountExpenditure":3434.45
          },
          "building":{
            "name":"Plaza",
            "number":"1",
            "postcode":"TF3 4EH"
          }
        }
      ],
      "enhancedStructuredBuildingAllowance":[
        {
          "amount":234.45,
          "firstYear":{
            "qualifyingDate":"2020-05-29",
            "qualifyingAmountExpenditure":453.34
          },
          "building":{
            "name":"Plaza 2",
            "number":"2",
            "postcode":"TF3 4ER"
          }
        }
      ],
      "zeroEmissionsCarAllowance":454.34
    }
  },
  "links": [
    {
      "href": "/individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23",
      "method": "PUT",
      "rel": "amend-uk-property-annual-submission"
    },
    {
      "href": "/individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/TC663795B/XAIS12345678910/annual/2022-23",
      "method": "DELETE",
      "rel": "delete-property-annual-submission"
    }
  ]
}

Property Allowance Response

{
  "submittedOn":"2020-06-17T10:59:47.544Z",
  "ukFhlProperty":{
    "adjustments":{
      "balancingCharge":231.45,
      "periodOfGraceAdjustment":true,
      "businessPremisesRenovationAllowanceBalancingCharges":567.67,
      "nonResidentLandlord":true,
      "rentARoom":{
        "jointlyLet":true
      }
    },
    "allowances":{
      "propertyIncomeAllowance":453.45
    }
  },
  "ukNonFhlProperty":{
    "adjustments":{
      "balancingCharge":565.34,
      "businessPremisesRenovationAllowanceBalancingCharges":563.34,
      "nonResidentLandlord":true,
      "rentARoom":{
        "jointlyLet":true
      }
    },
    "allowances":{
      "propertyIncomeAllowance":342.34
    }
  },
  "links": [
    {
      "href": "/individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23",
      "method": "PUT",
      "rel": "amend-uk-property-annual-submission"
    },
    {
      "href": "/individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/TC663795B/XAIS12345678910/annual/2022-23",
      "method": "DELETE",
      "rel": "delete-property-annual-submission"
    }
  ]
}

Response table
Name Description
submittedOn
string
required

The date the UK property was submitted, in the format `YYYY-MM-DDThh:mm:ss.SSSZ`

For example: 2020-07-07T10:59:47.544Z

ukFhlProperty
object
optional

Object holding the adjustments and allowances of the user's Furnished Holiday Letting (FHL) in the United Kingdom.

adjustments
object
optional

Object holding UK FHL Property Adjustments.

privateUseAdjustment
number
optional

Any adjustments that are not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

balancingCharge
number
optional

If an item for which capital allowance was claimed has been sold, given away or is no longer in use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

periodOfGraceAdjustment
boolean
required

A boolean to identify a property which didn't qualify for FHL this year, but qualified the previous year. The value must be true or false.

For example: true

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: true

allowances
object
optional

Object holding other and property allowances details.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

The allowance amount for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 100.25

electricChargePointAllowance
number
optional

The expenditure incurred on electric charge-point equipment. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionsCarAllowance
number
optional

The amount of zero emissions car allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

ukNonFhlProperty
object
optional

Object holding allowances and adjustments for UK property business - excluding Furnished Holiday Lettings (FHL) for the period.

adjustments
object
optional

Object holding UK Non FHL Property annual adjustments.

balancingCharge
number
optional

If an item for which capital allowance was claimed has been sold, given away or is no longer in use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

privateUseAdjustment
number
optional

Any adjustments that are not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding Non UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: true

allowances
object
optional

Object holding UK Non FHL Property Allowances.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionsGoodsVehicleAllowance
number
optional

The amount of zero emissions goods vehicle allowance for goods vehicles purchased for business use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

Allowance for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfReplacingDomesticGoods
number
optional

Cost of Replacing Domestic Items - formerly Wear and Tear allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 100.25

electricChargePointAllowance
number
optional

The expenditure incurred on electric charge-point equipment. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

structuredBuildingAllowance
array
optional

Details about structured building allowance.

amount
number
required

The amount of structured building allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

firstYear
object
optional

Object holding UK Non FHL structured building allowance details.

qualifyingDate
string
required

The date qualified for structured building allowance. Must conform to the format YYYY-MM-DD.

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

building
object
required

Object holding UK Non FHL structured building details. Postcode is mandatory and minimum one of name and number field must be supplied.

name
string
optional

The name of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: Green Oak’s

number
string
optional

The number of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: 16

postcode
string
required

The postcode for the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: GF4 9JH

enhancedStructuredBuildingAllowance
array
optional

Details about enhanced structured building allowance.

amount
number
required

The amount of enhanced structured building allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

firstYear
object
optional

Object holding UK Non FHL enhanced structured building allowance details.

qualifyingDate
string
required

The date qualified for enhanced structured building allowance. Must conform to the format YYYY-MM-DD.

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

building
object
required

Object holding UK Non FHL enhanced structured building details. Postcode is mandatory and minimum one of name and number field must be supplied.

name
string
optional

The name of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: Green Oak’s

number
string
optional

The number of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: 16

postcode
string
required

The postcode for the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: GF4 9JH

zeroEmissionsCarAllowance
number
optional

The amount of zero emissions car allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint.

For example: /individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
DELETE
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

self
amend-uk-property-annual-submission
delete-property-annual-submission

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied Business ID field is not valid.

400 (Bad Request)

FORMAT_BUSINESS_ID

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The supplied Business ID does not represent a UK property business.

400 (Bad Request)

RULE_TYPE_OF_BUSINESS_INCORRECT

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates the scenario where no data is found.

UK_PROPERTY

Simulates the scenario with FHL and Non-FHL properties.

UK_FHL_ALL_OTHER_ALLOWANCES

Simulates the scenario of a FHL property with all other allowances.

UK_FHL_PROPERTY_ALLOWANCE

Simulates success response with UK Non-FHL property.

UK_NON_FHL_ALL_OTHER_ALLOWANCES

Simulates the scenario of a Non-FHL property with all other allowances.

UK_NON_FHL_PROPERTY_ALLOWANCE

Simulates the scenario of a Non-FHL property with property allowance.

FOREIGN_PROPERTY

Simulates the scenario where the type of business is incorrect.


Close Section
/individuals/business/property/uk/{nino}/{businessId}/annual/{taxYear}

Create and Amend a UK Property Business Annual Submission
PUT

This endpoint allows a developer to re-submit adjustments and allowances for a UK property business. This submission is for either or both of Furnished Holiday Letting (FHL) and Non FHL UK property submissions. A National Insurance number, business ID and tax year are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer.

Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies. For example: 2022-23. The start year and end year must not span two tax years. The minimum tax year is 2022-23. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2022-23

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Property Allowance request

{
  "ukFhlProperty": {
    "allowances": {
      "propertyIncomeAllowance": 123.45
    },
    "adjustments": {
      "balancingCharge": 231.45,
      "periodOfGraceAdjustment": true,
      "businessPremisesRenovationAllowanceBalancingCharges": 567.67,
      "nonResidentLandlord": true,
      "rentARoom": {
        "jointlyLet": true
      }
    }
  },
  "ukNonFhlProperty": {
    "allowances": {
      "propertyIncomeAllowance": 678.45
    },
    "adjustments": {
      "balancingCharge": 565.34,
      "businessPremisesRenovationAllowanceBalancingCharges": 563.34,
      "nonResidentLandlord": true,
      "rentARoom": {
        "jointlyLet": true
      }
    }
  }
}

Scenario: All Other Allowances request

{
  "ukFhlProperty": {
    "allowances": {
      "annualInvestmentAllowance": 123.45,
      "businessPremisesRenovationAllowance": 345.56,
      "otherCapitalAllowance": 345.34,
      "electricChargePointAllowance": 453.34,
      "zeroEmissionsCarAllowance": 123.12
    },
    "adjustments": {
      "privateUseAdjustment": 454.45,
      "balancingCharge": 231.45,
      "periodOfGraceAdjustment": true,
      "businessPremisesRenovationAllowanceBalancingCharges": 567.67,
      "nonResidentLandlord": true,
      "rentARoom": {
        "jointlyLet": true
      }
    }
  },
  "ukNonFhlProperty": {
    "allowances": {
      "annualInvestmentAllowance": 678.45,
      "zeroEmissionsGoodsVehicleAllowance": 456.34,
      "businessPremisesRenovationAllowance": 573.45,
      "otherCapitalAllowance": 452.34,
      "costOfReplacingDomesticGoods": 567.34,
      "electricChargePointAllowance": 454.34,
      "structuredBuildingAllowance": [
        {
          "amount": 234.34,
          "firstYear": {
            "qualifyingDate": "2020-03-29",
            "qualifyingAmountExpenditure": 3434.45
          },
          "building": {
            "name": "Red Oaks",
            "number": "1",
            "postcode": "SW1A 2AA"
          }
        }
      ],
      "enhancedStructuredBuildingAllowance": [
        {
          "amount": 234.45,
          "firstYear": {
            "qualifyingDate": "2020-05-29",
            "qualifyingAmountExpenditure": 453.34
          },
          "building": {
            "name": "Green Oaks",
            "number": "2",
            "postcode": "SW1A 2AB"
          }
        }
      ],
      "zeroEmissionsCarAllowance": 454.34
    },
    "adjustments": {
      "balancingCharge": 565.34,
      "privateUseAdjustment": 533.54,
      "businessPremisesRenovationAllowanceBalancingCharges": 563.34,
      "nonResidentLandlord": true,
      "rentARoom": {
        "jointlyLet": true
      }
    }
  }
}

Request table
Name Description
ukFhlProperty
object
optional

Object holding the adjustments and allowances of the user's Furnished Holiday Letting (FHL) in the United Kingdom.

adjustments
object
optional

Object holding UK FHL Property Adjustments.

privateUseAdjustment
number
optional

Any adjustments that are not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

balancingCharge
number
optional

If an item for which capital allowance was claimed has been sold, given away or is no longer in use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

periodOfGraceAdjustment
boolean
required

A boolean to identify a property which didn't qualify for FHL this year, but qualified the previous year. The value must be true or false.

For example: false

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: false

allowances
object
optional

Object holding other and property allowances details.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

The allowance amount for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

electricChargePointAllowance
number
optional

The expenditure incurred on electric charge-point equipment. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionsCarAllowance
number
optional

The amount of zero emissions car allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 200.25

ukNonFhlProperty
object
optional

Object holding allowances and adjustments for UK property business - excluding Furnished Holiday Lettings (FHL) for the period.

adjustments
object
optional

Object holding UK Non FHL Property annual adjustments.

balancingCharge
number
optional

If an item for which capital allowance was claimed has been sold, given away or is no longer in use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

privateUseAdjustment
number
optional

Any adjustments that are not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding Non UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: false

allowances
object
optional

Object holding UK Non FHL Property Allowances.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionsGoodsVehicleAllowance
number
optional

The amount of zero emissions goods vehicle allowance for goods vehicles purchased for business use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

Allowance for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfReplacingDomesticGoods
number
optional

Cost of Replacing Domestic Items - formerly Wear and Tear allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

electricChargePointAllowance
number
optional

The expenditure incurred on electric charge-point equipment. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionsCarAllowance
number
optional

The amount of zero emissions car allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 100.25

structuredBuildingAllowance
array
optional

Details about structured building allowance.

amount
number
required

The amount of structured building allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

firstYear
object
optional

Object holding UK Non FHL structured building allowance details.

qualifyingDate
string
required

The date qualified for structured building allowance. Must conform to the format YYYY-MM-DD.

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

building
object
required

Object holding UK Non FHL structured building details. Postcode is mandatory and minimum one of name and number field must be supplied.

name
string
optional

The name of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: Green Oak’s

number
string
optional

The number of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: 16

postcode
string
required

The postcode for the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: SW1A 2AA

enhancedStructuredBuildingAllowance
array
optional

Details about enhanced structured building allowance.

amount
number
required

The amount of enhanced structured building allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

firstYear
object
optional

Object holding UK Non FHL enhanced structured building allowance details.

qualifyingDate
string
required

The date qualified for enhanced structured building allowance. Must conform to the format YYYY-MM-DD.

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

building
object
required

Object holding UK Non FHL enhanced structured building details. Postcode is mandatory and minimum one of name and number field must be supplied.

name
string
optional

The name of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: Green Oak’s

number
string
optional

The number of the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: 16

postcode
string
required

The postcode for the building.

Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$

For example: SW1A 2AA

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Example response

{
  "links":[
    {
      "href":"/individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23",
      "method":"PUT",
      "rel":"amend-uk-property-annual-submission"
    },
    {
      "href":"/individuals/business/property/TC663795B/XAIS12345678910/annual/2022-23",
      "method":"DELETE",
      "rel":"delete-property-annual-submission"
    }
  ]
}

Response table
Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint.

For example: /individuals/business/property/uk/TC663795B/XAIS12345678910/annual/2022-23

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
DELETE
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

amend-uk-property-annual-submission
delete-property-annual-submission
self

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied Business ID field is not valid.

400 (Bad Request)

FORMAT_BUSINESS_ID

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of one or more monetary fields is not valid.

400 (Bad Request)

FORMAT_VALUE

The supplied date format is not valid.

400 (Bad Request)

FORMAT_DATE

One or more strings have been added with the incorrect format.

400 (Bad Request)

FORMAT_STRING

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

Both allowances and property income allowance must not be present at the same time.

400 (Bad Request)

RULE_BOTH_ALLOWANCES_SUPPLIED

One of building name or number must be supplied.

400 (Bad Request)

RULE_BUILDING_NAME_NUMBER

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The supplied Business ID does not represent a UK property business.

400 (Bad Request)

RULE_TYPE_OF_BUSINESS_INCORRECT

The propertyIncomeAllowance cannot be submitted if privateUseAdjustment is supplied.

400 (Bad Request)

RULE_PROPERTY_INCOME_ALLOWANCE

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.

TYPE_OF_BUSINESS_INCORRECT

Simulates the scenario where a businessId for something other than a UK property is supplied.


Close Section

UK Property Income & Expenses Period Summary

Resources relating to an individual's UK Property Income & Expenses Period Summary

UK Property Income & Expenses Period Summary resources

/individuals/business/property/uk/{nino}/{businessId}/period/{taxYear}

Create a UK Property Income & Expenses Period Summary
POST

This endpoint allows a developer to submit the income and expenses for a UK property business. This submission is for either or both of Furnished Holiday Letting (FHL) and Non FHL UK property submissions. A National Insurance number, business ID and tax year are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer.

Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies. For example, 2022-23. The start year and end year must not span two tax years. The minimum tax year is 2022-23. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2022-23

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Full Expenses request

{
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "ukFhlProperty":{
    "income": {
      "periodAmount": 5000.99,
      "taxDeducted": 3123.21,
      "rentARoom": {
        "rentsReceived": 532.12
      }
    },
    "expenses": {
      "premisesRunningCosts": 3123.21,
      "repairsAndMaintenance": 928.42,
      "financialCosts": 842.99,
      "professionalFees": 8831.12,
      "costOfServices": 484.12,
      "other": 99282,
      "travelCosts": 974.47,
      "rentARoom": {
        "amountClaimed": 8842.43
      }
    }
  },
  "ukNonFhlProperty": {
    "income": {
      "premiumsOfLeaseGrant": 42.12,
      "reversePremiums": 84.31,
      "periodAmount": 9884.93,
      "taxDeducted": 842.99,
      "otherIncome": 31.44,
      "rentARoom": {
        "rentsReceived": 947.66
      }
    },
    "expenses": {
      "premisesRunningCosts": 4141.21,
      "repairsAndMaintenance": 582.21,
      "financialCosts": 829.39,
      "professionalFees": 4992.31,
      "costOfServices": 98.21,
      "other": 29.48,
      "residentialFinancialCost": 2884.99,
      "travelCosts": 48.93,
      "residentialFinancialCostsCarriedForward": 483.91,
      "rentARoom": {
        "amountClaimed": 88.21
      }
    }
  }
}

Scenario: Consolidated Expenses request

{
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "ukFhlProperty":{
    "income": {
      "periodAmount": 5000.99,
      "taxDeducted": 3123.21,
      "rentARoom": {
        "rentsReceived": 532.12
      }
    },
    "expenses": {
      "consolidatedExpenses": 988.18
    }
  },
  "ukNonFhlProperty": {
    "income": {
      "premiumsOfLeaseGrant": 42.12,
      "reversePremiums": 84.31,
      "periodAmount": 9884.93,
      "taxDeducted": 842.99,
      "otherIncome": 31.44,
      "rentARoom": {
        "rentsReceived": 947.66
      }
    },
    "expenses": {
      "consolidatedExpenses": 988.18
    }
  }
}

Request table
Name Description
fromDate
string
required

The first day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD.

For example: 2020-01-01

toDate
string
required

The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD.

For example: 2020-01-31

ukFhlProperty
object
optional

Object holding the income and expenses of the UK property business. (At least one of income or expenses should be present)

income
object
optional

Object holding the income details for the period.

periodAmount
number
optional

Total rents from property, ground rents and rent charges but not rent-a-room. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

The tax deducted from the income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents received for the period.

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period.

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the amount claimed for the period.

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed.The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. You can either submit a consolidatedExpenses value or individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, travelCosts, rentARoom). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

ukNonFhlProperty
object
optional

Object holding the income and expenses of the UK property business - excluding Furnished Holiday Lettings (FHL) for the period. (At least one of income or expenses should be present)

income
object
optional

Object holding the income details for the period.

premiumsOfLeaseGrant
number
optional

Premiums received for the grant of a lease and other lump sums to possess a property. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

reversePremiums
number
optional

Amount paid by a landlord or outgoing tenant to induce a new tenant to enter into a leasehold agreement. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

periodAmount
number
optional

Total rents from property (but not ground rents, rent charges and rent-a-room rental income). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

Tax already deducted from the rental income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherIncome
number
optional

Total amount of rent and any income for services provided to tenants. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents received for the period.

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period.

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

residentialFinancialCost
number
optional

The residential financial cost deductible from rental income (tax relief). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

residentialFinancialCostsCarriedForward
number
optional

Amount of residential financial costs carried forward. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the amount claimed for the period.

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. You can either submit a consolidatedExpenses value or individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, residentialFinancialCost, travelCosts, residentialFinancialCostsCarriedForward, rentARoom). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

Responses

HTTP status 201 (Created)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Default Example

{
  "submissionId": "4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
  "links": [
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method":"GET",
      "rel":"self"
    }
  ]
}

Response table
Name Description
submissionId
string
required

An identifier for the income and expenses period summary.

Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint

For example: /individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c

rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

For example: self

method
string
required

The HTTP method type for the endpoint

For example: GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of the supplied Business ID field is not valid.

400 (Bad Request)

FORMAT_BUSINESS_ID

The format of the supplied From date field is not valid.

400 (Bad Request)

FORMAT_FROM_DATE

The format of the supplied To date field is not valid.

400 (Bad Request)

FORMAT_TO_DATE

The format of one or more monetary fields is not valid.

400 (Bad Request)

FORMAT_VALUE

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Both Expenses and Consolidated Expenses must not be present at the same time.

400 (Bad Request)

RULE_BOTH_EXPENSES_SUPPLIED

The supplied Business ID does not represent a UK property business.

400 (Bad Request)

RULE_TYPE_OF_BUSINESS_INCORRECT

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

The To date is earlier than the From date.

400 (Bad Request)

RULE_TO_DATE_BEFORE_FROM_DATE

Period summary overlaps with any of the existing period summaries.

400 (Bad Request)

RULE_OVERLAPPING_PERIOD

Period summary is not within the accounting period.

400 (Bad Request)

RULE_MISALIGNED_PERIOD

Period summaries are not contiguous.

400 (Bad Request)

RULE_NOT_CONTIGUOUS_PERIOD

A summary has already been submitted for the period specified.

400 (Bad Request)

RULE_DUPLICATE_SUBMISSION

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success response.

NOT_FOUND

Simulates the scenario where the given resource could not be found.

OVERLAPPING

Simulates the scenario where the period summary overlaps with an existing period summary.

MISALIGNED

Simulates the scenario where the period summary isn't within the accounting period.

NOT_CONTIGUOUS

Simulates the scenario where the period summaries are not contiguous.

DUPLICATE_SUBMISSION

Simulates the scenario where a summary has already been submitted for the specified period.

TYPE_OF_BUSINESS_INCORRECT

Simulates the scenario where the supplied Business ID does not represent a foreign property business.


Close Section
/individuals/business/property/uk/{nino}/{businessId}/period/{taxYear}/{submissionId}

Retrieve a UK Property Income & Expenses Period Summary
GET

This endpoint allows a developer to retrieve the income and expenses for a UK property business, that occurred between tax year. A National Insurance number, business ID, tax year and submission ID are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer.

Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies. For example, 2022-23. The start year and end year must not span two tax years. The minimum tax year is 2022-23. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2022-23

submissionId
string
required

An identifier for the income and expenditure period summary.

Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Full Expenditure response

{
  "submittedOn": "2021-10-21T10:59:47.544Z",
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "periodCreationDate": "2023-07-06T14:15:22.000Z",
  "ukFhlProperty": {
    "income": {
      "periodAmount": 5000.99,
      "taxDeducted": 3123.21,
      "rentARoom": {
        "rentsReceived": 532.12
      }
    },
    "expenses": {
      "premisesRunningCosts": 4141.21,
      "repairsAndMaintenance": 582.21,
      "financialCosts": 829.39,
      "professionalFees": 4992.31,
      "costOfServices": 98.21,
      "other": 29.48,
      "travelCosts": 48.93,
      "rentARoom": {
        "amountClaimed": 88.21
      }
    }
  },
  "ukNonFhlProperty": {
    "income": {
      "premiumsOfLeaseGrant": 42.12,
      "reversePremiums": 84.31,
      "periodAmount": 9884.93,
      "taxDeducted": 842.99,
      "otherIncome": 31.44,
      "rentARoom": {
        "rentsReceived": 947.66
      }
    },
    "expenses": {
      "premisesRunningCosts": 4141.21,
      "repairsAndMaintenance": 582.21,
      "financialCosts": 829.39,
      "professionalFees": 4992.31,
      "costOfServices": 98.21,
      "other": 29.48,
      "residentialFinancialCost": 2884.99,
      "travelCosts": 48.93,
      "residentialFinancialCostsCarriedForward": 483.91,
      "rentARoom": {
        "amountClaimed": 88.21
      }
    }
  },
  "links": [
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "PUT",
      "rel": "amend-uk-property-period-summary"
    },
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "GET",
      "rel": "self"
    },
    {
      "href":"/individuals/business/property/AA999999A/XAIS12345678910/period/2022-23",
      "method": "GET",
      "rel": "list-property-period-summaries"
    }
  ]
}

Consolidated Expenditure response

{
  "submittedOn": "2021-10-21T10:59:47.544Z",
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "ukFhlProperty": {
    "income": {
      "periodAmount": 5000.99,
      "taxDeducted": 3123.21,
      "rentARoom": {
        "rentsReceived": 532.12
      }
    },
    "expenses": {
      "consolidatedExpenses": 988.18
    }
  },
  "ukNonFhlProperty": {
    "income": {
      "premiumsOfLeaseGrant": 42.12,
      "reversePremiums": 84.31,
      "periodAmount": 9884.93,
      "taxDeducted": 842.99,
      "otherIncome": 31.44,
      "rentARoom": {
        "rentsReceived": 947.66
      }
    },
    "expenses": {
      "consolidatedExpenses": 988.18
    }
  },
  "links": [
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "PUT",
      "rel": "amend-uk-property-period-summary"
    },
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "GET",
      "rel": "self"
    },
    {
      "href":"/individuals/business/property/AA999999A/XAIS12345678910/period/2022-23",
      "method": "GET",
      "rel": "list-property-period-summaries"
    }
  ]
}

Response table
Name Description
submittedOn
string
required

The date the UK property were submitted, in the format `YYYY-MM-DDThh:mm:ss.SSSZ`

For example: 2020-07-07T10:59:47.544Z

fromDate
string
required

The first day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD

For example: 2020-01-01

toDate
string
required

The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD

For example: 2020-01-31

periodCreationDate
string
optional

[Test only] The date and time when the income and expenses period was created. This is only available from the tax year 2023-24.

For example: 2023-07-06T14:15:22.000Z

ukFhlProperty
object
optional

Object holding the income and expenses of the user's Furnished Holiday Letting (FHL) in the United Kingdom for the period. (At least one of income or expenses should be present).

income
object
optional

Object holding the income details for the period.

periodAmount
number
optional

Total rents from property, ground rents and rent charges but not rent-a-room. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

The tax deducted from income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents received for the period.

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period.

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents claimed for the period.

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. If consolidatedExpenses is returned, values for individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, travelCosts, rentARoom) are not returned. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

ukNonFhlProperty
object
optional

Object holding the income and expenses of the UK property business - excluding Furnished Holiday Lettings (FHL) for the period. (At least one of income or expenses should be present).

income
object
optional

Object holding the income details for the period.

premiumsOfLeaseGrant
number
optional

Premiums received for the grant of a lease and other lump sums to possess a property. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

reversePremiums
number
optional

Amount paid by a landlord or outgoing tenant to induce a new tenant to enter into a leasehold agreement. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

periodAmount
number
optional

Total rents from property (but not ground rents, rent charges and rent-a-room rental income). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

Tax already deducted from the rental income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherIncome
number
optional

Total amount of rent and any income for services provided to tenants. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents received for the period.

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period.

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionGoodsVehicleAllowance
number
optional

The amount of zero emission goods vehicle allowance for goods vehicles purchased for business use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

residentialFinancialCost
number
optional

The residential financial cost deductible from rental income (tax relief). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

residentialFinancialCostsCarriedForward
number
optional

Amount of residential financial costs carried forward. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents claimed for the period.

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. You can either submit a consolidatedExpenses value or individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, residentialFinancialCost, travelCosts, residentialFinancialCostsCarriedForward, rentARoom) The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint

For example: /individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c

rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

Limited to the following possible values:

self
list-property-period-summaries
amend-uk-property-period-summary
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
PUT

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of the supplied Business ID field is not valid.

400 (Bad Request)

FORMAT_BUSINESS_ID

The format of the supplied Submission ID field is not valid.

400 (Bad Request)

FORMAT_SUBMISSION_ID

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The supplied Business ID does not represent a UK property business.

400 (Bad Request)

RULE_TYPE_OF_BUSINESS_INCORRECT

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates the scenario where no data is found.

UK_PROPERTY

Simulates the scenario with FHL and Non-FHL properties.

UK_FHL_FULL_EXPENSES

Simulates the scenario of a FHL property with full expenses.

UK_FHL_CONSOLIDATED

Simulates the scenario of a FHL property with consolidated expenses.

UK_NON_FHL_FULL_EXPENSES

Simulates the scenario of a Non-FHL property with full expenses.

UK_NON_FHL_CONSOLIDATED

Simulates the scenario of a Non-FHL property with consolidated expenses.

FOREIGN_PROPERTY

Simulates the scenario where the type of business is incorrect.


Close Section
/individuals/business/property/uk/{nino}/{businessId}/period/{taxYear}/{submissionId}

Amend a UK Property Income & Expenses Period Summary
PUT

This endpoint allows a developer to re-submit the income and expenditure for a UK property business. This submission is for either or both of Furnished Holiday Letting (FHL) and Non FHL UK property submissions. A National Insurance number, business ID, tax year and submission ID are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer.

Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies. For example, 2022-23. The start year and end year must not span two tax years. The minimum tax year is 2022-23. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2022-23

submissionId
string
required

An identifier for the income and expenditure period summary.

Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Full Expenses request

{
  "ukFhlProperty":{
    "income": {
      "periodAmount": 5000.99,
      "taxDeducted": 3123.21,
      "rentARoom": {
        "rentsReceived": 532.12
      }
    },
    "expenses": {
      "premisesRunningCosts": 3123.21,
      "repairsAndMaintenance": 928.42,
      "financialCosts": 842.99,
      "professionalFees": 8831.12,
      "costOfServices": 484.12,
      "other": 99282,
      "travelCosts": 974.47,
      "rentARoom": {
        "amountClaimed": 8842.43
      }
    }
  },
  "ukNonFhlProperty": {
    "income": {
      "premiumsOfLeaseGrant": 42.12,
      "reversePremiums": 84.31,
      "periodAmount": 9884.93,
      "taxDeducted": 842.99,
      "otherIncome": 31.44,
      "rentARoom": {
        "rentsReceived": 947.66
      }
    },
    "expenses": {
      "premisesRunningCosts": 4141.21,
      "repairsAndMaintenance": 582.21,
      "financialCosts": 829.39,
      "professionalFees": 4992.31,
      "costOfServices": 98.21,
      "other": 29.48,
      "residentialFinancialCost": 2884.99,
      "travelCosts": 48.93,
      "residentialFinancialCostsCarriedForward": 483.91,
      "rentARoom": {
        "amountClaimed": 88.21
      }
    }
  }
}

Scenario: Consolidated Expenses request

{
  "ukFhlProperty":{
    "income": {
      "periodAmount": 5000.99,
      "taxDeducted": 3123.21,
      "rentARoom": {
        "rentsReceived": 532.12
      }
    },
    "expenses": {
      "consolidatedExpenses": 988.18
    }
  },
  "ukNonFhlProperty": {
    "income": {
      "premiumsOfLeaseGrant": 42.12,
      "reversePremiums": 84.31,
      "periodAmount": 9884.93,
      "taxDeducted": 842.99,
      "otherIncome": 31.44,
      "rentARoom": {
        "rentsReceived": 947.66
      }
    },
    "expenses": {
      "consolidatedExpenses": 988.18
    }
  }
}

Request table
Name Description
ukFhlProperty
object
optional

Object holding the income and expenditure of the user's Furnished Holiday Letting (FHL) in the United Kingdom for the period. (At least one of income or expenses should be present)

income
object
optional

Object holding the income details for the period.

periodAmount
number
optional

Total rents from property, ground rents and rent charges but not rent-a-room. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

The tax deducted from the income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents received for rooms.

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period.

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the amount claimed for the period.

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed.The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. You can either submit a consolidatedExpenses value or individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, travelCosts, rentARoom). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

ukNonFhlProperty
object
optional

Object holding the income and expenses of the UK property business - excluding Furnished Holiday Lettings (FHL) for the period. (At least one of income or expenses should be present)

income
object
optional

Object holding the income details for the period.

premiumsOfLeaseGrant
number
optional

Premiums received for the grant of a lease and other lump sums to possess a property. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

reversePremiums
number
optional

Amount paid by a landlord or outgoing tenant to induce a new tenant to enter into a leasehold agreement. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

periodAmount
number
optional

Total rents from property (but not ground rents, rent charges and rent-a-room rental income). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

Tax already deducted from the rental income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherIncome
number
optional

Total amount of rent and any income for services provided to tenants. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rents received for rooms.

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period.

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

residentialFinancialCost
number
optional

The residential financial cost deductible from rental income (tax relief). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

residentialFinancialCostsCarriedForward
number
optional

Amount of residential financial costs carried forward. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the rent claimed for rooms.

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. You can either submit a consolidatedExpenses value or individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, residentialFinancialCost, travelCosts, residentialFinancialCostsCarriedForward, rentARoom). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Default Example

{
  "links": [
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method":"PUT",
      "rel":"amend-uk-property-period-summary"
    },
    {
      "href":"/individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23",
      "method":"GET",
      "rel":"list-property-period-summaries"
    }
  ]
}

Response table
Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint

For example: /individuals/business/property/uk/AA999999A/XAIS12345678910/period/2022-23/4557ecb5-fd32-48cc-81f5-e6acd1099f3c

rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

Limited to the following possible values:

self
list-property-period-summaries
amend-uk-property-period-summary
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
PUT

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of the supplied Business ID field is not valid.

400 (Bad Request)

FORMAT_BUSINESS_ID

The format of the supplied Submission ID field is not valid.

400 (Bad Request)

FORMAT_SUBMISSION_ID

The format of one or more monetary fields is not valid.

400 (Bad Request)

FORMAT_VALUE

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Both Expenses and Consolidated Expenses must not be present at the same time.

400 (Bad Request)

RULE_BOTH_EXPENSES_SUPPLIED

The supplied Business ID does not represent a UK property business.

400 (Bad Request)

RULE_TYPE_OF_BUSINESS_INCORRECT

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success response.

NOT_FOUND

Simulates the scenario where no data is found.

TYPE_OF_BUSINESS_INCORRECT

Simulates the scenario where an businessId for something other than a UK property is supplied.


Close Section

Historic FHL UK Property Business Annual Submission

Resources relating to an individual's historic FHL UK Property Business Annual Submission

Historic FHL UK Property Business Annual Submission resources

/individuals/business/property/uk/annual/furnished-holiday-lettings/{nino}/{taxYear}

Retrieve a Historic FHL UK Property Business Annual Submission
GET

This endpoint enables you to retrieve the income from adjustments and allowances for a furnished holiday lettings (FHL) UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and tax year must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Retrieve a UK Property Business Annual Submission endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year to which the data applies. For example: 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18 and the maximum tax year is 2021-22. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2021-22

Request headers

Request headers Table
Name Description
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

{
  "annualAdjustments": {
    "lossBroughtForward": 200.00,
    "balancingCharge": 200.00,
    "privateUseAdjustment": 200.00,
    "periodOfGraceAdjustment": true,
    "businessPremisesRenovationAllowanceBalancingCharges": 200.02,
    "nonResidentLandlord": true,
    "rentARoom": {
      "jointlyLet": true
    }
  },
  "annualAllowances": {
    "annualInvestmentAllowance": 200.00,
    "otherCapitalAllowance": 200.00,
    "businessPremisesRenovationAllowance": 100.02,
    "propertyIncomeAllowance": 10.02
  },
  "links": [
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20",
      "method": "PUT",
      "rel": "create-and-amend-uk-property-historic-fhl-annual-submission"
    },
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20",
      "method": "DELETE",
      "rel": "delete-uk-property-historic-fhl-annual-submission"
    }
  ]
}

Response table
Name Description
annualAdjustments
object
optional

Object containing the details about annual adjustments

lossBroughtForward
number
optional

Loss brought forward from earlier years. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

privateUseAdjustment
number
optional

Private use adjustment on an asset by a sole trader or partner in a partnership, the asset is put in to a single-asset pool and allowances are restricted on the business to private-use ratio. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

balancingCharge
number
optional

Balancing charge on sale or cessation of business use (where you have disposed of assets for more than their tax value). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

periodOfGraceAdjustment
boolean
required

A boolean to identify a property which didn't qualify for FHL this year, but qualified the previous year. The value must be true or false.

For example: false

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: false

annualAllowances
object
optional

An object containing the details about annual allowances.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to the maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

The allowance amount for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.25

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint

For example: /individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20

rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

Limited to the following possible values:

create-and-amend-uk-property-historic-fhl-annual-submission
self
delete-uk-property-historic-fhl-annual-submission
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

PUT
GET
DELETE

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates a success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/property/uk/annual/furnished-holiday-lettings/{nino}/{taxYear}

Create and Amend a Historic FHL UK Property Business Annual Submission
PUT

This endpoint enables you to create and amend the income from adjustments and allowances for a furnished holiday lettings (FHL) UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and tax year must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Create and Amend a UK Property Business Annual Submission endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year to which the data applies. For example: 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18 and the maximum tax year is 2021-22. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2021-22

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Property Allowance request

{
  "annualAdjustments": {
    "lossBroughtForward": 200.00,
    "balancingCharge": 200.00,
    "privateUseAdjustment": 200.00,
    "periodOfGraceAdjustment": true,
    "businessPremisesRenovationAllowanceBalancingCharges": 200.02,
    "nonResidentLandlord": true,
    "rentARoom": {
      "jointlyLet": true
    }
  },
  "annualAllowances": {
    "annualInvestmentAllowance": 200.00,
    "otherCapitalAllowance": 200.00,
    "businessPremisesRenovationAllowance": 100.02,
    "propertyIncomeAllowance": 10.02
  }
}

Request table
Name Description
annualAdjustments
object
optional

Object containing the details about annual adjustments.

lossBroughtForward
number
optional

Loss brought forward from earlier years. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

privateUseAdjustment
number
optional

Private use adjustment on an asset by a sole trader or partner in a partnership, the asset is put in to a single-asset pool and allowances are restricted on the business to private-use ratio. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

balancingCharge
number
optional

Balancing charge on sale or cessation of business use (where you have disposed of assets for more than their tax value). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

periodOfGraceAdjustment
boolean
required

A boolean to identify a property which didn't qualify for FHL this year, but qualified the previous year. The value must be true or false

For example: false

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: false

annualAllowances
object
optional

Object containing the details about annual allowances

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

The allowance amount for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 5000.99

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Example response

{
  "links": [
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20",
      "method": "PUT",
      "rel": "create-and-amend-uk-property-historic-fhl-annual-submission"
    },
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/AA999999A/2019-20",
      "method": "DELETE",
      "rel": "delete-uk-property-historic-fhl-annual-submission"
    }
  ]
}

Response table
Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint.

For example: /individuals/business/property/uk/furnished-holiday-lettings/TC663795B/2019-20

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
DELETE
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

create-and-amend-uk-property-historic-fhl-annual-submission
self
delete-uk-property-historic-fhl-annual-submission

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

One or more values have been added with the incorrect format.

400 (Bad Request)

FORMAT_VALUE

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/property/uk/annual/furnished-holiday-lettings/{nino}/{taxYear}

Delete a Historic FHL UK Property Business Annual Submission
DELETE

This endpoint enables you to delete the income from adjustments and allowances for a furnished holiday lettings (FHL) UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and tax year must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Delete a UK Property Business Annual Submission endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year to which the data applies. For example: 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18 and the maximum tax year is 2021-22. No gaps are allowed, for example, 2022-24 is not valid. (The minimum tax year in Sandbox is 2021-22.)

For example: 2021-22

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

DELETE

Simulates a success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section

Historic non-FHL UK Property Business Annual Submission

Resources relating to an individual's historic non-FHL UK Property Business Annual Submission.

Historic non-FHL UK Property Business Annual Submission resources

/individuals/business/property/uk/annual/non-furnished-holiday-lettings/{nino}/{taxYear}

Retrieve a Historic Non-FHL UK Property Business Annual Submission
GET

This endpoint enables you to retrieve the income from adjustments and allowances for a non furnished holiday lettings (non-FHL) UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and tax year must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Retrieve a UK Property Business Annual Submission endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18 and the maximum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid.

For example: 2021-22

Request headers

Request headers Table
Name Description
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

{
  "annualAdjustments": {
    "lossBroughtForward": 200.00,
    "balancingCharge": 200.00,
    "privateUseAdjustment": 200.00,
    "businessPremisesRenovationAllowanceBalancingCharges": 80.02,
    "nonResidentLandlord": true,
    "rentARoom": {
      "jointlyLet": true
    }
  },
  "annualAllowances": {
    "annualInvestmentAllowance": 200.00,
    "otherCapitalAllowance": 200.00,
    "zeroEmissionGoodsVehicleAllowance": 200.00,
    "businessPremisesRenovationAllowance": 200.00,
    "costOfReplacingDomesticGoods": 200.00,
    "propertyIncomeAllowance": 30.02
  },
  "links": [
    {
      "href": "/individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20",
      "method": "PUT",
      "rel": "create-and-amend-uk-property-historic-non-fhl-annual-submission"
    },
    {
      "href": "/individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20",
      "method": "DELETE",
      "rel": "delete-uk-property-historic-non-fhl-annual-submission"
    }
  ]
}

Response table
Name Description
annualAdjustments
object
optional

Object containing the details about annual adjustments.

lossBroughtForward
number
optional

Loss brought forward from earlier years. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

privateUseAdjustment
number
optional

Private use adjustment on an asset by a sole trader or partner in a partnership, the asset is put in to a single-asset pool and allowances are restricted on the business to private-use ratio. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

balancingCharge
number
optional

Balancing charge on sale or cessation of business use (where you have disposed of assets for more than their tax value). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord.

For example: false

rentARoom
object
optional

Object holding UK FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual.

For example: false

annualAllowances
object
optional

An object containing the details about annual allowances.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) up to the maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionGoodsVehicleAllowance
number
optional

The number of zero-emissions goods vehicle allowance for goods vehicles purchased for business use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

The allowance amount for renovation or conversion of derelict business properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfReplacingDomesticGoods
number
optional

Cost of Replacing Domestic Items - formerly Wear and Tear allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.25

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint

For example: /individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20

rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

Limited to the following possible values:

create-and-amend-uk-property-historic-non-fhl-annual-submission
self
delete-uk-property-historic-non-fhl-annual-submission
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

PUT
GET
DELETE

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates a success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/property/uk/annual/non-furnished-holiday-lettings/{nino}/{taxYear}

Create and Amend a Historic Non-FHL UK Property Business Annual Submission
PUT

This endpoint enables you to create and amend the income from adjustments and allowances for a non-furnished holiday lettings (non-FHL) UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and tax year must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Create and Amend a UK Property Business Annual Submission endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18 and the maximum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid.

For example: 2021-22

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Property Allowance request

{
  "annualAdjustments": {
    "lossBroughtForward": 200.00,
    "balancingCharge": 200.00,
    "privateUseAdjustment": 200.00,
    "businessPremisesRenovationAllowanceBalancingCharges": 80.02,
    "nonResidentLandlord": true,
    "rentARoom": {
      "jointlyLet": true
    }
  },
  "annualAllowances": {
    "annualInvestmentAllowance": 200.00,
    "zeroEmissionGoodsVehicleAllowance": 200.00,
    "businessPremisesRenovationAllowance": 200.00,
    "otherCapitalAllowance": 200.00,
    "costOfReplacingDomesticGoods": 200.00,
    "propertyIncomeAllowance": 30.02
  }
}

Request table
Name Description
annualAdjustments
object
optional

An object containing the details about annual adjustments.

lossBroughtForward
number
optional

This includes unused losses in the trade from earlier years. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

privateUseAdjustment
number
optional

Private use adjustment on an asset by a sole trader or partner in a partnership, the asset is put into a single-asset pool, and allowances are restricted on the business to private-use ratio. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

balancingCharge
number
optional

Balancing charge on sale or cessation of business use (where you have disposed of assets for more than their tax value). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

businessPremisesRenovationAllowanceBalancingCharges
number
optional

Income from the sale or grant of a long lease for a premium of renovated business premises within 7 years of first use. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

nonResidentLandlord
boolean
required

A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.

For example: false

rentARoom
object
optional

Object holding UK NON FHL Rent A Room income shared.

jointlyLet
boolean
required

A boolean to identify that the Rent A Room income (RAR) is shared with another individual. The value must be true or false.

For example: false

annualAllowances
object
optional

An object containing the details about annual allowances.

annualInvestmentAllowance
number
optional

The amount claimed on equipment bought (except cars) is up to the maximum annual amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

zeroEmissionGoodsVehicleAllowance
number
optional

The number of zero-emissions goods vehicle allowance for goods vehicles purchased for business use.The individual can claim 8% of the writing down allowances on cars with CO2 emissions of more than 130g/km. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

businessPremisesRenovationAllowance
number
optional

Business Premises Renovation Allowance (BPRA) The individual may be able to claim 100% BPRA for the cost of renovating or repairing business premises. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

otherCapitalAllowance
number
optional

The individual can claim capital allowances for renovating business premises in disadvantaged areas of the UK, extracting minerals, research, and developing know-how (intellectual property about industrial techniques), patents, and dredging. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfReplacingDomesticGoods
number
optional

Cost of Replacing Domestic Items - formerly Wear and Tear allowance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

propertyIncomeAllowance
number
optional

The amount of tax exemption for individuals with income from land or property. The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 100.25

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

Example response

{
  "links": [
    {
      "href": "/individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20",
      "method": "PUT",
      "rel": "create-and-amend-uk-property-historic-non-fhl-annual-submission"
    },
    {
      "href": "/individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/non-furnished-holiday-lettings/AA999999A/2019-20",
      "method": "DELETE",
      "rel": "delete-uk-property-historic-non-fhl-annual-submission"
    }
  ]
}

Response table
Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint.

For example: /individuals/business/property/uk/non-furnished-holiday-lettings/TC663795B/2021-22

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
DELETE
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

create-and-amend-uk-property-historic-non-fhl-annual-submission
self
delete-uk-property-historic-non-fhl-annual-submission

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

One or more values have been added with the incorrect format.

400 (Bad Request)

FORMAT_VALUE

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/property/uk/annual/non-furnished-holiday-lettings/{nino}/{taxYear}

Delete a Historic Non-FHL UK Property Business Annual Submission
DELETE

This endpoint enables you to delete the income from adjustments and allowances for a non-furnished holiday lettings (non-FHL) UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and tax year must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Delete a UK Property Business Annual Submission endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18 and the maximum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid.

For example: 2021-22

Request headers

Request headers Table
Name Description
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

DELETE

Simulates a success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section

Historic FHL UK Property Income & Expenses Period Summary

Resources relating to an individual's historic FHL UK Property Income & Expenses Period Summaries.

Historic FHL UK Property Income & Expenses Period Summary resources

/individuals/business/property/uk/period/furnished-holiday-lettings/{nino}

List Historic FHL UK Property Income & Expenses Period Summaries
GET

This endpoint enables you to list the income and expenses for a furnished holiday lettings (FHL) UK property business for a specific period within tax years 2017-18 to 2021-22. A National Insurance number is required.

To list summaries from the current tax year, use the List Property Income & Expenses Period Summaries endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Default Example

{
  "submissions": [
    {
      "periodId": "2019-03-24_2020-05-28",
      "fromDate": "2019-03-24",
      "toDate": "2020-05-28",
      "links": [
        {
          "href": "/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2019-03-24_2020-05-28",
          "method": "PUT",
          "rel": "amend-uk-property-historic-fhl-period-summary"
        },
        {
          "href": "/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2019-03-24_2020-05-28",
          "method": "GET",
          "rel": "self"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B",
      "method": "POST",
      "rel": "create-uk-property-historic-fhl-period-summary"
    }
  ]
}

Response table
Name Description
submissions
array
required

Array containing details about FHL UK property update periods

periodId
string
optional

An identifier for the update period, unique to the customer's UK property business.

For example: 2017-04-06_2017-07-04

fromDate
string
optional

The first day that the income, expenses and deduction period summary covers. Must conform to the format: YYYY-MM-DD.

For example: 2017-04-06

toDate
string
optional

The last day that the income, expenses and deduction period summary covers. Must conform to the format: YYYY-MM-DD

For example: 2017-07-04

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

self
amend-uk-property-historic-fhl-period-summary
href
string
required

The relative url of the endpoint.

For example: /individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2019-03-24_2020-05-28

links
array
required

A list of endpoint links that indicate possible actions related to the current resource.

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
POST
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

self
create-uk-property-historic-fhl-period-summary
href
string
required

The relative url of the endpoint.

For example: /individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success response.

EMPTY

Simulates the scenario where no data is found.


Close Section
/individuals/business/property/uk/period/furnished-holiday-lettings/{nino}

Create a Historic FHL UK Property Income & Expenses Period Summary
POST

This endpoint enables you to create income and expenses for a furnished holiday lettings (FHL) UK property business and make periodic submissions for tax years from 2017-18 to 2021-22. A National Insurance number must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the use the Create a UK Property Income & Expenses Period Summary endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Full Expenses request

{
  "fromDate": "2017-04-06",
  "toDate": "2017-07-05",
  "income": {
    "periodAmount": 100.25,
    "taxDeducted": 100.25,
    "rentARoom": {
      "rentsReceived": 100.25
    }
  },
  "expenses": {
    "premisesRunningCosts": 100.25,
    "repairsAndMaintenance": 100.25,
    "financialCosts": 100.25,
    "professionalFees": 100.25,
    "costOfServices": 100.25,
    "other": 100.25,
    "travelCosts": 100.25,
    "rentARoom": {
      "amountClaimed": 100.25
    }
  }
}

Scenario: Consolidated Expenses request

{
  "fromDate": "2017-04-06",
  "toDate": "2017-07-05",
  "income": {
    "periodAmount": 100.25,
    "taxDeducted": 100.25,
    "rentARoom": {
      "rentsReceived": 100.25
    }
  },
  "expenses": {
    "consolidatedExpenses": 100.25
  }
}

Request table
Name Description
fromDate
string
optional

The first day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD.

For example: 2020-01-01

toDate
string
optional

The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD.

For example: 2020-01-31

income
object
optional

Object containing the details about income

periodAmount
number
optional

Total rents from property, ground rents and rent charges but not rent-a-room. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxDeducted
number
optional

Tax already deducted from the rental income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding rents received for the period

rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

expenses
object
optional

Object holding the expenses for the period

premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places

For example: 5000.99

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places

For example: 5000.99

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. You can either submit a consolidatedExpenses value or individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, travelCosts, rentARoom). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

rentARoom
object
optional

Object holding the amount claimed for the period

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

Responses

HTTP status 201 (Created)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Default Example

{
  "periodId": "2017-04-06_2017-07-04",
  "links": [
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/KZ816096B/2017-04-06_2017-07-04",
      "method": "PUT",
      "rel": "amend-uk-property-historic-fhl-period-summary"
    },
    {
      "href": "/individuals/business/property/uk/furnished-holiday-lettings/KZ816096B/2017-04-06_2017-07-04",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Response table
Name Description
periodId
string
required

An identifier for the update period, unique to the UK business property

Must conform to the regular expression [0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{4}-[0-9]{2}-[0-9]{2}

For example: 2017-04-06_2017-07-04

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.

href
string
required

The relative url of the endpoint

For example: "/individuals/business/property/uk/furnished-holiday-lettings/KZ816096B/2017-04-06_2017-07-04"

rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

For example: self

method
string
required

The HTTP method type for the endpoint

For example: GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of one or more monetary fields is not valid.

400 (Bad Request)

FORMAT_VALUE

The format of the supplied From date field is not valid.

400 (Bad Request)

FORMAT_FROM_DATE

The format of the supplied To date field is not valid.

400 (Bad Request)

FORMAT_TO_DATE

The To date is earlier than the From date.

400 (Bad Request)

RULE_TO_DATE_BEFORE_FROM_DATE

Both Expenses and Consolidated Expenses must not be present at the same time.

400 (Bad Request)

RULE_BOTH_EXPENSES_SUPPLIED

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

A summary has already been submitted for the period specified.

400 (Bad Request)

RULE_DUPLICATE_SUBMISSION

Period summary is not within the accounting period.

400 (Bad Request)

RULE_MISALIGNED_PERIOD

Period summary overlaps with any of the existing period summaries.

400 (Bad Request)

RULE_OVERLAPPING_PERIOD

Period summaries are not contiguous.

400 (Bad Request)

RULE_NOT_CONTIGUOUS_PERIOD

The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success response.

NOT_FOUND

Simulates the scenario where no data is found.

DUPLICATE_SUBMISSION

Simulates the scenario where the submission period has already been submitted.

MISALIGNED_PERIOD

Simulates the scenario where the period summary is not within the accounting period.

OVERLAPPING_PERIOD

Simulates the scenario where the period summary overlaps with any of the existing period summaries.

NOT_CONTIGUOUS_PERIOD

Simulates the scenario where period summaries are not contiguous.

TAX_YEAR_NOT_SUPPORTED

Simulates the scenario where the specified tax year is not supported.


Close Section
/individuals/business/property/uk/period/furnished-holiday-lettings/{nino}/{periodId}

Retrieve a Historic FHL UK Property Income & Expenses Period Summary
GET

This endpoint enables you to retrieve income and expenses for a FHL UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and a period ID must be provided.

Use this endpoint only for the specified tax year range; for current tax year submissions, use the Retrieve a UK Property Income & Expenses Period Summary endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

periodId
string
required

An identifier for the update period, unique to the customer's UK property business.

For example: 2017-04-06_2017-07-04

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.2.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

Example response

{
  "fromDate":"2017-04-06",
  "toDate":" 2017-07-04",
  "income":{
    "periodAmount":5000.99,
    "taxDeducted":5000.99,
    "rentARoom":{
      "rentsReceived":5000.99
    }
  },
  "expenses":{
    "premisesRunningCosts": 5000.99,
    "repairsAndMaintenance": 5000.99,
    "financialCosts": 5000.99,
    "professionalFees": 5000.99,
    "costOfServices": 5000.99,
    "other": 5000.99,
    "travelCosts": 5000.99,
    "rentARoom":{
      "amountClaimed":5000.99
    }
  },
  "links": [
    {
      "href":"/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2017-04-06_2017-07-04",
      "method": "PUT",
      "rel": "amend-uk-property-historic-fhl-period-summary"
    },
    {
      "href":"/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2017-04-06_2017-07-04",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B",
      "method": "GET",
      "rel": "list-uk-property-historic-fhl-period-summaries"
    }
  ]
}

Example Consolidated response

{
  "fromDate": "2017-04-06",
  "toDate": "2017-07-05",
  "income": {
    "periodAmount": 100.25,
    "taxDeducted": 100.25,
    "rentARoom": {
      "rentsReceived": 100.25
    }
  },
  "expenses": {
    "consolidatedExpenses": 5000.99
  },
  "links": [
    {
      "href":"/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2017-04-06_2017-07-04",
      "method": "PUT",
      "rel": "amend-uk-property-historic-fhl-period-summary"
    },
    {
      "href":"/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2017-04-06_2017-07-04",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B",
      "method": "GET",
      "rel": "list-uk-property-historic-fhl-period-summaries"
    }
  ]
}

Response table
Name Description
fromDate
string
required

The first day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD

For example: 2020-01-01

toDate
string
required

The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD

For example: 2020-01-31

income
object
optional
periodAmount
number
optional

Total rents from property, ground rents and rent charges but not rent-a-room. The value must be between 0 and 99999999999.99 up to 2 decimal places.

taxDeducted
number
optional

Tax already deducted from the rental income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

rentARoom
object
optional
rentsReceived
number
optional

Total rents received from properties. The value must be between 0 and 99999999999.99 up to 2 decimal places.

expenses
object
optional
premisesRunningCosts
number
optional

Rent, rates, insurance, ground rents and other costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99 up to 2 decimal places.

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99 up to 2 decimal places.

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99 up to 2 decimal places.

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. If consolidatedExpenses is returned, values for individual expenses (premisesRunningCosts, repairsAndMaintenance, financialCosts, professionalFees, costOfServices, other, travelCosts, rentARoom) are not returned. The value must be between 0 and 99999999999.99 up to 2 decimal places.

travelCosts
number
optional

Car, van and travel costs incurred in running a property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

rentARoom
object
optional

Object holding the amount claimed for the period

amountClaimed
number
optional

The amount of UK Furnished Holiday Lettings rent claimed. The value must be between 0 and 99999999999.99 up to 2 decimal places.

links
array
optional
href
string
required

The relative url of the endpoint

For example: /individuals/business/property/uk/period/furnished-holiday-lettings/TC663795B/2017-04-06_2017-07-04

method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

PUT
GET
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource

Limited to the following possible values:

amend-uk-property-historic-fhl-period-summary
self
list-uk-property-historic-fhl-period-summaries

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied Period ID field is not valid.

400 (Bad Request)

FORMAT_PERIOD_ID

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates a success response.

NOT_FOUND

Simulates the scenario where no data is found.

CONSOLIDATED

Simulates the scenario where success response containing consolidated expenses is found.


Close Section
/individuals/business/property/uk/period/furnished-holiday-lettings/{nino}/{periodId}

Amend a Historic FHL UK Property Income & Expenses Period Summary
PUT

This endpoint enables you to amend income and expenses for a periodic submission relating to a furnished holiday lettings UK property business for tax years from 2017-18 to 2021-22. A National Insurance number and a period ID must be provided.

To amend submissions for the current tax year, use the Amend a UK Property Income & Expenses Period Summary endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

periodId
string
required

An identifier for the update period, unique to the customer's UK property business.

For example: 2017-04-06_2017-07-04

Request headers

Request headers Table
Name Description
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Full Expenses request

{
  "income": {
    "periodAmount": 1123.45,
    "taxDeducted": 2134.53,
    "rentARoom": {
      "rentsReceived": 5167.56
    }
  },
  "expenses": {
    "premiseRunningCosts": 5167.53,
    "repairsAndMaintenance": 424.65,
    "financialCosts": 853.56,
    "professionalFees": 835.78,
    "costOfServices": 978.34,
    "other": 382.34,
    "travelCosts": 145.56,
    "rentARoom": {
      "amountClaimed": 945.9
    }
  }
}

Scenario: Consolidated Expenses request

{
  "income": {
    "periodAmount": 1123.45,
    "taxDeducted": 2134.53,
    "rentARoom": {
      "rentsReceived": 5167.56
    }
  },
  "expenses": {
    "consolidatedExpenses": 135.78
  }
}

Request table
Name Description
income
object
optional

Object containing the details about income

periodAmount
number
optional

Total rents from property, ground rents and rent charges but not rent-a-room. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1123.45

taxDeducted
number
optional

Tax already deducted from the rental income. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2134.53

rentARoom
object
optional

Objects holding rents received for the period

rentsReceived
number