This version is in beta - expect some breaking changes.

Property Business (MTD) API

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

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

• Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
• Raise technical issues on the income-tax-mtd-changelog GitHub page.

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

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

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

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":"2022-06-17T10:53:38Z",
  "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":"2022-06-17T10:53:38Z",
  "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"
    }
  ]
}

Name	Description
submittedOn string required	The date the UK property was submitted, in the format YYYY-MM-DDThh:mm:ssZ For example: 2022-07-07T10:59:47Z
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

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. That is, the tax year specified is before the minimum 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

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

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
      }
    }
  }
}

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

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"
    }
  ]
}

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

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. That is, the tax year specified is before the minimum 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

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

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
    }
  }
}

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. 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. 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

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"
    }
  ]
}

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

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. That is, the tax year specified is before the minimum 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

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

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

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-21T08:57:47Z",
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "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-21T08:57:47Z",
  "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"
    }
  ]
}

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
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. 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. 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

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. That is, the tax year specified is before the minimum 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

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

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
    }
  }
}

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. 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. 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

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"
    }
  ]
}

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

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. That is, the tax year specified is before the minimum 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

Foreign Property Income & Expenses Period Summary

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

Foreign Property Income & Expenses Period Summary resources

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

Create a Foreign Property Income & Expenses Period Summary

POST

This endpoint allows the developer to submit the income and expenses for a foreign property business that occurred between two dates. This submission is for either or both of Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) and all other foreign Property submissions. In the case of Non-FHL Foreign Property, if there are multiple properties per country, the income and expenses should be the total across all properties. A National Insurance number, tax year and business 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

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 2021-22. No gaps are allowed, for example, 2022-24 is not valid. For example: 2022-23

Request headers

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 Expenditure request

{
  "fromDate": "2020-04-06",
  "toDate": "2021-04-06",
  "foreignFhlEea": {
    "income": {
      "rentAmount": 5000.99
    },
    "expenses": {
      "premisesRunningCosts": 5000.99,
      "repairsAndMaintenance": 5000.99,
      "financialCosts": 5000.99,
      "professionalFees": 5000.99,
      "costOfServices": 5000.99,
      "travelCosts": 5000.99,
      "other": 5000.99
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "FRA",
      "income": {
        "rentIncome": {
          "rentAmount": 5000.99
        },
        "foreignTaxCreditRelief": false,
        "premiumsOfLeaseGrant": 5000.99,
        "otherPropertyIncome": 5000.99,
        "foreignTaxPaidOrDeducted": 5000.99,
        "specialWithholdingTaxOrUkTaxPaid": 5000.99
      },
      "expenses": {
        "premisesRunningCosts": 5000.99,
        "repairsAndMaintenance": 5000.99,
        "financialCosts": 5000.99,
        "professionalFees": 5000.99,
        "costOfServices": 5000.99,
        "travelCosts": 5000.99,
        "residentialFinancialCost": 5000.99,
        "broughtFwdResidentialFinancialCost": 5000.99,
        "other": 5000.99
      }
    }
  ]
}

Scenario: Consolidated Expenditure request

{
  "fromDate": "2020-04-06",
  "toDate": "2021-04-06",
  "foreignFhlEea": {
    "income": {
      "rentAmount": 5000.99
    },
    "expenses": {
      "consolidatedExpenses": 5000.99
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "FRA",
      "income": {
        "rentIncome": {
          "rentAmount": 5000.99
        },
        "foreignTaxCreditRelief": false,
        "premiumsOfLeaseGrant": 5000.99,
        "otherPropertyIncome": 5000.99,
        "foreignTaxPaidOrDeducted": 5000.99,
        "specialWithholdingTaxOrUkTaxPaid": 5000.99
      },
      "expenses": {
        "residentialFinancialCost": 200.25,
        "broughtFwdResidentialFinancialCost": 100.25,
        "consolidatedExpenses": 100.25
      }
    }
  ]
}

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
foreignFhlEea object optional	Object holding the income and expenses of the user's Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) for the period.
income object optional	Object holding the income details for the period.
rentAmount number required	Total rent and other income from property. 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
consolidatedExpenses number optional	The sum of all expenses for the specified period.The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignNonFhlProperty array optional	Array holding the income and expenses of the user's foreign property business - excluding Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) - for the period.
countryCode string required	A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. For example: FRA
income object required	Object holding the income details for the period.
rentIncome object required	Object holding the rent income.
rentAmount number required	Total rent and other income from property. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignTaxCreditRelief boolean required	A boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed. For example: true
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
otherPropertyIncome number optional	Other income from property, such as rent charges and ground rents, income from letting others tip waste on your land, and income for the use of a caravan or houseboat at a fixed location. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignTaxPaidOrDeducted number optional	The total amount of foreign tax paid or deducted from your income. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
specialWithholdingTaxOrUkTaxPaid number optional	Tax withheld (in UK Pounds) on certain payments to UK residents or UK Tax paid from rental Income (applies to non-resident landlords only). 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
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
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
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
broughtFwdResidentialFinancialCost number optional	Amount of relief brought forward for restricted residential financial costs. 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. 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

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/foreign/TC663795B/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/individuals/business/property/foreign/TC663795B/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method":"PUT",
      "rel":"amend-foreign-property-period-summary"
    }
  ]
}

