This version is in beta - expect some breaking changes.

Business Source Adjustable Summary (MTD) API

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

Overview

This API allows 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 income-tax-mtd-changelog GitHub wiki.

Support

Testing

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

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

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

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

Skip to main content

Endpoints

/individuals/self-assessment/adjustable-summary/{nino}

List Business Source Adjustable Summaries (BSAS)
GET

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: TC663795B

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: 2019-20

typeOfBusiness
string
optional

The type of business the summary calculation is for.

Limited to the following possible values:

  • self-employment
  • uk-property-non-fhl
  • uk-property-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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: X9IS98470026982

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

{
  "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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

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: 2019-04-06

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: 2020-04-05

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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}

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: /individuals/self-assessment/adjustable-summary/{nino}/trigger

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/trigger

Trigger a Business Source Adjustable Summary (BSAS)
POST

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: TC663795B

Request headers

Name Description
Accept
required

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

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

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Self-employment Trigger 

{
  "accountingPeriod": {
    "startDate": "2018-05-01",
    "endDate": "2019-04-30"
  },
  "typeOfBusiness": "self-employment",
  "businessId": "X9IS98470026982"
}

Scenario: UK Property Non-FHL Trigger 

{
  "accountingPeriod": {
    "startDate": "2018-05-01",
    "endDate": "2019-04-30"
  },
  "typeOfBusiness": "uk-property-non-fhl",
  "businessId": "X9IS98470026982"
}

Scenario: Foreign Property Trigger 

{
  "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: 2019-04-06

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: 2020-04-05

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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

Responses

HTTP status 201 (Created)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Self-employment example response 

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

UK Property example response 

{
  "id": "b82049ef-c026-4fe7-9ffc-6fb7d2ca73d9",
  "links":[
    {
      "href":"/individuals/self-assessment/adjustable-summary/AA123456A/property/b82049ef-c026-4fe7-9ffc-6fb7d2ca73d9",
      "rel":"self",
      "method":"GET"
    }
  ]
}

Foreign Property example response 

{
  "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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}

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.

Close Section

Self-employment business

Self-employment business resources

/individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}

Retrieve a Self-Employment Business Source Adjustable Summary (BSAS)
GET

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: true

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

{
  "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: 2019-04-06

endDate
string
required

The date the accounting period ended.

For example: 2020-04-05

businessId
string
required

An identifier for the business, unique to the customer.

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

For example: XAIS12345678910

taxYear
string
required

The tax year into which this accounting period falls.

For example: 2019-20

requestedDateTime
string
required

The original date and time of the summary calculation before any adjustments.

Must conform to the regular expression ^2[0-9]{3}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,3}|)Z$

For example: 2020-07-11T12:13:48.763Z

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

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: 1000.45

expenses
number
optional

The total expenses for the income source. The value must be between -99999999999.99 and 99999999999.99.

For example: 1000.45

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: 1000.45

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: 1000.45

accountingAdjustments
number
optional

Adjustment for change of accounting practice. The value must be between -99999999999.99 and 99999999999.99.

For example: 1000.45

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: 1000.45

taxable
number
optional

The taxable net profit of the income source. The value must be between 0 and 99999999999. No decimals.

For example: 1045

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: 1000.45

adjustedIncomeTax
number
optional

The adjusted income tax loss. The value must be between 0 and 99999999999. No decimals.

For example: 1045

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

advertisingCosts
number
optional

Advertising costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.

For example: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

other
number
optional

Expenses associated with the running of the business. The value must be between 0 and 99999999999.99.

For example: 1000.45

consolidatedExpenses
number
optional

Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.

For example: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: /sample-context/AA123456A

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}/adjust

Retrieve a Self-Employment Business' Summary Adjustments
GET

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Full Expenses 

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

Consolidated Expenses 

{
  "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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

accountingPeriod
object
required

An object containing the accounting period start and end dates.
startDate
string
required

The date the accounting period started.

For example: 2019-04-06

endDate
string
required

The date the accounting period ended.

For example: 2020-04-05

taxYear
string
required

The tax year into which this accounting period falls.

For example: 2019-20

requestedDateTime
string
required

The original date and time of the summary calculation before any adjustments.

Must conform to the regular expression ^2[0-9]{3}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,3}|)Z$

For example: 2020-07-11T12:13:48.763Z

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/AA123456A

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/self-employment/{bsasId}/adjust

Submit an Adjustment to a Self-Employment Business Summary
POST

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Name Description
Accept
required

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

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

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Full Expenses 

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

Scenario: Consolidated Expenses 

