Property Business (MTD) API
| Date | Amount |
|---|---|
| Version and status | |
| Available in Sandbox | Yes |
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Available in Production | No |
Overview
This API allows developers to:
- list, retrieve, create or amend an individual’s Foreign Property Income & Expenditure Period Summaries
- retrieve, create, amend or delete an individual’s Foreign Property Annual Summary
For information on how to connect to this API see the Income Tax MTD end-to-end service guide.
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 field 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.
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 [test only]
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.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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 c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Example response
{
"submittedOn":"2022-06-17T10:53:38Z",
"ukFhlProperty":{
"adjustments":{
"lossBroughtForward":343.34,
"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,
"propertyIncomeAllowance":453.45,
"electricChargePointAllowance":453.34,
"zeroEmissionsCarAllowance":123.12
}
},
"ukNonFhlProperty":{
"adjustments":{
"lossBroughtForward":334.45,
"balancingCharge":565.34,
"privateUseAdjustment":533.54,
"businessPremisesRenovationAllowanceBalancingCharges":563.34,
"nonResidentLandlord":true,
"rentARoom":{
"jointlyLet":true
}
},
"allowances":{
"annualInvestmentAllowance":678.45,
"zeroEmissionGoodsVehicleAllowance":456.34,
"businessPremisesRenovationAllowance":573.45,
"otherCapitalAllowance":452.34,
"costOfReplacingDomesticGoods":567.34,
"propertyIncomeAllowance":342.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"
}
]
}
| Name | Description |
|---|---|
|
submittedOn
string
required
|
The date the UK property was submitted, in the format YYYY-MM-DDThh:mm:ss.SSSZ
For example: |
|
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. |
|
lossBroughtForward
number
optional
|
Loss brought forward from earlier years. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
privateUseAdjustment
number
optional
|
Any expenses incurred not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
balancingCharge
number
optional
|
A charge for an item, for which capital allowance was claimed, but has since 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: |
|
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: |
|
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: |
|
nonResidentLandlord
boolean
required
|
A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.
For example: |
|
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: |
|
allowances
object
optional
|
Object holding UK 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: |
|
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: |
|
otherCapitalAllowance
number
optional
|
All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
propertyIncomeAllowance
number
optional
|
The amount of Tax exemption for individuals with income from land or property. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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 Adjustments. |
|
lossBroughtForward
number
optional
|
Loss brought forward from earlier years. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
privateUseAdjustment
number
optional
|
Any expenses incurred that were not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
nonResidentLandlord
boolean
required
|
A boolean to identify that the user is a Non-Resident Landlord. The value must be true or false.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
otherCapitalAllowance
number
optional
|
All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
propertyIncomeAllowance
number
optional
|
The amount of Tax exemption for individuals with income from land or property. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
qualifyingAmountExpenditure
number
required
|
The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
building
object
required
|
Object holding UK Non FHL structured building details. Post code 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
For example: |
|
number
string
optional
|
The number of the building.
Must conform to the regular expression
For example: |
|
postcode
string
required
|
The postcode for the building.
Must conform to the regular expression
For example: |
|
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: |
|
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: |
|
qualifyingAmountExpenditure
number
required
|
The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
building
object
required
|
Object holding UK Non FHL enhanced structured building details. Post code 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
For example: |
|
number
string
optional
|
The number of the building.
Must conform to the regular expression
For example: |
|
postcode
string
required
|
The postcode for the building.
Must conform to the regular expression
For example: |
|
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: |
|
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: |
|
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 success response with UK FHL and Non-FHL properties. |
UK_FHL_PROPERTY |
Simulates success response with UK FHL property. |
UK_NON_FHL_PROPERTY |
Simulates success response with UK Non-FHL property. |
FOREIGN_PROPERTY |
Simulates the scenario where wrong business type is returned. |
Close Section
/individuals/business/property/uk/{nino}/{businessId}/annual/{taxYear}
Create and Amend a UK Property Business Annual Submission [test only]
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.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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": {
"lossBroughtForward": 343.34,
"privateUseAdjustment": 454.45,
"balancingCharge": 231.45,
"periodOfGraceAdjustment": true,
"businessPremisesRenovationAllowanceBalancingCharges": 567.67,
"nonResidentLandlord": true,
"rentARoom": {
"jointlyLet": true
}
}
},
"ukNonFhlProperty": {
"allowances": {
"propertyIncomeAllowance": 678.45
},
"adjustments": {
"lossBroughtForward": 334.45,
"balancingCharge": 565.34,
"privateUseAdjustment": 533.54,
"businessPremisesRenovationAllowanceBalancingCharges": 563.34,
"nonResidentLandlord": true,
"rentARoom": {
"jointlyLet": true
}
}
}
}
Scenario: All Other Allowance request
{
"ukFhlProperty": {
"allowances": {
"annualInvestmentAllowance": 123.45,
"businessPremisesRenovationAllowance": 345.56,
"otherCapitalAllowance": 345.34,
"electricChargePointAllowance": 453.34,
"zeroEmissionsCarAllowance": 123.12
},
"adjustments": {
"lossBroughtForward": 343.34,
"privateUseAdjustment": 454.45,
"balancingCharge": 231.45,
"periodOfGraceAdjustment": true,
"businessPremisesRenovationAllowanceBalancingCharges": 567.67,
"nonResidentLandlord": true,
"rentARoom": {
"jointlyLet": true
}
}
},
"ukNonFhlProperty": {
"allowances": {
"annualInvestmentAllowance": 678.45,
"zeroEmissionGoodsVehicleAllowance": 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": "Building Name",
"number": "1",
"postcode": "SW1A 2AA"
}
}
],
"enhancedStructuredBuildingAllowance": [
{
"amount": 234.45,
"firstYear": {
"qualifyingDate": "2020-05-29",
"qualifyingAmountExpenditure": 453.34
},
"building": {
"name": "Building Name",
"number": "2",
"postcode": "SW1A 2AB"
}
}
],
"zeroEmissionsCarAllowance": 454.34
},
"adjustments": {
"lossBroughtForward": 334.45,
"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. |
|
lossBroughtForward
number
optional
|
Loss brought forward from earlier years. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
privateUseAdjustment
number
optional
|
Any expenses incurred that are not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
periodOfGraceAdjustment
boolean
required
|
A boolean to identify a property which didn't qualify for FHL this year, but qualified the previous year.
For example: |
|
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: |
|
nonResidentLandlord
boolean
required
|
A boolean to identify that the user is a Non-Resident Landlord.
For example: |
|
rentARoom
object
optional
|
Object holding UK FHL Rent A Room income shared. |
|
jointlyLet
boolean
required
|
A boolean to identify that the Rent A Room income (RAR) is shared with another individual.
For example: |
|
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: |
|
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: |
|
otherCapitalAllowance
number
optional
|
All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
propertyIncomeAllowance
number
optional
|
The amount of Tax exemption for individuals with income from land or property. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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. |
|
lossBroughtForward
number
optional
|
Loss brought forward from earlier years. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
privateUseAdjustment
number
optional
|
Any expenses incurred that are not solely for the property business. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
nonResidentLandlord
boolean
required
|
A boolean to identify that the user is a Non-Resident Landlord.
For example: |
|
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.
For example: |
|
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: |
|
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: |
|
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: |
|
otherCapitalAllowance
number
optional
|
All other capital allowances. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
propertyIncomeAllowance
number
optional
|
The amount of Tax exemption for individuals with income from land or property. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
structuredBuildingAllowance
array
optional
|
Details about structured building allowances. |
|
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: |
|
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: |
|
qualifyingAmountExpenditure
number
required
|
The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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
For example: |
|
number
string
optional
|
The number of the building.
Must conform to the regular expression
For example: |
|
postcode
string
required
|
The postcode for the building.
Must conform to the regular expression
For example: |
|
enhancedStructuredBuildingAllowance
array
optional
|
Details about enhanced structured building allowances. |
|
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: |
|
firstYear
object
optional
|
Object holding UK Non FHL enhanced structured building allowance details. |
|
qualifyingDate
string
required
|
The date qualified for structured building allowance. Must conform to the format YYYY-MM-DD.
For example: |
|
qualifyingAmountExpenditure
number
required
|
The amount of qualifying expenditure. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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
For example: |
|
number
string
optional
|
The number of the building.
Must conform to the regular expression
For example: |
|
postcode
string
required
|
The postcode for the building.
Must conform to the regular expression
For example: |
Responses
HTTP status 200 (OK)
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking 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: |
|
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 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 an 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 [test only]
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.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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: |
|
toDate
string
required
|
The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD.
For example: |
|
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 rent and other income from property. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
periodAmount
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: |
|
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: |
|
otherIncome
number
optional
|
Other allowable property incomes. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
Responses
HTTP status 201 (Created)
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking 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
For example: |
|
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: |
|
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: |
|
method
string
required
|
The HTTP method type for the endpoint
For example: |
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 |
|
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. |
Close Section
/individuals/business/property/uk/{nino}/{businessId}/period/{taxYear}/{submissionId}
Retrieve a UK Property Income & Expenses Period Summary [test only]
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.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
|
submissionId
string
required
|
An identifier for the income and expenditure period summary. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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 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/uk/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/uk/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: |
|
fromDate
string
required
|
The first day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD
For example: |
|
toDate
string
required
|
The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD
For example: |
|
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 rent and other income from property. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxDeducted
number
optional
|
The tax deducted from income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
rentARoom
object
optional
|
Object holding the rents claimed for the period. |
|
rentsReceived
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: |
|
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: |
|
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: |
|
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: |
|
periodAmount
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: |
|
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: |
|
otherIncome
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
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 [test only]
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.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
|
submissionId
string
required
|
An identifier for the income and expenditure period summary. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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: |
|
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: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
Responses
HTTP status 200 (OK)
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking 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: |
|
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 & Expenditure Period Summary [test only]
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. A National Insurance number, tax year and business ID are required.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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: |
|
toDate
string
required
|
The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD.
For example: |
|
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.
For example: |
|
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 greater than 0 and up to 99999999999.99.
For example: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
financialCosts
number
optional
|
Loan interest and other financial costs. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
professionalFees
number
optional
|
Legal, management and other professional fees. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
costOfServices
number
optional
|
Cost of services provided, including wages. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
travelCosts
number
optional
|
Car, van and travel costs incurred in running a property business. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
other
number
optional
|
Other allowable property expenses. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
The sum of all expenses for the specified period. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
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: |
|
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.
For example: |
|
foreignTaxCreditRelief
boolean
required
|
A boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed.
For example: |
|
premiumsOfLeaseGrant
number
optional
|
Premiums received for the grant of a lease and other lump sums to possess a property. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
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 greater than 0 and up to 99999999999.99.
For example: |
|
foreignTaxPaidOrDeducted
number
optional
|
The total amount of foreign tax paid or deducted from your income. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
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 greater than 0 and up to 99999999999.99.
For example: |
|
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 greater than 0 and up to 99999999999.99.
For example: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
financialCosts
number
optional
|
Loan interest and other financial costs. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
professionalFees
number
optional
|
Legal, management and other professional fees. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
travelCosts
number
optional
|
Car, van and travel costs incurred in running a property business. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
costOfServices
number
optional
|
Cost of services provided, including wages. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
residentialFinancialCost
number
optional
|
The residential financial cost that can be deducted from rental income (tax relief). The value must be greater than 0 and up to 99999999999.99.
For example: |
|
broughtFwdResidentialFinancialCost
number
optional
|
Amount of relief brought forward for restricted residential financial costs. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
other
number
optional
|
Other allowable property expenses. The value must be greater than 0 and up to 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
The sum of all expenses for the specified period. The value must be greater than 0 and up to 99999999999.99.
For example: |
Responses
HTTP status 201 (Created)
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking 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
For example: |
|
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: |
|
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 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 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. |
Close Section
/individuals/business/property/foreign/{nino}/{businessId}/period/{taxYear}/{submissionId}
Retrieve a Foreign Property Income & Expenses Period Summary [test only]
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.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
|
submissionId
string
required
|
An identifier for the income and expenses period summary. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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 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: |
|
fromDate
string
required
|
The first day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD
For example: |
|
toDate
string
required
|
The last day that the income and expenses period summary covers. Must conform to the format YYYY-MM-DD
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
foreignTaxCreditRelief
boolean
required
|
A boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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 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. |
NO_EXPENSES |
Simulates success response with no expenses. |
Close Section
/individuals/business/property/foreign/{nino}/{businessId}/period/{taxYear}/{submissionId}
Amend a Foreign Property Income & Expenses Period Summary [test only]
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. A National Insurance number, business ID, tax year and submission ID are required.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
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: |
|
submissionId
string
required
|
An identifier for the income and expenses period summary. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
foreignTaxCreditRelief
boolean
required
|
A boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed. The value must be true or false.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
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: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
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: |
Responses
HTTP status 200 (OK)
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Example Response
{
"links":[
{
"href":"/individuals/business/property/foreign/TC663795B/XAIS12345678910/period/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"method":"GET",
"rel":"self"
},
{
"href":"/individuals/business/property/foreign/TC663795B/XAIS12345678910/period/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"method":"PUT",
"rel":"amend-foreign-property-period-summary"
},
{
"href":"/individuals/business/property/TC663795B/XAIS12345678910/period",
"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: |
|
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 UK property business. |
400 (Bad Request) |
RULE_TYPE_OF_BUSINESS_INCORRECT |
|
Duplicate Country code is not allowed. |
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. |
DUPLICATE_COUNTRY_CODE |
Duplicate Country code is not allowed |
Close Section
UK or Foreign Property Annual Submission Deletion
Resources relating to an individual's UK or Foreign Property Annual Submission Deletion
UK or Foreign Property Annual Submission Deletion resources
/individuals/business/property/{nino}/{businessId}/annual/{taxYear}
Delete a Property Annual Submission [test only]
DELETE
This endpoint allows the developer to delete the adjustments and allowances for a UK or Foreign property business in a tax year. A National Insurance number, business ID and tax year must be provided.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
businessId
string
required
|
An identifier for the business, unique to the customer. Must conform to the regular expression
For example: |
|
taxYear
string
required
|
The tax year to which the data applies. For example: 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
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 |
|
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 client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
The supplied income source could not be found. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates a success response. |
NOT_FOUND |
Simulates the scenario where the given property could not be found. |
Close Section