Name	Description
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
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/foreign/AA999999A/XAIS12345678910/period/2021-22/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 amend-foreign-property-period-summary
method string required	The HTTP method type for the endpoint Limited to the following possible values: GET PUT

Error scenarios

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 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
The format of the supplied Country Code field is not valid.	400 (Bad Request)	FORMAT_COUNTRY_CODE
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. That is, the tax year specified is before the minimum 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 foreign property business.	400 (Bad Request)	RULE_TYPE_OF_BUSINESS_INCORRECT
The To date is earlier than the From date.	400 (Bad Request)	RULE_TO_DATE_BEFORE_FROM_DATE
Not a valid ISO 3166-1 alpha-3 country code.	400 (Bad Request)	RULE_COUNTRY_CODE
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED
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 same countryCode cannot be supplied for multiple properties. If there are multiple properties per country the adjustments and allowances should be the total across all properties.	400 (Bad Request)	RULE_DUPLICATE_COUNTRY_CODE
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/foreign/{nino}/{businessId}/period/{taxYear}/{submissionId}

Retrieve a Foreign Property Income & Expenses Period Summary

GET

This endpoint allows a developer to retrieve the income and expenses for a Foreign Property business, using the submission ID for either or both of Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) and all other Foreign 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

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 2021-22. No gaps are allowed, for example, 2022-24 is not valid. For example: 2022-23
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

Request headers

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

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 Expenses response

{
  "submittedOn": "2021-07-07T10:59:47Z",
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "foreignFhlEea": {
    "income": {
      "rentAmount": 200.22
    },
    "expenses": {
      "premisesRunningCosts": 100.25,
      "repairsAndMaintenance": 100.25,
      "financialCosts": 100.25,
      "professionalFees": 100.25,
      "costOfServices": 100.25,
      "travelCosts": 100.25,
      "other": 100.25
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "FRA",
      "income": {
        "rentIncome": {
          "rentAmount": 200.22
        },
        "foreignTaxCreditRelief": true,
        "premiumsOfLeaseGrant": 100.25,
        "otherPropertyIncome": 100.25,
        "foreignTaxPaidOrDeducted": 44.21,
        "specialWithholdingTaxOrUkTaxPaid": 23.78
      },
      "expenses": {
        "premisesRunningCosts": 100.25,
        "repairsAndMaintenance": 100.25,
        "financialCosts": 200.25,
        "professionalFees": 100.25,
        "costOfServices": 100.25,
        "travelCosts": 100.25,
        "other": 100.25
      }
    }
  ],
  "links": [
    {
      "href": "/individuals/business/property/foreign/CX897463D/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "PUT",
      "rel": "amend-foreign-property-period-summary"
    },
    {
      "href": "/individuals/business/property/foreign/CX897463D/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/CX897463D/XAIS12345678910/period/2021-22",
      "method": "GET",
      "rel": "list-property-period-summaries"
    }
  ]
}

Consolidated Expenses response