{
  "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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

{
  "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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/AA123456A

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.

Close Section

UK property business

UK property business resources

/individuals/self-assessment/adjustable-summary/{nino}/property/{bsasId}

Retrieve a UK Property Business Source Adjustable Summary (BSAS)
GET

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: true

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

{
  "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 ^X[a-zA-Z0-9]{1}IS[0-9]{12}$

For example: XAIS123456789012

accountingPeriod
object
required

An object containing the accounting period start and end dates.
startDate
string
required

The date the accounting period started.

For example: 2019-04-06

endDate
string
required

The date the accounting period ended.

For example: 2020-04-05

taxYear
string
required

The tax year into which this accounting period falls.

For example: 2019-20

requestedDateTime
string
required

The original date and time of the summary calculation before any adjustments.

Must conform to the regular expression ^2[0-9]{3}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,3}|)Z$

For example: 2020-07-11T12:13:48.763Z

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

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: 1000.45

expenses
number
optional

The total expenses for the income source. The value must be between -99999999999.99 and 99999999999.99.

For example: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

taxable
number
optional

The taxable net profit of the income source. The value must be between 0 and 99999999999. No decimals.

For example: 1045

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: 1000.45

adjustedIncomeTax
number
optional

The adjusted income tax loss. The value must be between 0 and 99999999999. No decimals.

For example: 1045

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99.

For example: 1000.45

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99.

For example: 1000.45

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99.

For example: 1000.45

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: 1000.45

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99.

For example: 1000.45

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: 1000.45

broughtFwdResidentialFinancialCost
number
optional

Amount of relief brought forward for restricted residential financial costs. The value must be between 0 and 99999999999.99.

For example: 1000.45

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99.

For example: 1000.45

consolidatedExpenses
number
optional

Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.

For example: 1000.45

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: /sample-context/AA123456A

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/property/{bsasId}/adjust

Retrieve a UK Property Business' Summary Adjustments
GET

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Retrieve UK Property Business' Summary Adjustments - non-FHL example 

{
  "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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS12345678910

accountingPeriod
object
required

An object containing the accounting period start and end dates.
startDate
string
required

The date the accounting period started.

For example: 2019-04-06

endDate
string
required

The date the accounting period ended.

For example: 2020-04-05

taxYear
string
required

The tax year into which this accounting period falls.

For example: 2019-20

requestedDateTime
string
required

The original date and time of the summary calculation before any adjustments.

Must conform to the regular expression ^2[0-9]{3}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,3}|)Z$

For example: 2020-07-11T12:13:48.763Z

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

repairsAndMaintenance
number
optional

The adjustment made to property repairs and maintenance. The value must be between 0 and 99999999999.99.

For example: 1000.45

financialCosts
number
optional

The adjustment made to loan interest and other financial costs. The value must be between 0 and 99999999999.99.

For example: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

other
number
optional

The adjustment made to other allowable property expenses. The value must be between 0 and 99999999999.99.

For example: 1000.45

consolidatedExpenses
number
optional

Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.

For example: 1000.45

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/AA123456A

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/property/{bsasId}/adjust

Submit an Adjustment to a UK Property Business Summary
POST

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Name Description
Accept
required

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

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

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Non-FHL Property with Full Expenses 

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

Scenario: Non-FHL Property with Consolidated Expenses 

{
  "nonFurnishedHolidayLet": {
    "income": {
      "rentIncome": 1000.49,
      "premiumsOfLeaseGrant": 1000.49,
      "reversePremiums": 1000.49,
      "otherPropertyIncome": 1000.49
    },
    "expenses": {
      "consolidatedExpenses": 1000.49,
      "residentialFinancialCost": 1000.49
    }
  }
}

Scenario: FHL Property with Full Expenses 

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

Scenario: FHL Property with Consolidated Expenses 

