GOV.UK
This version is in beta - expect some breaking changes.
Business Source Adjustable Summary (MTD) API
| Available in Sandbox | Yes |
|---|---|
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Available in Production | Yes |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
This API allows a developer to retrieve a Business Source Adjustable Summary (BSAS) calculation for a specified self-employment or property business, for a given accounting period. Here a developer can:
- generate a list of BSAS
- generate an end of accounting period BSAS
- request a specific BSAS
- request the adjustments made to a specific self-employment BSAS
- provide accounting adjustments against a specified BSAS
- request the adjustments made to a specific property BSAS
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 self-assessment-bsas-api GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the self-assessment-bsas-api 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
/individuals/self-assessment/adjustable-summary/{nino}
This endpoint allows the developer to generate a list of Business Source Adjustable Summaries (BSAS) for a given tax year. A filter can be set to return the BSAS for a single business or business type. The National Insurance number is required.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
Query parameters
| Name | Description |
|---|---|
|
taxYear
string
optional
|
The tax year the data applies to. The start year and end year must not span two tax years. No gaps are allowed, for example, 2018-20 is not valid. The minimum tax year is 2019-20.
For example: |
|
typeOfBusiness
string
optional
|
The type of business the summary calculation is for. Limited to the following possible values:
|
|
businessId
string
optional
|
An identifier for the business, unique to the customer. 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. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"businessSourceSummaries": [
{
"typeOfBusiness": "self-employment",
"businessId": "XAIS12345678910",
"accountingPeriod": {
"startDate": "2018-10-11",
"endDate": "2019-10-10"
},
"bsasEntries": [
{
"bsasId": "76350054-0f11-4024-a811-99bcf5ced792",
"requestedDateTime": "2019-10-14T11:33:27.000Z",
"summaryStatus": "valid",
"adjustedSummary": false,
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/self-employment/76350054-0f11-4024-a811-99bcf5ced792",
"rel": "self",
"method": "GET"
}
]
},
{
"bsasId": "ef1a6fd7-3faa-4323-9a9d-fe5cc8ed1c43",
"requestedDateTime": "2019-10-10T09:01:35.000Z",
"summaryStatus": "superseded",
"adjustedSummary": true,
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/self-employment/ef1a6fd7-3faa-4323-9a9d-fe5cc8ed1c43",
"rel": "self",
"method": "GET"
}
]
}
]
},
{
"typeOfBusiness": "uk-property-fhl",
"accountingPeriod": {
"startDate": "2019-04-06",
"endDate": "2020-04-05"
},
"bsasEntries": [
{
"bsasId": "56f0a4fe-cfa7-4a21-8aa8-6c8f4642b792",
"requestedDateTime": "2020-05-14T12:17:15.000Z",
"summaryStatus": "valid",
"adjustedSummary": false,
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/property/56f0a4fe-cfa7-4a21-8aa8-6c8f4642b792",
"rel": "self",
"method": "GET"
}
]
},
{
"bsasId": "7f1fd081-3f59-4fd6-9b1c-c90521e0f7a8",
"requestedDateTime": "2020-04-10T13:03:17.000Z",
"summaryStatus": "superseded",
"adjustedSummary": true,
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/property/7f1fd081-3f59-4fd6-9b1c-c90521e0f7a8",
"rel": "self",
"method": "GET"
}
]
}
]
},
{
"typeOfBusiness": "foreign-property",
"businessId": "XAIS12345678912",
"accountingPeriod": {
"startDate": "2021-04-06",
"endDate": "2022-04-05"
},
"bsasEntries": [
{
"bsasId": "16332284-c01b-4046-a055-6c00454467a2",
"requestedDateTime": "2022-05-14T12:17:15.000Z",
"summaryStatus": "valid",
"adjustedSummary": false,
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/16332284-c01b-4046-a055-6c00454467a2",
"rel": "self",
"method": "GET"
}
]
},
{
"bsasId": "7ef31d49-ce57-4622-94fc-f4248b72b2cd",
"requestedDateTime": "2020-04-10T13:03:17.000Z",
"summaryStatus": "superseded",
"adjustedSummary": true,
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/7ef31d49-ce57-4622-94fc-f4248b72b2cd",
"rel": "self",
"method": "GET"
}
]
}
]
}
],
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A/trigger",
"rel": "trigger-business-source-accounting-summary",
"method": "POST"
},
{
"href": "/individuals/self-assessment/adjustable-summary/AA123456A",
"rel": "self",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
businessSourceSummaries
array
required
|
The array holding Business Source Adjustable Summary (BSAS) entries, by Business Income Source. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: self-employment
uk-property-fhl
uk-property-non-fhl
foreign-property-fhl-eea
foreign-property
|
|
businessId
string
optional
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
|
accountingPeriod
object
required
|
The duration of the business income source operations to be included in the tax year submission. 2019-20 is the earliest tax year to which the accounting period can be assigned. |
|
startDate
string
required
|
The date the accounting period began.
For example: |
|
endDate
string
required
|
The date the accounting period finished. The accounting period must end in the tax year to which it is assigned. For MTD submissions 2019-20 is the earliest tax year in which an accounting period can end.
For example: |
|
bsasEntries
array
required
|
The array holding Business Source Adjustable Summary (BSAS) entries. |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
requestedDateTime
string
required
|
The date and time this summary calculation was originally requested, prior to any adjustments. |
|
summaryStatus
string
required
|
Whether the summary calculation with this ID is current, has been invalidated (by subsequent changes) or has been superseded by a more recent request for a summary calculation. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates whether the original summary calculation has had adjustments applied.
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
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
|
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
trigger-business-source-accounting-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
|
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 is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
|
The format of the supplied business ID is invalid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
|
The format of the supplied type of business is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_BUSINESS |
|
The specified tax year is not supported - 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 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 a successful response containing multiple income sources. |
SELF_EMPLOYMENT_SINGLE |
Simulates a successful response containing a single self-employment. |
SELF_EMPLOYMENT_MULTIPLE |
Simulates a successful response containing multiple self-employments. |
UK_PROPERTY_FHL |
Simulates a successful response containing a single uk-property-fhl. |
UK_PROPERTY_NON_FHL |
Simulates a successful response containing a single uk-property-non-fhl. |
UK_PROPERTY_MULTIPLE |
Simulates a successful response containing a mixture of uk-property-fhl and uk-property-non-fhl. |
FOREIGN_PROPERTY |
Simulates a successful response containing a single foreign-property. |
FOREIGN_PROPERTY_FHL_EEA |
Simulates a successful response containing a single foreign-property-fhl-eea. |
FOREIGN_PROPERTY_MULTIPLE |
Simulates a successful response containing a mixture of foreign-property and foreign-property-fhl-eea. |
NOT_FOUND |
Simulates a scenario where no data can be found. |
/individuals/self-assessment/adjustable-summary/{nino}/trigger
This endpoint allows a developer to generate an end of accounting period Business Source Adjustable Summary (BSAS) of the income and expenditure for a specified business for a given accounting period. A BSAS must be generated before accounting adjustments are to be entered. A National Insurance number is required.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{
"accountingPeriod": {
"startDate": "2018-05-01",
"endDate": "2019-04-30"
},
"typeOfBusiness": "self-employment",
"businessId": "X9IS98470026982"
}
{
"accountingPeriod": {
"startDate": "2018-05-01",
"endDate": "2019-04-30"
},
"typeOfBusiness": "uk-property-non-fhl",
"businessId": "X9IS98470026982"
}
{
"accountingPeriod": {
"startDate": "2018-05-01",
"endDate": "2019-04-30"
},
"typeOfBusiness": "foreign-property",
"businessId": "X9IS98470026982"
}
| Name | Description |
|---|---|
|
accountingPeriod
object
required
|
The duration of the business income source operations to be included in the tax year submission. 2019-20 is the earliest tax year to which the accounting period can be assigned. |
|
startDate
string
required
|
The date the accounting period began.
For example: |
|
endDate
string
required
|
The date the accounting period finished. The accounting period must end in the tax year to which it is assigned. For MTD submissions 2019-20 is the earliest tax year in which an accounting period can end.
For example: |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: self-employment
uk-property-fhl
uk-property-non-fhl
foreign-property-fhl-eea
foreign-property
|
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 201 (Created)
{
"id": "a5667b29-c442-4df0-8e78-7b724212e537",
"links":[
{
"href":"/individuals/self-assessment/adjustable-summary/AA123456A/self-employment/a5667b29-c442-4df0-8e78-7b724212e537",
"rel":"self",
"method":"GET"
}
]
}
{
"id": "b82049ef-c026-4fe7-9ffc-6fb7d2ca73d9",
"links":[
{
"href":"/individuals/self-assessment/adjustable-summary/AA123456A/property/b82049ef-c026-4fe7-9ffc-6fb7d2ca73d9",
"rel":"self",
"method":"GET"
}
]
}
{
"id": "c75f40a6-a3df-4429-a697-471eeec46435",
"links":[
{
"href":"/individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/c75f40a6-a3df-4429-a697-471eeec46435",
"rel":"self",
"method":"GET"
}
]
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the summary calculation.
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
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied accounting period start date is not valid. |
400 (Bad Request) |
FORMAT_START_DATE |
|
The format of the supplied accounting period end date is not valid. |
400 (Bad Request) |
FORMAT_END_DATE |
|
The format of the supplied type of business is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_BUSINESS |
|
The format of the supplied business ID is invalid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
|
The accounting period end date value is before the start date. |
400 (Bad Request) |
RULE_END_DATE_BEFORE_START_DATE |
|
The specified accounting period is not supported - the accounting period specified falls before the minimum tax year value. |
400 (Bad Request) |
RULE_ACCOUNTING_PERIOD_NOT_SUPPORTED |
|
The accounting period has not ended. |
403 (Forbidden) |
RULE_ACCOUNTING_PERIOD_NOT_ENDED |
|
One or more Periodic updates are missing for this accounting period. |
403 (Forbidden) |
RULE_PERIODIC_DATA_INCOMPLETE |
|
The supplied accounting period does not exist. |
403 (Forbidden) |
RULE_NO_ACCOUNTING_PERIOD |
|
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 successful response. |
NOT_FOUND |
Simulates a scenario where no data can be found. |
NO_ACCOUNTING_PERIOD |
Simulates a scenario where the supplied accounting period does not exist. |
PERIODIC_DATA_INCOMPLETE |
Simulates a scenario where one or more periodic updates are missing for this accounting period. |
Self-employment business
Self-employment business resources
/individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}
This endpoint allows a developer to request a specific Business Source Adjustable Summary (BSAS) using a unique identifier. By default, when it is available the adjusted summary is returned. A filter can be set to specify whether the original or the adjusted is returned.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Query parameters
| Name | Description |
|---|---|
|
adjustedStatus
boolean
optional
|
To specify if the original (unadjusted) summary or adjusted summary is returned. If not specified the adjusted summary will be returned where it exists, otherwise the original summary is returned.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"metadata": {
"typeOfBusiness": "self-employment",
"businessId": "X9IS98470026982",
"accountingPeriod": {
"startDate": "2018-10-11",
"endDate": "2019-10-10"
},
"taxYear": "2019-20",
"requestedDateTime": "2019-10-14T11:33:27Z",
"bsasId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"summaryStatus": "superseded",
"adjustedSummary": true
},
"bsas": {
"total": {
"income": 100.49,
"expenses": 100.49,
"additions": 100.49,
"deductions": 100.49
},
"accountingAdjustments": -100.49,
"profit": {
"net": 100.49,
"taxable": 149
},
"loss": {
"net": 100.49,
"adjustedIncomeTax": 149
},
"incomeBreakdown": {
"turnover": 100.49,
"other": 100.49
},
"expensesBreakdown": {
"costOfGoodsBought": 100.49,
"cisPaymentsToSubcontractors": 100.49,
"staffCosts": 100.49,
"travelCosts": 100.49,
"premisesRunningCosts": 100.49,
"maintenanceCosts": 100.49,
"adminCosts": 100.49,
"advertisingCosts": 100.49,
"businessEntertainmentCosts": 100.49,
"interest": 100.49,
"financialCharges": 100.49,
"badDebt": 100.49,
"professionalFees": 100.49,
"depreciation": 100.49,
"other": 100.49
},
"additionsBreakdown": {
"costOfGoodsBoughtDisallowable": 100.49,
"cisPaymentsToSubcontractorsDisallowable": 100.49,
"staffCostsDisallowable": 100.49,
"travelCostsDisallowable": 100.49,
"premisesRunningCostsDisallowable": 100.49,
"maintenanceCostsDisallowable": 100.49,
"adminCostsDisallowable": 100.49,
"advertisingCostsDisallowable": 100.49,
"businessEntertainmentCostsDisallowable": 100.49,
"interestDisallowable": 100.49,
"financialChargesDisallowable": 100.49,
"badDebtDisallowable": 100.49,
"professionalFeesDisallowable": 100.49,
"depreciationDisallowable": 100.49,
"otherDisallowable": 100.49
}
},
"links": [
{
"href":"/individuals/self-assessment/adjustable-summary/self-employment/c75f40a6-a3df-4429-a697-471eeec46435",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/self-employment/c75f40a6-a3df-4429-a697-471eeec46435/adjust",
"rel":"submit-accounting-adjustments",
"method":"POST"
}
]
}
| Name | Description |
|---|---|
|
metadata
object
required
|
Object containing the identifying data for the business and associated information for the BSAS with this ID. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: self-employment
|
|
accountingPeriod
object
required
|
An object containing the accounting period start and end dates. |
|
startDate
string
required
|
The date the accounting period started.
For example: |
|
endDate
string
required
|
The date the accounting period ended.
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 into which this accounting period falls.
For example: |
|
requestedDateTime
string
required
|
The original date and time of the summary calculation before any adjustments.
Must conform to the regular expression
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
summaryStatus
string
required
|
The status of the calculated summary. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates if summary includes adjusted values.
For example: |
|
bsas
object
optional
|
Object holding the BSAS for the self-employment business income source. |
|
total
object
optional
|
Object of total values. |
|
income
number
optional
|
The total income for the income source. The value must be between 0 and 99999999999.99.
For example: |
|
expenses
number
optional
|
The total expenses for the income source. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
additions
number
optional
|
The total additions to net profit (or deduction to net loss). The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
deductions
number
optional
|
The total deductions to net loss (or addition to net profit). The value must be between 0 and 99999999999.99.
For example: |
|
accountingAdjustments
number
optional
|
Adjustment for change of accounting practice. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
profit
object
optional
|
An object of profit values. |
|
net
number
optional
|
The net profit of income source. The value must be between 0 and 99999999999.99.
For example: |
|
taxable
number
optional
|
The taxable net profit of the income source. The value must be between 0 and 99999999999. No decimals.
For example: |
|
loss
object
optional
|
An object of loss values. |
|
net
number
optional
|
The net loss of income source. The value must be between 0 and 99999999999.99.
For example: |
|
adjustedIncomeTax
number
optional
|
The adjusted income tax loss. The value must be between 0 and 99999999999. No decimals.
For example: |
|
incomeBreakdown
object
optional
|
Total income broken down by type for the accounting period. |
|
turnover
number
optional
|
The takings, fees, sales or money earned by the business. Income associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
other
number
optional
|
Any other business income not included in the turnover. Income associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
expensesBreakdown
object
optional
|
Total expenses broken down by type for the accounting period. |
|
costOfGoodsBought
number
optional
|
Cost of goods bought for resale or goods used. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
cisPaymentsToSubcontractors
number
optional
|
Payments to subcontractors - Construction Industry Scheme (CIS). Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
staffCosts
number
optional
|
Wages, salaries and other staff costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
travelCosts
number
optional
|
Car, van and travel expenses. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
premisesRunningCosts
number
optional
|
Rent, rates, power and insurance costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
maintenanceCosts
number
optional
|
Repairs and renewals of property and equipment. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
adminCosts
number
optional
|
Phone, fax, stationery and other office costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
advertisingCosts
number
optional
|
Advertising costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
businessEntertainmentCosts
number
optional
|
Business entertainment costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
interest
number
optional
|
Interest on bank and other loans. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
financialCharges
number
optional
|
Bank, credit card and other financial charges. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
badDebt
number
optional
|
Irrecoverable debts written off. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
professionalFees
number
optional
|
Accountancy, legal and other professional fees. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
depreciation
number
optional
|
Depreciation and loss or profit on sales of assets. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
other
number
optional
|
Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.
For example: |
|
additionsBreakdown
object
optional
|
A breakdown of the adjustable additions for the accounting period. |
|
costOfGoodsBoughtDisallowable
number
optional
|
Cost of goods bought for resale or goods used. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
cisPaymentsToSubcontractorsDisallowable
number
optional
|
Payments to subcontractors - Construction Industry Scheme (CIS). Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
staffCostsDisallowable
number
optional
|
Wages, salaries and other staff costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
travelCostsDisallowable
number
optional
|
Car, van and travel expenses. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
premisesRunningCostsDisallowable
number
optional
|
Rent, rates, power and insurance costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
maintenanceCostsDisallowable
number
optional
|
Repairs and renewals of property and equipment. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
adminCostsDisallowable
number
optional
|
Phone, fax, stationery and other office costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
advertisingCostsDisallowable
number
optional
|
Advertising costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
businessEntertainmentCostsDisallowable
number
optional
|
Business entertainment costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
interestDisallowable
number
optional
|
Interest on bank and other loans. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
financialChargesDisallowable
number
optional
|
Bank, credit card and other financial charges. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
badDebtDisallowable
number
optional
|
Irrecoverable debts written off. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
professionalFeesDisallowable
number
optional
|
Accountancy, legal and other professional fees. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
depreciationDisallowable
number
optional
|
Depreciation and loss/profit on sales of assets. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
otherDisallowable
number
optional
|
Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
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 the retrieval of the same resource. Limited to the following possible values: self
submit-accounting-adjustments
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
|
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 BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
The format of the supplied adjusted status field is not valid. |
400 (Bad Request) |
FORMAT_ADJUSTED_STATUS |
|
The BSAS ID supplied does not relate to a self-employment business. |
403 (Forbidden) |
RULE_NOT_SELF_EMPLOYMENT |
|
An adjusted calculation does not exist. |
403 (Forbidden) |
RULE_NO_ADJUSTMENTS_MADE |
|
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 |
|
A calculation with this BSAS ID cannot 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 was found. |
SELF_EMPLOYMENT_ADJUSTED |
Simulates a response containing an adjusted self-employment summary. |
SELF_EMPLOYMENT_UNADJUSTED |
Simulates a response containing an unadjusted self-employment summary. |
SELF_EMPLOYMENT_CONSOLIDATED |
Simulates a response containing an adjusted self-employment summary with consolidated expenses. |
NOT_SELF_EMPLOYMENT |
Simulates an unsuccessful response where a property BSAS ID was requested. |
/individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}/adjust
This endpoint allows a developer to request the adjustments made to a specific self-employment Business Source Adjustable Summary (BSAS) by using its identifier. The BSAS ID quoted must be for a self-employment business that has been previously adjusted.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"metadata": {
"typeOfBusiness": "self-employment",
"businessId": "XAIS00000000210",
"accountingPeriod": {
"startDate": "2020-10-11",
"endDate": "2021-10-10"
},
"taxYear": "2020-21",
"requestedDateTime": "2020-10-14T11:33:27Z",
"bsasId": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"summaryStatus": "superseded",
"adjustedSummary": true
},
"adjustments": {
"income": {
"turnover": 100.49,
"other": 100.49
},
"expenses": {
"costOfGoodsBought": 100.49,
"cisPaymentsToSubcontractors": 100.49,
"staffCosts": 100.49,
"travelCosts": 100.49,
"premisesRunningCosts": 100.49,
"maintenanceCosts": 100.49,
"adminCosts": 100.49,
"advertisingCosts": 100.49,
"businessEntertainmentCosts": 100.49,
"interest": 100.49,
"financialCharges": 100.49,
"badDebt": 100.49,
"professionalFees": 100.49,
"depreciation": 100.49,
"other": 100.49
},
"additions": {
"costOfGoodsBoughtDisallowable": 100.49,
"cisPaymentsToSubcontractorsDisallowable": 100.49,
"staffCostsDisallowable": 100.49,
"travelCostsDisallowable": 100.49,
"premisesRunningCostsDisallowable": 100.49,
"maintenanceCostsDisallowable": 100.49,
"adminCostsDisallowable": 100.49,
"advertisingCostsDisallowable": 100.49,
"businessEntertainmentCostsDisallowable": 100.49,
"interestDisallowable": 100.49,
"financialChargesDisallowable": 100.49,
"badDebtDisallowable": 100.49,
"professionalFeesDisallowable": 100.49,
"depreciationDisallowable": 100.49,
"otherDisallowable": 100.49
}
},
"links":[
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/self-employment/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/self-employment/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "retrieve-adjustable-summary",
"method": "GET"
}
]
}
{
"metadata": {
"typeOfBusiness": "self-employment",
"businessId": "XAIS00000000210",
"accountingPeriod": {
"startDate": "2020-10-11",
"endDate": "2021-10-10"
},
"taxYear": "2020-21",
"requestedDateTime": "2020-10-14T11:33:27Z",
"bsasId": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"summaryStatus": "superseded",
"adjustedSummary": true
},
"adjustments": {
"income": {
"turnover": 100.49,
"other": 100.49
},
"expenses": {
"consolidatedExpenses": 100.49
}
},
"links":[
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/self-employment/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4/adjust",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/self-employment/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "retrieve-adjustable-summary",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
metadata
object
required
|
Object containing the identifying data for the business and associated information for the BSAS with this ID. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: self-employment
|
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
|
accountingPeriod
object
required
|
An object containing the accounting period start and end dates. |
|
startDate
string
required
|
The date the accounting period started.
For example: |
|
endDate
string
required
|
The date the accounting period ended.
For example: |
|
taxYear
string
required
|
The tax year into which this accounting period falls.
For example: |
|
requestedDateTime
string
required
|
The original date and time of the summary calculation before any adjustments.
Must conform to the regular expression
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
summaryStatus
string
required
|
The status of the calculated summary. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates if summary includes adjusted values.
For example: |
|
adjustments
object
required
|
Object containing the adjustments made. |
|
income
object
optional
|
An object containing the adjustments to the income values. |
|
turnover
number
optional
|
The adjustment to takings, fees, sales or money earned by your business. Income associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to any other business income not included in the turnover. Income associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the expenses values. |
|
costOfGoodsBought
number
optional
|
The adjustment to the cost of goods bought for resale or goods used. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
cisPaymentsToSubcontractors
number
optional
|
The adjustment to payments to subcontractors - Construction Industry Scheme (CIS). Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
staffCosts
number
optional
|
The adjustment to wages, salaries and other staff costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel expenses. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, power and insurance costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
maintenanceCosts
number
optional
|
The adjustment to repairs and renewals of property and equipment. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
adminCosts
number
optional
|
The adjustment to phone, fax, stationery and other office costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
advertisingCosts
number
optional
|
The adjustment to advertising costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
businessEntertainmentCosts
number
optional
|
The adjustment to business entertainment costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
interest
number
optional
|
The adjustment to interest on bank and other loans. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCharges
number
optional
|
The adjustment to bank, credit card and other financial charges. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
badDebt
number
optional
|
The adjustment to irrecoverable debts written off. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to accountancy, legal and other professional fees. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
depreciation
number
optional
|
The adjustment to depreciation and loss or profit on sales of assets. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to other expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
additions
object
optional
|
A breakdown of the adjustable additions for the accounting period. |
|
costOfGoodsBoughtDisallowable
number
optional
|
The adjustment to cost of goods bought for resale or goods used. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
cisPaymentsToSubcontractorsDisallowable
number
optional
|
The adjustment to payments to subcontractors - Construction Industry Scheme (CIS). Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
staffCostsDisallowable
number
optional
|
The adjustment to wages, salaries and other staff costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCostsDisallowable
number
optional
|
The adjustment to car, van and travel expenses. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premisesRunningCostsDisallowable
number
optional
|
The adjustment to rent, rates, power and insurance costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
maintenanceCostsDisallowable
number
optional
|
The adjustment to repairs and renewals of property and equipment. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
adminCostsDisallowable
number
optional
|
The adjustment to phone, fax, stationery and other office costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
advertisingCostsDisallowable
number
optional
|
The adjustment to advertising costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
businessEntertainmentCostsDisallowable
number
optional
|
The adjustment to business entertainment costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
interestDisallowable
number
optional
|
The adjustment to interest on bank and other loans. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialChargesDisallowable
number
optional
|
The adjustment to bank, credit card and other financial charges. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
badDebtDisallowable
number
optional
|
The adjustment to irrecoverable debts written off. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFeesDisallowable
number
optional
|
The adjustment to accountancy, legal and other professional fees. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
depreciationDisallowable
number
optional
|
The adjustment to depreciation and loss or profit on sales of assets. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
otherDisallowable
number
optional
|
The adjustment to any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
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
retrieve-adjustable-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
The BSAS ID supplied does not relate to a self-employment business. |
403 (Forbidden) |
RULE_NOT_SELF_EMPLOYMENT |
|
An adjusted calculation does not exist. |
403 (Forbidden) |
RULE_NO_ADJUSTMENTS_MADE |
|
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 |
|
A calculation with this BSAS ID cannot 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 was found. |
SELF_EMPLOYMENT_ADJUSTED |
Simulates a successful response where adjustments are present for a self-employment. |
SELF_EMPLOYMENT_CONSOLIDATED |
Simulates a successful response where adjustments are present for a consolidated self-employment. |
SELF_EMPLOYMENT_UNADJUSTED |
Simulates an unsuccessful response where adjustments are not present for a self-employment. |
NOT_SELF_EMPLOYMENT |
Simulates an unsuccessful response where returned adjustments do not belong to a self-employment. |
This endpoint allows a developer to provide accounting adjustments against a specified Business Source Adjustable Summary (BSAS) using its unique identifier. The BSAS ID used must be for a self-employment business that has not been previously adjusted.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{
"income": {
"turnover": 1000.49,
"other": 1000.49
},
"expenses": {
"costOfGoodsBought": -1000.49,
"cisPaymentsToSubcontractors": 1000.49,
"staffCosts": 1000.49,
"travelCosts": 1000.49,
"premisesRunningCosts": 1000.49,
"maintenanceCosts": -1000.49,
"adminCosts": 1000.49,
"advertisingCosts": 1000.49,
"businessEntertainmentCosts": 1000.49,
"interest": 1000.49,
"financialCharges": 1000.49,
"badDebt": 1000.49,
"professionalFees": 1000.49,
"depreciation": 1000.49,
"other": 1000.49
},
"additions": {
"costOfGoodsBoughtDisallowable": 1000.49,
"cisPaymentsToSubcontractorsDisallowable": 1000.49,
"staffCostsDisallowable": 1000.49,
"travelCostsDisallowable": 1000.49,
"premisesRunningCostsDisallowable": 1000.49,
"maintenanceCostsDisallowable": 1000.49,
"adminCostsDisallowable": -1000.49,
"advertisingCostsDisallowable": -1000.49,
"businessEntertainmentCostsDisallowable": 1000.49,
"interestDisallowable": 1000.49,
"financialChargesDisallowable": 1000.49,
"badDebtDisallowable": 1000.49,
"professionalFeesDisallowable": 1000.49,
"depreciationDisallowable": 1000.49,
"otherDisallowable": 1000.49
}
}
{
"income": {
"turnover": 1000.49,
"other": 1000.49
},
"expenses": {
"consolidatedExpenses": -1000.49
}
}
| Name | Description |
|---|---|
|
income
object
optional
|
An object containing the adjustments to the income values. |
|
turnover
number
optional
|
The adjustment to takings, fees, sales or money earned by your business. Income associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to any other business income not included in the turnover. Income associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the expenses values. |
|
costOfGoodsBought
number
optional
|
The adjustment to the cost of goods bought for resale or goods used. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
cisPaymentsToSubcontractors
number
optional
|
The adjustment to payments to subcontractors - Construction Industry Scheme (CIS). Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
staffCosts
number
optional
|
The adjustment to wages, salaries and other staff costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel expenses. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, power and insurance costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
maintenanceCosts
number
optional
|
The adjustment to repairs and renewals of property and equipment. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
adminCosts
number
optional
|
The adjustment to phone, fax, stationery and other office costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
advertisingCosts
number
optional
|
The adjustment to advertising costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
businessEntertainmentCosts
number
optional
|
The adjustment to business entertainment costs. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
interest
number
optional
|
The adjustment to interest on bank and other loans. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCharges
number
optional
|
The adjustment to bank, credit card and other financial charges. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
badDebt
number
optional
|
The adjustment to irrecoverable debts written off. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to accountancy, legal and other professional fees. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
depreciation
number
optional
|
The adjustment to depreciation and loss or profit on sales of assets. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to other expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
additions
object
optional
|
A breakdown of the adjustable additions for the accounting period. |
|
costOfGoodsBoughtDisallowable
number
optional
|
The adjustment to cost of goods bought for resale or goods used. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
cisPaymentsToSubcontractorsDisallowable
number
optional
|
The adjustment to payments to subcontractors - Construction Industry Scheme (CIS). Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
staffCostsDisallowable
number
optional
|
The adjustment to wages, salaries and other staff costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCostsDisallowable
number
optional
|
The adjustment to car, van and travel expenses. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premisesRunningCostsDisallowable
number
optional
|
The adjustment to rent, rates, power and insurance costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
maintenanceCostsDisallowable
number
optional
|
The adjustment to repairs and renewals of property and equipment. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
adminCostsDisallowable
number
optional
|
The adjustment to phone, fax, stationery and other office costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
advertisingCostsDisallowable
number
optional
|
The adjustment to advertising costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
businessEntertainmentCostsDisallowable
number
optional
|
The adjustment to business entertainment costs. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
interestDisallowable
number
optional
|
The adjustment to interest on bank and other loans. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialChargesDisallowable
number
optional
|
The adjustment to bank, credit card and other financial charges. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
badDebtDisallowable
number
optional
|
The adjustment to irrecoverable debts written off. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFeesDisallowable
number
optional
|
The adjustment to accountancy, legal and other professional fees. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
depreciationDisallowable
number
optional
|
The adjustment to depreciation and loss or profit on sales of assets. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
otherDisallowable
number
optional
|
The adjustment to any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"id": "c75f40a6-a3df-4429-a697-471eeec46435",
"links":[
{
"href":"/individuals/self-assessment/adjustable-summary/TC663795B/self-employment/c75f40a6-a3df-4429-a697-471eeec46435/adjust",
"rel":"self",
"method":"GET"
}
]
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the summary calculation.
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 the retrieval of the same resource. Limited to the following possible values: self
retrieve-adjustable-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
One or more values has been added with the incorrect format. |
400 (Bad Request) |
FORMAT_ADJUSTMENT_VALUE |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
|
One or more values has been added that is outside the accepted value range. |
400 (Bad Request) |
RULE_RANGE_INVALID |
|
Consolidated expenses adjusted with other unexpected fields. |
400 (Bad Request) |
RULE_BOTH_EXPENSES_SUPPLIED |
|
The BSAS ID supplied does not relate to a self-employment business. |
403 (Forbidden) |
RULE_NOT_SELF_EMPLOYMENT |
|
The ‘summaryStatus’ of the summary with this BSAS ID is set to 'invalid'. |
403 (Forbidden) |
RULE_SUMMARY_STATUS_INVALID |
|
A newer BSAS exists for this accounting period. |
403 (Forbidden) |
RULE_SUMMARY_STATUS_SUPERSEDED |
|
Adjustments previously submitted against the supplied BSAS ID. |
403 (Forbidden) |
RULE_BSAS_ALREADY_ADJUSTED |
|
Adjustment to turnover exceeds consolidated expenses threshold. |
403 (Forbidden) |
RULE_OVER_CONSOLIDATED_EXPENSES_THRESHOLD |
|
Adjustment to expenses where Trading Income Allowance claimed. |
403 (Forbidden) |
RULE_TRADING_INCOME_ALLOWANCE_CLAIMED |
|
One or more adjustments would result in a negative value that is not permitted. |
403 (Forbidden) |
RULE_RESULTING_VALUE_NOT_PERMITTED |
|
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 |
|
A calculation with this BSAS ID cannot 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 are only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates a successful response for a self-employment. |
NOT_SELF_EMPLOYMENT |
Simulates the error response where the BSAS ID is for an incorrect type of business. |
SUMMARY_STATUS_INVALID |
Simulates the error response where the summary is invalid and cannot be adjusted. |
SUMMARY_STATUS_SUPERSEDED |
Simulates the error response where the summary is superseded and cannot be adjusted. |
BSAS_ALREADY_ADJUSTED |
Simulates the error response where the summary has already been adjusted. |
SELF_EMPLOYMENT_OVER_CONSOLIDATED_EXPENSES_THRESHOLD |
Simulates the error response where the cumulative turnover amount exceeds the consolidated expenses threshold. |
RULE_TRADING_INCOME_ALLOWANCE_CLAIMED |
Simulates the error response where a claim for trading income allowance was made - cannot also have expenses. |
RESULTING_VALUE_NOT_PERMITTED |
Simulates the error response that may occur if one or more adjustments submitted would result in a negative value. |
NOT_FOUND |
Simulates the scenario where no data was found. |
UK property business
UK property business resources
/individuals/self-assessment/adjustable-summary/{nino}/property/{bsasId}
This endpoint allows a developer to request a specific Business Source Adjustable Summary (BSAS) using a unique identifier. By default, when it is available the adjusted summary will be returned. A filter can be set to specify whether the original or the adjusted summary is returned.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Query parameters
| Name | Description |
|---|---|
|
adjustedStatus
boolean
optional
|
To specify if the original (unadjusted) summary or adjusted summary is returned. If not specified the adjusted summary will be returned where it exists, otherwise the original summary is returned.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"metadata": {
"typeOfBusiness": "uk-property-non-fhl",
"businessId": "XAIS123456789012",
"accountingPeriod": {
"startDate": "2019-04-06",
"endDate": "2020-04-05"
},
"taxYear": "2019-20",
"requestedDateTime": "2020-10-14T11:33:27Z",
"bsasId": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"summaryStatus": "valid",
"adjustedSummary": true
},
"bsas": {
"total": {
"income": 100.49,
"expenses": 100.49,
"additions": 100.49,
"deductions": 100.49
},
"profit": {
"net": 100.49,
"taxable": 149
},
"loss": {
"net": 100.49,
"adjustedIncomeTax": 149
},
"incomeBreakdown": {
"rentIncome": 100.49,
"premiumsOfLeaseGrant": 100.49,
"reversePremiums": 100.49,
"otherPropertyIncome":100.49,
"rarRentReceived":100.49
},
"expensesBreakdown": {
"premisesRunningCosts": 100.49,
"repairsAndMaintenance": 100.49,
"financialCosts": 100.49,
"professionalFees": 100.49,
"travelCosts": 100.49,
"costOfServices": 100.49,
"residentialFinancialCost": 100.49,
"broughtFwdResidentialFinancialCost": 100.49,
"other": 100.49
}
},
"links": [
{
"href":"/individuals/self-assessment/adjustable-summary/property/c75f40a6-a3df-4429-a697-471eeec46435",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/property/c75f40a6-a3df-4429-a697-471eeec46435/adjust",
"rel":"submit-accounting-adjustments",
"method":"POST"
}
]
}
| Name | Description |
|---|---|
|
metadata
object
required
|
Object containing the identifying data for the business and associated information for the BSAS with this ID. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: uk-property-fhl
uk-property-non-fhl
|
|
businessId
string
required
|
The unique identifier for the business.
Must conform to the regular expression
For example: |
|
accountingPeriod
object
required
|
An object containing the accounting period start and end dates. |
|
startDate
string
required
|
The date the accounting period started.
For example: |
|
endDate
string
required
|
The date the accounting period ended.
For example: |
|
taxYear
string
required
|
The tax year into which this accounting period falls.
For example: |
|
requestedDateTime
string
required
|
The original date and time of the summary calculation before any adjustments.
Must conform to the regular expression
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
summaryStatus
string
required
|
The status of the calculated summary. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates if summary includes adjusted values.
For example: |
|
bsas
object
optional
|
Object holding the BSAS for either a UK property non-Furnished Holiday Let (non-FHL) or for a UK Property Furnished Holiday Let (FHL) business income source. |
|
total
object
optional
|
Object of total values. |
|
income
number
optional
|
The total income for the income source. The value must be between 0 and 99999999999.99.
For example: |
|
expenses
number
optional
|
The total expenses for the income source. The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
additions
number
optional
|
The total additions to net profit (or deduction to net loss). The value must be between -99999999999.99 and 99999999999.99.
For example: |
|
deductions
number
optional
|
The total deductions to net loss (or addition to net profit). The value must be between 0 and 99999999999.99.
For example: |
|
profit
object
optional
|
An object of profit values. |
|
net
number
optional
|
The net profit of income source. The value must be between 0 and 99999999999.99.
For example: |
|
taxable
number
optional
|
The taxable net profit of the income source. The value must be between 0 and 99999999999. No decimals.
For example: |
|
loss
object
optional
|
An object of loss values. |
|
net
number
optional
|
The net loss of income source. The value must be between 0 and 99999999999.99.
For example: |
|
adjustedIncomeTax
number
optional
|
The adjusted income tax loss. The value must be between 0 and 99999999999. No decimals.
For example: |
|
incomeBreakdown
object
optional
|
Total income broken down by type for the accounting period. |
|
rentIncome
number
optional
|
The total amount of property rental income. The value must be between 0 and 99999999999.99.
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.
For example: |
|
reversePremiums
number
optional
|
Reverse premiums and inducements. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 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 between 0 and 99999999999.99.
For example: |
|
rarRentReceived
number
optional
|
Rental income received under the Rent a Room scheme for the period. The value must be between 0 and 99999999999.99.
For example: |
|
expensesBreakdown
object
optional
|
Total expenses broken down by type for the accounting period. |
|
premisesRunningCosts
number
optional
|
Rent, rates, insurance, ground rents etc. The value must be between 0 and 99999999999.99.
For example: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99.
For example: |
|
financialCosts
number
optional
|
Loan interest and other financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
professionalFees
number
optional
|
Legal, management and other professional fees. The value must be between 0 and 99999999999.99.
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.
For example: |
|
costOfServices
number
optional
|
Cost of services provided, including wages. The value must be between 0 and 99999999999.99.
For example: |
|
residentialFinancialCost
number
optional
|
Captures residential financial cost that can be deductible from rental income (tax relief). The value must be between 0 and 99999999999.99.
For example: |
|
broughtFwdResidentialFinancialCost
number
optional
|
Amount of relief brought forward for restricted residential financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.
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
submit-accounting-adjustments
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
|
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 BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
The format of the supplied adjusted status field is not valid. |
400 (Bad Request) |
FORMAT_ADJUSTED_STATUS |
|
The BSAS ID supplied does not relate to a UK property business. |
403 (Forbidden) |
RULE_NOT_UK_PROPERTY |
|
An adjusted calculation does not exist. |
403 (Forbidden) |
RULE_NO_ADJUSTMENTS_MADE |
|
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 |
|
A calculation with this BSAS ID cannot 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 was found. |
UK_PROPERTY_FHL_ADJUSTED |
Simulates a response containing an adjusted FHL summary. |
UK_PROPERTY_FHL_UNADJUSTED |
Simulates a response containing an unadjusted FHL summary. |
UK_PROPERTY_FHL_CONSOLIDATED |
Simulates a response containing an adjusted FHL summary with consolidated expenses. |
UK_PROPERTY_NON_FHL_ADJUSTED |
Simulates a response containing an adjusted non-FHL summary. |
UK_PROPERTY_NON_FHL_UNADJUSTED |
Simulates a response containing an unadjusted non-FHL summary. |
UK_PROPERTY_NON_FHL_CONSOLIDATED |
Simulates a response containing an adjusted non-FHL summary with consolidated expenses. |
NOT_UK_PROPERTY |
Simulates an unsuccessful response where a non-property BSAS ID was requested. |
/individuals/self-assessment/adjustable-summary/{nino}/property/{bsasId}/adjust
This endpoint allows a developer to request the adjustments made to a specific UK property Business Source Adjustable Summary (BSAS) by using its identifier. The BSAS ID used must be for a UK property business that has been previously adjusted.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"metadata": {
"typeOfBusiness": "uk-property-non-fhl",
"businessId": "XAIS00000000210",
"accountingPeriod": {
"startDate": "2020-10-11",
"endDate": "2021-10-10"
},
"taxYear": "2020-21",
"requestedDateTime": "2020-10-14T11:33:27Z",
"bsasId": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"summaryStatus": "superseded",
"adjustedSummary": true
},
"adjustments": {
"incomes": {
"rentIncome": 100.49,
"premiumsOfLeaseGrant": 100.49,
"reversePremiums": 100.49,
"otherPropertyIncome": 100.49
},
"expenses": {
"premisesRunningCosts": 100.49,
"repairsAndMaintenance": 100.49,
"financialCosts": 100.49,
"professionalFees": 100.49,
"travelCosts": 100.49,
"costOfServices": 100.49,
"residentialFinancialCost": 100.49,
"other": 100.49
}
},
"links":[
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/property/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4/adjust",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/property/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "retrieve-adjustable-summary",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
metadata
object
optional
|
Object containing the identifying data for the business and associated information for the BSAS with this ID. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: uk-property-fhl
uk-property-non-fhl
|
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
|
accountingPeriod
object
required
|
An object containing the accounting period start and end dates. |
|
startDate
string
required
|
The date the accounting period started.
For example: |
|
endDate
string
required
|
The date the accounting period ended.
For example: |
|
taxYear
string
required
|
The tax year into which this accounting period falls.
For example: |
|
requestedDateTime
string
required
|
The original date and time of the summary calculation before any adjustments.
Must conform to the regular expression
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
summaryStatus
string
required
|
The status of the calculated summary. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates if summary includes adjusted values.
For example: |
|
adjustments
object
optional
|
Object containing the adjustments made to this calculation. |
|
incomes
object
optional
|
An object containing the adjustments to the income values. |
|
rentIncome
number
optional
|
The adjustment made to the total property rental income. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premiumsOfLeaseGrant
number
optional
|
The adjustment to 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.
For example: |
|
reversePremiums
number
optional
|
The adjustment to reverse premiums and inducements. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99.
For example: |
|
otherPropertyIncome
number
optional
|
The adjustment to other income from property such as income from rent charges and ground rents, letting others tip waste on your land or income for the use of a caravan or houseboat at a fixed location. The value must be between 0 and 99999999999.99.
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the expenses values. |
|
premisesRunningCosts
number
optional
|
The adjustment made to rent, rates, insurance, ground rents and others. The value must be between 0 and 99999999999.99.
For example: |
|
repairsAndMaintenance
number
optional
|
The adjustment made to property repairs and maintenance. The value must be between 0 and 99999999999.99.
For example: |
|
financialCosts
number
optional
|
The adjustment made to loan interest and other financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
professionalFees
number
optional
|
The adjustment made to professional fees such as legal and management. The value must be between 0 and 99999999999.99.
For example: |
|
travelCosts
number
optional
|
The adjustment made to car, van and travel costs incurred when running a property business. This value must be between 0 and 99999999999.99.
For example: |
|
costOfServices
number
optional
|
The adjustment made to the cost of services provided, including wages. The value must be between 0 and 99999999999.99.
For example: |
|
residentialFinancialCost
number
optional
|
The adjustment made to the residential financial cost that can be deductible from rental income (tax relief). The value must be between 0 and 99999999999.99.
For example: |
|
other
number
optional
|
The adjustment made to other allowable property expenses. The value must be between 0 and 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.
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
retrieve-adjustable-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
The BSAS ID supplied does not relate to a UK property business. |
403 (Forbidden) |
RULE_NOT_UK_PROPERTY |
|
An adjusted calculation does not exist. |
403 (Forbidden) |
RULE_NO_ADJUSTMENTS_MADE |
|
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 |
|
A calculation with this BSAS ID cannot 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 was found. |
UK_PROPERTY_FHL_ADJUSTED |
Simulates a response containing an adjusted FHL summary. |
UK_PROPERTY_FHL_UNADJUSTED |
Simulates a response containing an unadjusted FHL summary. |
UK_PROPERTY_FHL_CONSOLIDATED |
Simulates a response containing an adjusted FHL summary with consolidated expenses. |
UK_PROPERTY_NON_FHL_ADJUSTED |
Simulates a response containing an adjusted non-FHL summary. |
UK_PROPERTY_NON_FHL_UNADJUSTED |
Simulates a response containing an unadjusted non-FHL summary. |
UK_PROPERTY_NON_FHL_CONSOLIDATED |
Simulates a response containing an adjusted non-FHL summary with consolidated expenses. |
NOT_UK_PROPERTY |
Simulates an unsuccessful response where a non-property BSAS ID was requested. |
This endpoint allows a developer to provide accounting adjustments against a specified Business Source Adjustable Summary (BSAS) quoting its unique identifier. The BSAS ID quoted must be for a UK property business which has not been previously adjusted. Only data for one property business (either FHL or non-FHL) should be included in any submission.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{
"nonFurnishedHolidayLet": {
"income": {
"rentIncome": 1000.49,
"premiumsOfLeaseGrant": 1000.49,
"reversePremiums": 1000.49,
"otherPropertyIncome": 1000.49
},
"expenses": {
"premisesRunningCosts": -1000.49,
"repairsAndMaintenance": 1000.49,
"financialCosts": 1000.49,
"professionalFees": 1000.49,
"travelCosts": 1000.49,
"costOfServices": -1000.49,
"residentialFinancialCost": 1000.49,
"other": 1000.49
}
}
}
{
"nonFurnishedHolidayLet": {
"income": {
"rentIncome": 1000.49,
"premiumsOfLeaseGrant": 1000.49,
"reversePremiums": 1000.49,
"otherPropertyIncome": 1000.49
},
"expenses": {
"consolidatedExpenses": 1000.49,
"residentialFinancialCost": 1000.49
}
}
}
{
"furnishedHolidayLet": {
"income": {
"rentIncome": 1000.49
},
"expenses": {
"premisesRunningCosts": -1000.49,
"repairsAndMaintenance": 1000.49,
"financialCosts": 1000.49,
"professionalFees": 1000.49,
"travelCosts": 1000.49,
"costOfServices": -1000.49,
"other": 1000.49
}
}
}
{
"furnishedHolidayLet": {
"income": {
"rentIncome": 1000.49
},
"expenses": {
"consolidatedExpenses": -1000.49
}
}
}
| Name | Description |
|---|---|
|
nonFurnishedHolidayLet
object
optional
|
Object holding non-FHL adjustments. |
|
income
object
optional
|
An object containing the adjustments to the income values. |
|
rentIncome
number
optional
|
The adjustment to total property rental income. The total amount of property rental income. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premiumsOfLeaseGrant
number
optional
|
The adjustment to premiums received for the grant of a lease and other lump sums to possess a property. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
reversePremiums
number
optional
|
The adjustment to reverse premiums and inducements. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
otherPropertyIncome
number
optional
|
The adjustment to 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 -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the expenses values. |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, insurance, ground rents etc. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
repairsAndMaintenance
number
optional
|
The adjustment to property repairs and maintenance. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCosts
number
optional
|
The adjustment to loan interest and other financial costs. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to legal, management and other professional fees. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel costs incurred in running a property business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
costOfServices
number
optional
|
The adjustment to cost of services provided, including wages. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
residentialFinancialCost
number
optional
|
The adjustment to the residential financial cost that can be deductible from rental income (tax relief). The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to other allowable property expenses. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
furnishedHolidayLet
object
optional
|
Object holding non-FHL adjustments. |
|
income
object
optional
|
An object containing the adjustments to the income values. |
|
rentIncome
number
optional
|
The adjustment to total property rental income. The total amount of property rental Income. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
expenses
object
optional
|
Total expenses broken down by type for the accounting period. |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, insurance, ground rents and others. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
repairsAndMaintenance
number
optional
|
The adjustment to property repairs and maintenance. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCosts
number
optional
|
The adjustment to loan interest and other financial costs. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to legal, management and other professional fees. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel costs incurred in running a property business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
costOfServices
number
optional
|
The adjustment to cost of services provided, including wages. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to other allowable property expenses. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"id": "c75f40a6-a3df-4429-a697-471eeec46435",
"links":[
{
"href":"/individuals/self-assessment/adjustable-summary/TC663795B/property/c75f40a6-a3df-4429-a697-471eeec46435/adjust",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/TC663795B/property/c75f40a6-a3df-4429-a697-471eeec46435?adjustedStatus=true",
"rel":"retrieve-adjustable-summary",
"method":"GET"
}
]
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the summary calculation.
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 the retrieval of the same resource. Limited to the following possible values: self
retrieve-adjustable-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
One or more values has been added with the incorrect format. |
400 (Bad Request) |
FORMAT_ADJUSTMENT_VALUE |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
|
One or more values has been added that is outside the accepted value range. |
400 (Bad Request) |
RULE_RANGE_INVALID |
|
Consolidated expenses adjusted with other unexpected fields. |
400 (Bad Request) |
RULE_BOTH_EXPENSES_SUPPLIED |
|
The BSAS ID relates to a different type of business. |
403 (Forbidden) |
RULE_TYPE_OF_BUSINESS_INCORRECT |
|
The ‘summaryStatus’ of the summary with this BSAS ID is set to 'invalid'. |
403 (Forbidden) |
RULE_SUMMARY_STATUS_INVALID |
|
A newer BSAS exists for this accounting period. |
403 (Forbidden) |
RULE_SUMMARY_STATUS_SUPERSEDED |
|
Adjustments previously submitted against the supplied BSAS ID. |
403 (Forbidden) |
RULE_BSAS_ALREADY_ADJUSTED |
|
Adjustment to turnover exceeds consolidated expenses threshold. |
403 (Forbidden) |
RULE_OVER_CONSOLIDATED_EXPENSES_THRESHOLD |
|
Adjustment to expenses where Property Income Allowance claimed. |
403 (Forbidden) |
RULE_PROPERTY_INCOME_ALLOWANCE_CLAIMED |
|
The BSAS ID used in the adjustment was for a self-employment business type, and an adjustment has been made. |
403 (Forbidden) |
RULE_SELF_EMPLOYMENT_ADJUSTED |
|
One or more adjustments would result in a negative value that is not permitted. |
403 (Forbidden) |
RULE_RESULTING_VALUE_NOT_PERMITTED |
|
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 |
|
A calculation with this BSAS ID cannot 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 successful response for submitting a UK Property. |
SUMMARY_STATUS_INVALID |
Simulates the error response where the summary is invalid and cannot be adjusted. |
SUMMARY_STATUS_SUPERSEDED |
Simulates the error response where the summary is superseded and cannot be adjusted. |
BSAS_ALREADY_ADJUSTED |
Simulates the error response where the summary has already been adjusted. |
PROPERTY_OVER_CONSOLIDATED_EXPENSES_THRESHOLD |
Simulates the error response where the cumulative turnover exceeds the threshold for consolidated expenses. |
PROPERTY_INCOME_ALLOWANCE_CLAIMED |
Simulates the error response where property income allowance has been claimed and therefore no further expenses can be claimed. |
PROPERTY_TYPE_OF_BUSINESS_INCORRECT |
Simulates the error response where either the fields submitted or the BSAS ID are incorrect for the type of business. |
RESULTING_VALUE_NOT_PERMITTED |
Simulates the error response that may occur if one of more adjustments submitted would result in a negative value. |
NOT_FOUND |
Simulates the scenario where no data was found. |
Foreign property business
Foreign property business resources
/individuals/self-assessment/adjustable-summary/{nino}/foreign-property/{bsasId}
This endpoint allows the developer to request a specific Business Source Adjustable Summary using a unique identifier. By default, when it is available the adjusted summary will be returned. A filter can be set to specify whether the original or the adjusted is to be returned. A National Insurance number and BSAS ID are required. The BSAS ID quoted must be for a Foreign Property Business.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Query parameters
| Name | Description |
|---|---|
|
adjustedStatus
boolean
optional
|
To specify if the original (unadjusted) summary or adjusted summary is returned. If not specified the adjusted summary will be returned where it exists, otherwise the original summary is returned.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"metadata": {
"typeOfBusiness": "foreign-property",
"accountingPeriod": {
"startDate": "2021-04-06",
"endDate": "2022-04-06"
},
"taxYear": "2021-22",
"requestedDateTime": "2022-10-14T11:33:27Z",
"bsasId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"summaryStatus": "valid",
"adjustedSummary": true
},
"bsas": {
"total": {
"income": 123.12,
"expenses": 123.12,
"additions": 123.12,
"deductions": 123.12
},
"profit": {
"net": 123.12,
"taxable": 123
},
"loss": {
"net": 123.12,
"adjustedIncomeTax": 123
},
"incomeBreakdown": {
"rentIncome": 123.12,
"premiumsOfLeaseGrant": 123.12,
"otherPropertyIncome": 123.12
},
"expensesBreakdown": {
"premisesRunningCosts": 123.12,
"repairsAndMaintenance": 123.12,
"financialCosts": 123.12,
"professionalFees": 123.12,
"travelCosts": 123.12,
"costOfServices": 123.12,
"residentialFinancialCost": 123.12,
"broughtFwdResidentialFinancialCost": 123.12,
"other": 123.12
},
"countryLevelDetail":[
{
"countryCode": "CYM",
"total": {
"income": 123.12,
"expenses": 123.12,
"additions": 123.12,
"deductions": 123.12
},
"incomeBreakdown": {
"rentIncome": 123.12,
"premiumsOfLeaseGrant": 123.12,
"otherPropertyIncome": 123.12,
"foreignTaxTakenOff": 123.12,
"specialWithholdingTaxOrUKTaxPaid": 123.12
},
"expensesBreakdown": {
"premisesRunningCosts": 123.12,
"repairsAndMaintenance": 123.12,
"financialCosts": 123.12,
"professionalFees": 123.12,
"travelCosts": 123.12,
"costOfServices": 123.12,
"residentialFinancialCost": 123.12,
"broughtFwdResidentialFinancialCost": 123.12,
"other": 123.12
}
}
]
},
"links": [
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/adjust",
"rel":"submit-summary-adjustments",
"method":"POST"
}
]
}
{
"metadata": {
"typeOfBusiness": "foreign-property-fhl-eea",
"accountingPeriod": {
"startDate": "2021-04-06",
"endDate": "2022-04-06"
},
"taxYear": "2021-22",
"requestedDateTime": "2022-10-14T11:33:27Z",
"bsasId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"summaryStatus": "valid",
"adjustedSummary": true
},
"bsas": {
"total": {
"income": 123.12,
"expenses": 123.12,
"additions": 123.12,
"deductions": 123.12
},
"profit": {
"net": 123.12,
"taxable": 123
},
"loss": {
"net": 123.12,
"adjustedIncomeTax": 123
},
"incomeBreakdown": {
"rentIncome": 123.12
},
"expensesBreakdown": {
"premisesRunningCosts": 123.12,
"repairsAndMaintenance": 123.12,
"financialCosts": 123.12,
"professionalFees": 123.12,
"travelCosts": 123.12,
"costOfServices": 123.12,
"other": 123.12
}
},
"links": [
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/adjust",
"rel":"submit-summary-adjustments",
"method":"POST"
}
]
}
{
"metadata": {
"typeOfBusiness": "foreign-property",
"accountingPeriod": {
"startDate": "2021-04-06",
"endDate": "2022-04-06"
},
"taxYear": "2021-22",
"requestedDateTime": "2022-10-14T11:33:27Z",
"bsasId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"summaryStatus": "valid",
"adjustedSummary": true
},
"bsas": {
"total": {
"income": 123.12,
"expenses": 123.12,
"additions": 123.12,
"deductions": 123.12
},
"profit": {
"net": 123.12,
"taxable": 123
},
"loss": {
"net": 123.12,
"adjustedIncomeTax": 123
},
"incomeBreakdown": {
"rentIncome": 123.12,
"premiumsOfLeaseGrant": 123.12,
"otherPropertyIncome": 123.12
},
"expensesBreakdown": {
"consolidatedExpenses": 123.12
},
"countryLevelDetail":[
{
"countryCode": "CYM",
"total": {
"income": 123.12,
"expenses": 123.12,
"additions": 123.12,
"deductions": 123.12
},
"incomeBreakdown": {
"rentIncome": 123.12,
"premiumsOfLeaseGrant": 123.12,
"otherPropertyIncome": 123.12,
"foreignTaxTakenOff": 123.12,
"specialWithholdingTaxOrUKTaxPaid": 123.12
},
"expensesBreakdown": {
"consolidatedExpenses": 123.12
}
}
]
},
"links": [
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/adjust",
"rel":"submit-summary-adjustments",
"method":"POST"
}
]
}
| Name | Description |
|---|---|
|
metadata
object
required
|
Object containing the identifying data for the business and associated information for the BSAS with this ID. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: foreign-property-fhl-eea
foreign-property
|
|
businessId
string
optional
|
The unique identifier for the business.
Must conform to the regular expression
For example: |
|
accountingPeriod
object
required
|
An object containing the accounting period start and end dates. |
|
startDate
string
required
|
The date the accounting period started.
For example: |
|
endDate
string
required
|
The date the accounting period ended.
For example: |
|
taxYear
string
required
|
The tax year into which this accounting period falls.
For example: |
|
requestedDateTime
string
required
|
The original date and time of the summary calculation before any adjustments.
Must conform to the regular expression
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
summaryStatus
string
required
|
The status of the calculated summary. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates if summary includes adjusted values.
For example: |
|
bsas
object
optional
|
Object holding the BSAS for either Foreign Property Furnished Holiday Let in the EEA business income source or for any other type Foreign Property. |
|
total
object
required
|
Object of total values. |
|
income
number
optional
|
The total income for the income source. The value must be between 0 and 99999999999.99.
For example: |
|
expenses
number
optional
|
The total expenses for the income source. The value must be between 0 and 99999999999.99.
For example: |
|
additions
number
optional
|
The total additions to net profit (or deduction to net loss). The value must be between 0 and 99999999999.99.
For example: |
|
deductions
number
optional
|
The total deductions to net loss (or addition to net profit). The value must be between 0 and 99999999999.99.
For example: |
|
profit
object
optional
|
An object of profit values. |
|
net
number
optional
|
The net profit of income source. The value must be between 0 and 99999999999.99.
For example: |
|
taxable
number
optional
|
The taxable net profit of the income source. The value must be between 0 and 99999999999.
For example: |
|
loss
object
optional
|
Object of loss values |
|
net
number
optional
|
The net loss of income source. The value must be between 0 and 99999999999.99.
For example: |
|
adjustedIncomeTax
number
optional
|
The adjusted income tax loss. The value must be between 0 and 99999999999.
For example: |
|
incomeBreakdown
object
optional
|
Total income broken down by type for the tax year to date |
|
rentIncome
number
optional
|
The total amount of property rental Income. The value must be between 0 and 99999999999.99.
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.
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.
For example: |
|
expensesBreakdown
object
optional
|
Total expenses broken down by type for the tax year to date. |
|
premisesRunningCosts
number
optional
|
Rent, rates, insurance, ground rents etc. The value must be between 0 and 99999999999.99.
For example: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99.
For example: |
|
financialCosts
number
optional
|
Loan interest and other financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
professionalFees
number
optional
|
Legal, management and other professional fees. The value must be between 0 and 99999999999.99.
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.
For example: |
|
costOfServices
number
optional
|
Cost of services provided, including wages. The value must be between 0 and 99999999999.99.
For example: |
|
residentialFinancialCost
number
optional
|
Captures residential financial cost that can be deductible from rental income (tax relief). The value must be between 0 and 99999999999.99.
For example: |
|
broughtFwdResidentialFinancialCost
number
optional
|
Amount of relief brought forward for restricted residential financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.
For example: |
|
countryLevelDetail
array
optional
|
Object holding foreign property adjustments. |
|
countryCode
string
required
|
A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value.
For example: |
|
total
object
required
|
Object of total values |
|
income
number
optional
|
The total income for the income source. The value must be between 0 and 99999999999.99.
For example: |
|
expenses
number
optional
|
The total expenses for the income source. The value must be between 0 and 99999999999.99.
For example: |
|
additions
number
optional
|
The total additions to net profit (or deduction to net loss). The value must be between 0 and 99999999999.99.
For example: |
|
deductions
number
optional
|
The total deductions to net loss (or addition to net profit). The value must be between 0 and 99999999999.99.
For example: |
|
incomeBreakdown
object
optional
|
Total income broken down by type for the tax year to date. |
|
rentIncome
number
optional
|
The total amount of property rental Income. The value must be between 0 and 99999999999.99.
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.
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.
For example: |
|
expensesBreakdown
object
optional
|
Total expenses broken down by type for the tax year to date. |
|
premisesRunningCosts
number
optional
|
Rent, rates, insurance, ground rents etc. The value must be between 0 and 99999999999.99.
For example: |
|
repairsAndMaintenance
number
optional
|
Property repairs and maintenance. The value must be between 0 and 99999999999.99.
For example: |
|
financialCosts
number
optional
|
Loan interest and other financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
professionalFees
number
optional
|
Legal, management and other professional fees. The value must be between 0 and 99999999999.99.
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.
For example: |
|
costOfServices
number
optional
|
Cost of services provided, including wages. The value must be between 0 and 99999999999.99.
For example: |
|
residentialFinancialCost
number
optional
|
Captures residential financial cost that can be deductible from rental income (tax relief). The value must be between 0 and 99999999999.99.
For example: |
|
broughtFwdResidentialFinancialCost
number
optional
|
Amount of relief brought forward for restricted residential financial costs. The value must be between 0 and 99999999999.99.
For example: |
|
other
number
optional
|
Other allowable property expenses. The value must be between 0 and 99999999999.99.
For example: |
|
consolidatedExpenses
number
optional
|
Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.
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
submit-summary-adjustments
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: POST
GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
The format of the supplied adjusted status field is not valid. |
400 (Bad Request) |
FORMAT_ADJUSTED_STATUS |
|
The BSAS ID supplied does not relate to a foreign property business. |
403 (Forbidden) |
RULE_NOT_FOREIGN_PROPERTY |
|
An adjusted calculation does not exist. |
403 (Forbidden) |
RULE_NO_ADJUSTMENTS_MADE |
|
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 |
|
A calculation with this BSAS ID cannot 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 was found. |
FOREIGN_PROPERTY_FHL_EEA_ADJUSTED |
Simulates a response containing an adjusted FHL summary. |
FOREIGN_PROPERTY_FHL_EEA_UNADJUSTED |
Simulates a response containing an unadjusted FHL summary. |
FOREIGN_PROPERTY_FHL_EEA_CONSOLIDATED |
Simulates a response containing an adjusted FHL summary with consolidated expenses. |
FOREIGN_PROPERTY_ADJUSTED |
Simulates a response containing an adjusted non-FHL summary. |
FOREIGN_PROPERTY_UNADJUSTED |
Simulates a response containing an unadjusted non-FHL summary. |
FOREIGN_PROPERTY_CONSOLIDATED |
Simulates a response containing an adjusted non-FHL summary with consolidated expenses. |
NOT_FOREIGN_PROPERTY |
Simulates an unsuccessful response where a non-property BSAS ID was requested. |
/individuals/self-assessment/adjustable-summary/{nino}/foreign-property/{bsasId}/adjust
This endpoint allows the developer to request the adjustments made to a specific Foreign Property Business Source Adjustable Summary, by quoting its identifier. A National Insurance number and BSAS ID are required. The BSAS ID quoted must be for a Foreign Property Business and previously adjusted.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"metadata": {
"typeOfBusiness": "foreign-property",
"businessId": "XAIS12345678901",
"accountingPeriod": {
"startDate": "2020-10-11",
"endDate": "2021-10-10"
},
"taxYear": "2020-21",
"requestedDateTime": "2020-10-14T11:33:27Z",
"bsasId": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce5",
"summaryStatus": "valid",
"adjustedSummary": true
},
"adjustments": [
{
"countryCode": "CYM",
"incomes": {
"rentIncome": 100.49,
"premiumsOfLeaseGrant": 100.49,
"otherPropertyIncome": 100.49
},
"expenses": {
"premisesRunningCosts": 100.49,
"repairsAndMaintenance": 100.49,
"financialCosts": 100.49,
"professionalFees": 100.49,
"travelCosts": 100.49,
"costOfServices": 100.49,
"residentialFinancialCost": 100.49,
"other": 100.49
}
}
],
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/foreign-property/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/foreign-property/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "retrieve-adjustable-summary",
"method": "GET"
}
]
}
{
"metadata": {
"typeOfBusiness": "foreign-property-fhl-eea",
"businessId": "XAIS00000000210",
"accountingPeriod": {
"startDate": "2020-10-11",
"endDate": "2021-10-10"
},
"taxYear": "2020-21",
"requestedDateTime": "2020-10-14T11:33:27Z",
"bsasId": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce5",
"summaryStatus": "valid",
"adjustedSummary": true
},
"adjustments": [
{
"incomes": {
"rentIncome": 100.49
},
"expenses": {
"premisesRunningCosts": 100.49,
"repairsAndMaintenance": 100.49,
"financialCosts": 100.49,
"professionalFees": 100.49,
"travelCosts": 100.49,
"costOfServices": 100.49,
"other": 100.49,
"consolidatedExpenses": 100.49
}
}
],
"links": [
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/foreign-property/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/self-assessment/adjustable-summary/TC663795B/foreign-property/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"rel": "retrieve-adjustable-summary",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
metadata
object
required
|
Object containing the identifying data for the business and associated information for the BSAS with this ID. |
|
typeOfBusiness
string
required
|
The type of business the summary calculation is for. Limited to the following possible values: foreign-property-fhl-eea
foreign-property
|
|
businessId
string
required
|
The unique identifier for the business.
Must conform to the regular expression
For example: |
|
accountingPeriod
object
required
|
An object containing the accounting period start and end dates. |
|
startDate
string
required
|
The date the accounting period started.
For example: |
|
endDate
string
required
|
The date the accounting period ended.
For example: |
|
taxYear
string
required
|
The tax year into which this accounting period falls.
For example: |
|
requestedDateTime
string
required
|
The original date and time of the summary calculation before any adjustments.
Must conform to the regular expression
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
Must conform to the regular expression
For example: |
|
summaryStatus
string
required
|
The status of the calculated summary. Limited to the following possible values: valid
invalid
superseded
|
|
adjustedSummary
boolean
required
|
Indicates if summary includes adjusted values.
For example: |
|
adjustments
array
required
|
Array containing the adjustments made to this calculation. |
|
countryCode
string
optional
|
A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. This field is mandatory if the ‘typeOfBusiness’ is set to ‘foreign-property’ |
|
incomes
object
optional
|
An object containing the adjustments to the income values. |
|
rentIncome
number
optional
|
The adjustment to the total amount of property rental Income. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premiumsOfLeaseGrant
number
optional
|
The adjustment to premiums received for the grant of a lease and other lump sums to possess a property. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00). This field is not present if ‘typeOfBusiness’ is set to ‘foreign-property-fhl-eea’ otherwise it is optional.
For example: |
|
otherPropertyIncome
number
optional
|
The adjustment to 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 -99999999999.99 and 99999999999.99 (excluding 0 or 0.00). This field is not present if ‘typeOfBusiness’ is set to ‘foreign-property-fhl-eea’ otherwise it is optional.
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the expenses values. |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, insurance, ground rents etc. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
repairsAndMaintenance
number
optional
|
The adjustment to property repairs and maintenance. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCosts
number
optional
|
The adjustment to loan interest and other financial costs. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to legal, management and other professional fees. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel costs incurred in running a property business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
costOfServices
number
optional
|
The adjustment to the cost of services provided, including wages. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
residentialFinancialCost
number
optional
|
The adjustment to the residential financial cost that can be deductible from rental income (tax relief). The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00). This field is not present if ‘typeOfBusiness’ is set to ‘foreign-property-fhl-eea’ otherwise it is optional.
For example: |
|
other
number
optional
|
The adjustment to other allowable property expenses. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
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
retrieve-adjustable-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
The BSAS ID supplied does not relate to a foreign property business. |
403 (Forbidden) |
RULE_NOT_FOREIGN_PROPERTY |
|
An adjusted calculation does not exist. |
403 (Forbidden) |
RULE_NO_ADJUSTMENTS_MADE |
|
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 |
|
A calculation with this BSAS ID cannot 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 was found. |
FOREIGN_PROPERTY_FHL_EEA_ADJUSTED |
Simulates a response containing an adjusted FHL summary. |
FOREIGN_PROPERTY_FHL_EEA_UNADJUSTED |
Simulates a response containing an unadjusted FHL summary. |
FOREIGN_PROPERTY_FHL_EEA_CONSOLIDATED |
Simulates a response containing an adjusted FHL summary with consolidated expenses. |
FOREIGN_PROPERTY_ADJUSTED |
Simulates a response containing an adjusted non-FHL summary. |
FOREIGN_PROPERTY_UNADJUSTED |
Simulates a response containing an unadjusted non-FHL summary. |
FOREIGN_PROPERTY_CONSOLIDATED |
Simulates a response containing an adjusted non-FHL summary with consolidated expenses. |
NOT_FOREIGN_PROPERTY |
Simulates an unsuccessful response where a non-property BSAS ID was requested. |
This endpoint allows the developer to provide accounting adjustments against a specified Business Source Accounting Summary quoting its unique identifier. The BSAS ID quoted must be for a Foreign Property Business, and it must not have been adjusted, previously. Only data for one property business (either foreign-property-fhl-eea or foreign-property) should be included in any submission.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number in the format AA999999A.
For example: |
|
bsasId
string
required
|
The unique identifier of the summary calculation.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{
"foreignProperty": [
{
"countryCode": "FRA",
"income": {
"rentIncome": 123.12,
"premiumsOfLeaseGrant": 123.12,
"otherPropertyIncome": 123.12
},
"expenses": {
"consolidatedExpenses": 123.12
}
}
]
}
{
"foreignProperty": [
{
"countryCode": "FRA",
"income": {
"rentIncome": 123.12,
"premiumsOfLeaseGrant": 123.12,
"otherPropertyIncome": 123.12
},
"expenses": {
"premisesRunningCosts": 123.12,
"repairsAndMaintenance": 123.12,
"financialCosts": 123.12,
"professionalFees": 123.12,
"travelCosts": 123.12,
"costOfServices": 123.12,
"residentialFinancialCost": 123.12,
"other": 123.12
}
}
]
}
{
"foreignFhlEea": {
"income": {
"rentIncome": 123.12
},
"expenses": {
"consolidatedExpenses": 123.12
}
}
}
{
"foreignFhlEea": {
"income": {
"rentIncome": 123.12
},
"expenses": {
"premisesRunningCosts": 123.12,
"repairsAndMaintenance": 123.12,
"financialCosts": 123.12,
"professionalFees": 123.12,
"costOfServices": 123.12,
"travelCosts": 123.12,
"other": 123.12
}
}
}
| Name | Description |
|---|---|
|
foreignProperty
array
optional
|
Object holding foreign property adjustments. |
|
countryCode
string
required
|
A three-letter code that represents a country name. This must be an ISO 3166-1 Alpha-3 value. For example: FRA |
|
income
object
optional
|
An object containing the adjustments to the Income values. |
|
rentIncome
number
optional
|
The adjustment to premiums received for the grant of a lease and other lump sums to possess a property. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
premiumsOfLeaseGrant
number
optional
|
The adjustment to premiums received for the grant of a lease and other lump sums to possess a property. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
otherPropertyIncome
number
optional
|
The adjustment to 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 -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the Expenses values. |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, insurance, ground rents etc. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
repairsAndMaintenance
number
optional
|
The adjustment to property repairs and maintenance. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCosts
number
optional
|
The adjustment to loan interest and other financial costs. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to legal, management and other professional fees. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel costs incurred in running a property business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
costOfServices
number
optional
|
The adjustment to the cost of services provided, including wage. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
residentialFinancialCost
number
optional
|
The adjustment to the residential financial cost that can be deductible from rental income (tax relief). The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to other allowable property expenses. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
foreignFhlEea
object
optional
|
Object holding FHL adjustments. |
|
income
object
optional
|
An object containing the adjustments to the Income values. |
|
rentIncome
number
optional
|
The adjustment to total property rental income. Tax taken off any income. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
expenses
object
optional
|
An object containing the adjustments to the Expenses values. |
|
premisesRunningCosts
number
optional
|
The adjustment to rent, rates, insurance, ground rents etc. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
repairsAndMaintenance
number
optional
|
The adjustment to property repairs and maintenance. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
financialCosts
number
optional
|
The adjustment to loan interest and other financial costs. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
professionalFees
number
optional
|
The adjustment to legal, management and other professional fees. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
costOfServices
number
optional
|
The adjustment to the cost of services provided, including wage. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
travelCosts
number
optional
|
The adjustment to car, van and travel costs incurred in running a property business. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
other
number
optional
|
The adjustment to other allowable property expenses. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
|
consolidatedExpenses
number
optional
|
The adjustment to the sum of all expenses for the specified period. The value must be between -99999999999.99 and 99999999999.99 (excluding 0 or 0.00).
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"id": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
"links":[
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/adjust",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c?adjustedStatus=true",
"rel":"retrieve-adjustable-summary",
"method":"GET"
}
]
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the summary calculation.
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 the retrieval of the same resource. Limited to the following possible values: self
retrieve-adjustable-summary
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied BSAS ID is not valid. |
400 (Bad Request) |
FORMAT_BSAS_ID |
|
One or more values has been added with the incorrect format. |
400 (Bad Request) |
FORMAT_ADJUSTMENT_VALUE |
|
The format of the supplied Country code field is not valid. |
400 (Bad Request) |
FORMAT_COUNTRY_CODE |
|
Not a valid ISO 3166-1 alpha-3 country code. |
400 (Bad Request) |
RULE_COUNTRY_CODE |
|
One or more values has been added that is outside the accepted value range. |
400 (Bad Request) |
RULE_RANGE_INVALID |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
|
Consolidated expenses adjusted with other unexpected fields. |
400 (Bad Request) |
RULE_BOTH_EXPENSES_SUPPLIED |
|
The BSAS ID relates to a different type of business. |
403 (Forbidden) |
RULE_TYPE_OF_BUSINESS_INCORRECT |
|
The ‘summaryStatus’ of the summary with this BSAS ID is set to 'invalid'. |
403 (Forbidden) |
RULE_SUMMARY_STATUS_INVALID |
|
A newer BSAS exists for this accounting period. |
403 (Forbidden) |
RULE_SUMMARY_STATUS_SUPERSEDED |
|
A newer summary calculation exists for this accounting period. |
403 (Forbidden) |
RULE_BSAS_ALREADY_ADJUSTED |
|
One or more adjustments would result in a negative value that is not permitted. |
403 (Forbidden) |
RULE_RESULTING_VALUE_NOT_PERMITTED |
|
Adjustment to turnover exceeds consolidated expenses threshold. |
403 (Forbidden) |
RULE_OVER_CONSOLIDATED_EXPENSES_THRESHOLD |
|
Adjustment to expenses where Property Income Allowance claimed. |
403 (Forbidden) |
RULE_PROPERTY_INCOME_ALLOWANCE_CLAIMED |
|
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 |
|
Matching resource not 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 successful response for submitting a Foreign Property. |
SUMMARY_STATUS_INVALID |
Simulates the error response where the summary is invalid and cannot be adjusted. |
SUMMARY_STATUS_SUPERSEDED |
Simulates the error response where the summary is superseded and cannot be adjusted. |
BSAS_ALREADY_ADJUSTED |
Simulates the error response where the summary has already been adjusted. |
PROPERTY_OVER_CONSOLIDATED_EXPENSES_THRESHOLD |
Simulates the error response where the cumulative turnover exceeds the threshold for consolidated expenses. |
PROPERTY_INCOME_ALLOWANCE_CLAIMED |
Simulates the error response where property income allowance has been claimed and therefore no further expenses can be claimed. |
FOREIGN_PROPERTY_TYPE_OF_BUSINESS_INCORRECT |
Simulates the error response where either the fields submitted or the BSAS ID are incorrect for the type of business. |
RESULTING_VALUE_NOT_PERMITTED |
Simulates the error response that may occur if one of more adjustments submitted would result in a negative value. |
NOT_FOUND |
Simulates the scenario where no data was found. |