{
  "submittedOn": "2021-07-07T10:59:47Z",
  "fromDate": "2020-01-01",
  "toDate": "2020-01-31",
  "foreignFhlEea": {
    "income": {
      "rentAmount": 200.22
    },
    "expenses": {
      "consolidatedExpenses": 100.25
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "FRA",
      "income": {
        "rentIncome": {
          "rentAmount": 200.22
        },
        "foreignTaxCreditRelief": true,
        "premiumsOfLeaseGrant": 100.25,
        "otherPropertyIncome": 100.25,
        "foreignTaxPaidOrDeducted": 44.21,
        "specialWithholdingTaxOrUkTaxPaid": 23.78
      },
      "expenses": {
        "residentialFinancialCost": 200.25,
        "broughtFwdResidentialFinancialCost": 100.25,
        "consolidatedExpenses": 100.25
      }
    }
  ],
  "links": [
    {
      "href": "/individuals/business/property/foreign/CX897463D/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "PUT",
      "rel": "amend-foreign-property-period-summary"
    },
    {
      "href": "/individuals/business/property/foreign/CX897463D/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/CX897463D/XAIS12345678910/period/2021-22",
      "method": "GET",
      "rel": "list-property-period-summaries"
    }
  ]
}

Name	Description
submittedOn string required	The date the foreign property were submitted, in the format YYYY-MM-DDThh:mm:ssZ For example: 2021-07-07T10:59:47Z
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
foreignFhlEea object optional	Object holding the income and expenses of the user's Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) for the period.
income object optional	Object holding the income details for the period.
rentAmount number optional	Total rent and other income from property. 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	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
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
consolidatedExpenses number optional	The sum of all expenses for the specified period. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignNonFhlProperty array optional	Array holding the income and expenses of the user's foreign property business - excluding Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) - for the period.
countryCode string required	A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. For example: FRA
income object optional	Object holding the income details for the period.
rentIncome object optional	Object holding the rent income.
rentAmount number optional	Total rent and other income from property. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignTaxCreditRelief boolean required	A boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed. For example: false
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
otherPropertyIncome number optional	Other income from property, such as rent charges and ground rents, income from letting others tip waste on your land, and income for the use of a caravan or houseboat at a fixed location. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignTaxPaidOrDeducted number optional	The total amount of foreign tax paid or deducted from your income. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
specialWithholdingTaxOrUkTaxPaid number optional	Tax withheld (in UK Pounds) on certain payments to UK residents or UK Tax paid from rental Income (applies to non-resident landlords only). 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
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
broughtFwdResidentialFinancialCost number optional	Amount of relief brought forward for restricted residential financial costs. 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. 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/foreign/CX897463D/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c
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-foreign-property-period-summary list-property-period-summaries

Error scenarios

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 Submission ID field is not valid.	400 (Bad Request)	FORMAT_SUBMISSION_ID
The supplied Business ID does not represent a foreign 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.
FOREIGN_PROPERTY	Simulates success response with Foreign FHL and Non-FHL properties.
FOREIGN_FHL_FULL_EXPENSES	Simulates success response with Foreign FHL property.
FOREIGN_FHL_CONSOLIDATED	Simulates the scenario of a FHL property with consolidated expenses.
FOREIGN_NON_FHL_FULL_EXPENSES	Simulates success response with Foreign Non-FHL property.
FOREIGN_NON_FHL_CONSOLIDATED	Simulates the scenario of a Non-FHL property with consolidated expenses.
UK_PROPERTY	Simulates the scenario where wrong business type is returned.

Close Section

/individuals/business/property/foreign/{nino}/{businessId}/period/{taxYear}/{submissionId}

Amend a Foreign Property Income & Expenses Period Summary

PUT

This endpoint allows a developer to amend the income and expenses for a foreign property business. This submission is for either or both of Furnished Holiday Letting (FHL) in the European Economic Area (EEA) and all other foreign property submissions. In the case of Non-FHL Foreign Property, if there are multiple properties per country, the income and expenses should be the total across all properties. 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

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 2021-22. No gaps are allowed, for example, 2022-24 is not valid. For example: 2022-23
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

Request headers

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