{
  "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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

{
  "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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/AA123456A

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.

Close Section

Foreign property business

Foreign property business resources

/individuals/self-assessment/adjustable-summary/{nino}/foreign-property/{bsasId}

Retrieve a Foreign Property Business Source Adjustable Summary (BSAS)
GET

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: true

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Foreign Property 

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

Foreign Property FHL EEA 

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

Foreign Property with consolidated expenses 

{
  "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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS123456789012

accountingPeriod
object
required

An object containing the accounting period start and end dates.
startDate
string
required

The date the accounting period started.

For example: 2019-04-06

endDate
string
required

The date the accounting period ended.

For example: 2020-04-05

taxYear
string
required

The tax year into which this accounting period falls.

For example: 2019-20

requestedDateTime
string
required

The original date and time of the summary calculation before any adjustments.

Must conform to the regular expression ^2[0-9]{3}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,3}|)Z$

For example: 2020-07-11T12:13:48.763Z

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

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: 123.12

expenses
number
optional

The total expenses for the income source. The value must be between 0 and 99999999999.99.

For example: 123.12

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: 123.12

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: 123.12

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: 123.12

taxable
number
optional

The taxable net profit of the income source. The value must be between 0 and 99999999999.

For example: 123.

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: 123.12

adjustedIncomeTax
number
optional

The adjusted income tax loss. The value must be between 0 and 99999999999.

For example: 123

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: 123.12

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: 123.12

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: 123.12

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: 123.12

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99.

For example: 123.12

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99.

For example: 123.12

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99.

For example: 123.12

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: 123.12

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99.

For example: 123.12

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: 123.12

broughtFwdResidentialFinancialCost
number
optional

Amount of relief brought forward for restricted residential financial costs. The value must be between 0 and 99999999999.99.

For example: 123.12

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99.

For example: 123.12

consolidatedExpenses
number
optional

Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.

For example: 123.12

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: FRA

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: 123.12

expenses
number
optional

The total expenses for the income source. The value must be between 0 and 99999999999.99.

For example: 123.12

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: 123.12

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: 123.12

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: 123.12

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: 123.12

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: 123.12

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: 123.12

repairsAndMaintenance
number
optional

Property repairs and maintenance. The value must be between 0 and 99999999999.99.

For example: 123.12

financialCosts
number
optional

Loan interest and other financial costs. The value must be between 0 and 99999999999.99.

For example: 123.12

professionalFees
number
optional

Legal, management and other professional fees. The value must be between 0 and 99999999999.99.

For example: 123.12

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: 123.12

costOfServices
number
optional

Cost of services provided, including wages. The value must be between 0 and 99999999999.99.

For example: 123.12

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: 123.12

broughtFwdResidentialFinancialCost
number
optional

Amount of relief brought forward for restricted residential financial costs. The value must be between 0 and 99999999999.99.

For example: 123.12

other
number
optional

Other allowable property expenses. The value must be between 0 and 99999999999.99.

For example: 123.12

consolidatedExpenses
number
optional

Sum of all expenses for the specified period. The value must be between 0 and 99999999999.99.

For example: 123.12

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/AA999999A/foreign-property/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/adjust

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/foreign-property/{bsasId}/adjust

Retrieve a Foreign Property Business' Summary Adjustments
GET

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Retrieve Foreign Property Business' Summary Adjustments example 

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

Retrieve Foreign Property FhlEea Business' Summary Adjustments example 

{
  "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 ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XAIS123456789012

accountingPeriod
object
required

An object containing the accounting period start and end dates.
startDate
string
required

The date the accounting period started.

For example: 2019-04-06

endDate
string
required

The date the accounting period ended.

For example: 2020-04-05

taxYear
string
required

The tax year into which this accounting period falls.

For example: 2019-20

requestedDateTime
string
required

The original date and time of the summary calculation before any adjustments.

Must conform to the regular expression ^2[0-9]{3}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{0,3}|)Z$

For example: 2020-07-11T12:13:48.763Z

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: false

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/AA123456A

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.

Close Section
/individuals/self-assessment/adjustable-summary/{nino}/foreign-property/{bsasId}/adjust

Submit a Foreign Property Business' Accounting Adjustments
POST

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: TC663795B

bsasId
string
required

The unique identifier of the summary calculation.

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

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Name Description
Accept
required

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

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

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: foreignProperty consolidated request 

{
  "foreignProperty": [
    {
      "countryCode": "FRA",
      "income": {
        "rentIncome": 123.12,
        "premiumsOfLeaseGrant": 123.12,
        "otherPropertyIncome": 123.12
      },
      "expenses": {
        "consolidatedExpenses": 123.12
      }
    }
  ]
}

Scenario: foreignProperty unconsolidated request 

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

Scenario: foreignFhlEea consolidated request 

{
  "foreignFhlEea": {
    "income": {
      "rentIncome": 123.12
    },
    "expenses": {
      "consolidatedExpenses": 123.12
    }
  }
}

Scenario: foreignFhlEea unconsolidated request 

{
  "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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

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: 1000.45

Responses

HTTP status 200 (OK)

Response headers

Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response 

{
  "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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

links
array
optional

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

The relative URL of the endpoint.

For example: /individuals/self-assessment/adjustable-summary/{nino}/foreign-property/{bsasId}

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