{
  "foreignFhlEea": {
    "income": {
      "rentAmount": 1123.89
    },
    "expenses": {
      "premisesRunningCosts": 332.78,
      "repairsAndMaintenance": 231.45,
      "financialCosts": 345.23,
      "professionalFees": 232.45,
      "costOfServices": 231.56,
      "travelCosts": 234.67,
      "other": 3457.9
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "AFG",
      "income": {
        "rentIncome": {
          "rentAmount": 440.31
        },
        "foreignTaxCreditRelief": false,
        "premiumsOfLeaseGrant": 950.48,
        "otherPropertyIncome": 802.49,
        "foreignTaxPaidOrDeducted": 734.18,
        "specialWithholdingTaxOrUkTaxPaid": 85.47
      },
      "expenses": {
        "premisesRunningCosts":129.35,
        "repairsAndMaintenance":7490.32,
        "financialCosts":5000.99,
        "professionalFees":847.90,
        "travelCosts":69.20,
        "costOfServices":478.23,
        "residentialFinancialCost":879.28,
        "broughtFwdResidentialFinancialCost":846.13,
        "other":138.92
      }
    }
  ]
}

Scenario: Consolidated Expenses request

{
  "foreignFhlEea": {
    "income": {
      "rentAmount": 1123.89
    },
    "expenses": {
      "consolidatedExpenses": 334.64
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "AFG",
      "income": {
        "rentIncome": {
          "rentAmount": 440.31
        },
        "foreignTaxCreditRelief": false,
        "premiumsOfLeaseGrant": 950.48,
        "otherPropertyIncome": 802.49,
        "foreignTaxPaidOrDeducted": 734.18,
        "specialWithholdingTaxOrUkTaxPaid": 85.47
      },
      "expenses": {
        "consolidatedExpenses": 3992.93,
        "residentialFinancialCost":879.28,
        "broughtFwdResidentialFinancialCost":846.13
      }
    }
  ]
}

Name	Description
foreignFhlEea object optional	Object holding the income and expenses of the user's Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) for the period.
income object optional	Object holding the income details for the period.
rentAmount number required	Total rent and other income from property. 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
consolidatedExpenses number optional	The sum of all expenses for the specified period. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignNonFhlProperty array optional	Array holding the income and expenses of the user's foreign property business - excluding Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) - for the period.
countryCode string required	A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. For example: FRA
income object optional	Object holding the income details for the period.
rentIncome object optional	Object holding the rent income.
rentAmount number optional	Total rent and other income from property. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignTaxCreditRelief boolean required	A boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed. The value must be true or false. For example: false
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
otherPropertyIncome number optional	Other income from property, such as rent charges and ground rents, income from letting others tip waste on your land, and income for the use of a caravan or houseboat at a fixed location. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
foreignTaxPaidOrDeducted number optional	The total amount of foreign tax paid or deducted from your income. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
specialWithholdingTaxOrUkTaxPaid number optional	Tax withheld (in UK Pounds) on certain payments to UK residents or UK Tax paid from rental Income (applies to non-resident landlords only). 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
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
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
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
broughtFwdResidentialFinancialCost number optional	Amount of relief brought forward for restricted residential financial costs. 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. 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

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/foreign/TC663795B/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/individuals/business/property/foreign/TC663795B/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "method": "PUT",
      "rel": "amend-foreign-property-period-summary"
    },
    {
      "href": "/individuals/business/property/TC663795B/XAIS12345678910/period/2021-22",
      "method": "GET",
      "rel": "list-property-period-summaries"
    }
  ]
}

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/foreign/TC663795B/XAIS12345678910/period/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c
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: list-property-period-summaries amend-foreign-property-period-summary self

Error scenarios

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 the supplied Country Code field is not valid.	400 (Bad Request)	FORMAT_COUNTRY_CODE
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. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
The format of one or more monetary fields is not valid.	400 (Bad Request)	FORMAT_VALUE
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 foreign property business.	400 (Bad Request)	RULE_TYPE_OF_BUSINESS_INCORRECT
The same countryCode cannot be supplied for multiple properties. If there are multiple properties per country the adjustments and allowances should be the total across all properties.	400 (Bad Request)	RULE_DUPLICATE_COUNTRY_CODE
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED
Not a valid ISO 3166-1 alpha-3 country code.	400 (Bad Request)	RULE_COUNTRY_CODE
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 foreign property is supplied.

Close Section

Foreign Property Annual Submission

Resources relating to an individual's Foreign Property Annual Submission

Foreign Property Annual Submission resources

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

Retrieve a Foreign Property Annual Submission

GET

This endpoint allows a developer to retrieve adjustments and allowances for a foreign property business. For either or both of Furnished Holiday Letting (FHL) in the European Economic Area (EEA) and Non FHL Foreign 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

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 2021-22. No gaps are allowed, for example, 2022-24 is not valid. For example: 2022-23

Request headers

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

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":"2022-06-17T10:53:38Z",
  "foreignFhlEea":{
    "adjustments":{
      "privateUseAdjustment":34343.45,
      "balancingCharge":53543.23,
      "periodOfGraceAdjustment":true
    },
    "allowances":{
      "annualInvestmentAllowance":3434.23,
      "otherCapitalAllowance":1343.34,
      "electricChargePointAllowance":6565.45,
      "zeroEmissionsCarAllowance":3456.34
    }
  },
  "foreignNonFhlProperty":[
    {
      "countryCode":"LBN",
      "adjustments":{
        "privateUseAdjustment":4553.34,
        "balancingCharge":3453.34
      },
      "allowances":{
        "annualInvestmentAllowance":38330.95,
        "costOfReplacingDomesticItems":41985.17,
        "zeroEmissionsGoodsVehicleAllowance":9769.19,
        "otherCapitalAllowance":1049.21,
        "electricChargePointAllowance":3565.45,
        "structuredBuildingAllowance":[
          {
            "amount":3545.12,
            "firstYear":{
              "qualifyingDate":"2020-03-29",
              "qualifyingAmountExpenditure":3453.34
            },
            "building":{
              "name":"Blue Oaks",
              "number":"12",
              "postcode":"TF3 4GH"
            }
          }
        ],
        "zeroEmissionsCarAllowance":3456.34
      }
    }
  ],
  "links":[
    {
      "href":"/individuals/business/property/foreign/AA999999A/XAIS12345678910/annual/2022-23",
      "method":"PUT",
      "rel":"create-and-amend-foreign-property-annual-submission"
    },
    {
      "href":"/individuals/business/property/foreign/AA999999A/XAIS12345678910/annual/2022-23",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/individuals/business/property/AA999999A/XAIS12345678910/annual/2022-23",
      "method":"DELETE",
      "rel":"delete-property-annual-submission"
    }
  ]
}

Property Allowance Response

{
  "submittedOn":"2022-06-17T10:53:38Z",
  "foreignFhlEea":{
    "adjustments":{
      "balancingCharge":53543.23,
      "periodOfGraceAdjustment":true
    },
    "allowances":{
      "propertyIncomeAllowance":100.25
    }
  },
  "foreignNonFhlProperty":[
    {
      "countryCode":"LBN",
      "adjustments":{
        "balancingCharge":3453.34
      },
      "allowances":{
        "propertyIncomeAllowance":100.25
      }
    }
  ],
  "links":[
    {
      "href":"/individuals/business/property/foreign/AA999999A/XAIS12345678910/annual/2022-23",
      "method":"PUT",
      "rel":"create-and-amend-foreign-property-annual-submission"
    },
    {
      "href":"/individuals/business/property/foreign/AA999999A/XAIS12345678910/annual/2022-23",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/individuals/business/property/AA999999A/XAIS12345678910/annual/2022-23",
      "method":"DELETE",
      "rel":"delete-property-annual-submission"
    }
  ]
}

Name	Description
submittedOn string required	The date the foreign property was submitted, in the format YYYY-MM-DDThh:mm:ssZ For example: 2022-06-17T10:53:38Z
foreignFhlEea object optional	Object holding the adjustments and allowances of the user's Furnished Holiday Lets in the European Economic Area for the period.
adjustments object optional	Object holding Foreign FHL EEA 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 optional	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
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
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: 100.25
foreignNonFhlProperty array optional	Array holding the adjustments and allowances of the user's foreign property business - excluding Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) for the period.
countryCode string required	A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. Must conform to the regular expression ^[A-Z]{3}$ For example: FRA
adjustments object optional	Object holding foreign Non FHL Property annual 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
allowances object optional	Object holding foreign 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
costOfReplacingDomesticItems 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
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
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: 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 foreign 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 Foreign 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
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/foreign/AA999999A/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 create-and-amend-foreign-property-annual-submission delete-property-annual-submission

Error scenarios

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. That is, the tax year specified is before the minimum 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 foreign 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.
FOREIGN_PROPERTY	Simulates the scenario with FHL and Non-FHL properties.
FOREIGN_FHL_ALL_OTHER_ALLOWANCES	Simulates the scenario of a FHL property with all other allowances.
FOREIGN_FHL_PROPERTY_ALLOWANCE	Simulates the scenario of a FHL property with property allowance.
FOREIGN_NON_FHL_ALL_OTHER_ALLOWANCES	Simulates the scenario of a Non-FHL property with all other allowances.
FOREIGN_NON_FHL_PROPERTY_ALLOWANCE	Simulates the scenario of a Non-FHL property with property allowance.
UK_PROPERTY	Simulates the scenario where the type of business is incorrect.

Close Section

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

Create and Amend a Foreign Property Annual Submission

PUT

This endpoint allows a developer to re-submit adjustments and allowances for a foreign property business. This submission is for either or both of Furnished Holiday Letting (FHL) in the European Economic Area (EEA) and Non FHL Foreign Property submissions. In the case of Non-FHL Foreign Property, if there are multiple properties per country, the adjustments and allowances should be the total across all properties. A National Insurance number, business ID and tax year must be provided.

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

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 2021-22. No gaps are allowed, for example, 2022-24 is not valid. For example: 2022-23

Request headers

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: All Other Allowances request

{
  "foreignFhlEea": {
    "adjustments": {
      "privateUseAdjustment": 34343.45,
      "balancingCharge": 53543.23,
      "periodOfGraceAdjustment": true
    },
    "allowances": {
      "annualInvestmentAllowance": 3434.23,
      "otherCapitalAllowance": 1343.34,
      "electricChargePointAllowance": 6565.45,
      "zeroEmissionsCarAllowance": 3456.34
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "LBN",
      "adjustments": {
        "privateUseAdjustment": 4553.34,
        "balancingCharge": 3453.34
      },
      "allowances": {
        "annualInvestmentAllowance": 38330.95,
        "costOfReplacingDomesticItems": 41985.17,
        "zeroEmissionsGoodsVehicleAllowance": 9769.19,
        "otherCapitalAllowance": 1049.21,
        "electricChargePointAllowance": 3565.45,
        "zeroEmissionsCarAllowance": 1000.99,
        "structuredBuildingAllowance": [
          {
            "amount": 3545.12,
            "firstYear": {
              "qualifyingDate": "2020-03-29",
              "qualifyingAmountExpenditure": 3453.34
            },
            "building": {
              "name": "Green Oaks",
              "number": "12",
              "postcode": "TF3 4GH"
            }
          }
        ]
      }
    }
  ]
}

Scenario: Property Allowance request

{
  "foreignFhlEea": {
    "adjustments": {
      "balancingCharge": 53543.23,
      "periodOfGraceAdjustment": true
    },
    "allowances": {
      "propertyIncomeAllowance": 100.25
    }
  },
  "foreignNonFhlProperty": [
    {
      "countryCode": "LBN",
      "adjustments": {
        "balancingCharge": 3453.34
      },
      "allowances": {
        "propertyIncomeAllowance": 200.25
      }
    }
  ]
}

Name	Description
foreignFhlEea object optional	Object holding the adjustments and allowances of the user's Furnished Holiday Lets in the European Economic Area for the period.
adjustments object optional	Object holding Foreign FHL EEA 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: 5001.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
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: 5002.89
otherCapitalAllowance number optional	All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5003.79
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: 5004.69
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: 5005.59
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
foreignNonFhlProperty array optional	Array holding the adjustments and allowances of the user's foreign property business - excluding Furnished Holiday Lettings (FHL) in the European Economic Area (EEA) for the period.
countryCode string required	A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. For example: FRA
adjustments object optional	Object holding foreign Non FHL Property annual 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: 5003.39
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: 5002.29
allowances object optional	Object holding foreign 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: 5001.19
costOfReplacingDomesticItems 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: 409.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: 408.89
otherCapitalAllowance number optional	All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 407.00
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: 406.69
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: 4005.59
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 allowan