This version is in beta - expect some breaking changes.

Self-Employment Business (MTD) API

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

Overview

This API allows developers to:

  • create or amend a self-employment annual summary for a tax year
  • retrieve a self-employment annual submission for a tax year
  • delete the self-employment annual submission for a tax year
  • create a self-employment period summary for submission of periodic data
  • amend a self-employment period summary
  • retrieve a single self-employment period summary for a given identifier
  • retrieve a list of all self-employment period summaries

Send fraud prevention data

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

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

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

Versioning

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

Errors

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

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

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

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

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

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

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

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

An example with multiple errors: {     "code": "INVALID_REQUEST",     "message": "Invalid request",     "errors": [      {      "code": "FORMAT_VALUE",      "message": "The 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/business/self-employment/{nino}/{businessId}/annual/{taxYear}

Retrieve a Self-Employment Annual Submission [test only]
GET

This endpoint allows a developer to retrieve a self-employment annual submission for a tax year. A National Insurance number, Business ID and tax year must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies in the format YYYY-YY. The start year and end year must not span two tax years. The minimum tax year is 2017-18. No gaps are allowed, for example, 2022-24 is not valid.

For example: 2022-23

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response with Full Allowances

{
  "adjustments": {
    "includedNonTaxableProfits": 210,
    "basisAdjustment": 178.23,
    "overlapReliefUsed": 123.78,
    "accountingAdjustment": 678.9,
    "averagingAdjustment": 674.98,
    "outstandingBusinessIncome": 342.67,
    "balancingChargeBpra": 145.98,
    "balancingChargeOther": 457.23,
    "goodsAndServicesOwnUse": 432.9
  },
  "allowances": {
    "annualInvestmentAllowance": 564.76,
    "capitalAllowanceMainPool": 456.98,
    "capitalAllowanceSpecialRatePool": 352.87,
    "zeroEmissionsGoodsVehicleAllowance": 653.9,
    "businessPremisesRenovationAllowance": 452.98,
    "enhancedCapitalAllowance": 563.23,
    "allowanceOnSales": 678.9,
    "capitalAllowanceSingleAssetPool": 563.89,
    "electricChargePointAllowance": 0,
    "structuredBuildingAllowance": [
      {
        "amount": 564.89,
        "firstYear": {
          "qualifyingDate": "2019-05-29",
          "qualifyingAmountExpenditure": 567.67
        },
        "building": {
          "name": "Victoria Building",
          "number": "23",
          "postcode": "TF3 5GH"
        }
      }
    ],
    "enhancedStructuredBuildingAllowance": [
      {
        "amount": 445.56,
        "firstYear": {
          "qualifyingDate": "2019-09-29",
          "qualifyingAmountExpenditure": 565.56
        },
        "building": {
          "name": "Trinity House",
          "number": "20",
          "postcode": "TF4 7HJ"
        }
      }
    ],
    "zeroEmissionsCarAllowance": 678.78
  },
  "nonFinancials": {
    "businessDetailsChangedRecently": true,
    "class4NicsExemptionReason": "non-resident"
  },
  "links": [
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/annual/2019-20",
      "rel": "create-and-amend-self-employment-annual-submission",
      "method": "PUT"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/annual/2019-20",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/annual/2019-20",
      "rel": "delete-self-employment-annual-submission",
      "method": "DELETE"
    }
  ]
}

Example Response with Trading Allowance

{
  "adjustments": {
    "includedNonTaxableProfits": 210,
    "basisAdjustment": 178.23,
    "overlapReliefUsed": 123.78,
    "accountingAdjustment": 678.9,
    "averagingAdjustment": 674.98,
    "outstandingBusinessIncome": 342.67,
    "balancingChargeBpra": 145.98,
    "balancingChargeOther": 457.23,
    "goodsAndServicesOwnUse": 432.9
  },
  "allowances": {
    "tradingIncomeAllowance": 572.99
  },
  "nonFinancials": {
    "businessDetailsChangedRecently": true,
    "class4NicsExemptionReason": "non-resident"
  },
  "links": [
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/annual/2019-20",
      "rel": "create-and-amend-self-employment-annual-submission",
      "method": "PUT"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/annual/2019-20",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/annual/2019-20",
      "rel": "delete-self-employment-annual-submission",
      "method": "DELETE"
    }
  ]
}

Response table
Name Description
adjustments
object
optional

Object containing the details about annual adjustments

includedNonTaxableProfits
number
optional

Income, receipts and other profits included in business income or expenses but not taxable as business profits. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

basisAdjustment
number
optional

If your basis period is not the same as your accounting period, enter the adjustment needed to arrive at the profit or loss for the basis period. If the adjustment needs to be taken off the profit figure, this should be negative. Between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

overlapReliefUsed
number
optional

Overlap relief used this year. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

accountingAdjustment
number
optional

Adjustment for change of accounting practice. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

averagingAdjustment
number
optional

Averaging adjustment (only for farmers, market gardeners and creators of literary or artistic works) – if the adjustment needs to be taken off the profit figure, this should be negative. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

outstandingBusinessIncome
number
optional

Any other business income not included in other fields. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

balancingChargeBpra
number
optional

Balancing charge on sale or cessation of business use (only where Business Premises Renovation Allowance has been claimed). The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

balancingChargeOther
number
optional

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

For example: 2000.99

goodsAndServicesOwnUse
number
optional

Value of the normal sale price of goods or stock have been taken out of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

allowances
object
optional

Object containing the details about annual allowances

annualInvestmentAllowance
number
optional

Annual investment allowance on items that qualify up to the AIA amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

capitalAllowanceMainPool
number
optional

Capital allowances at 18% on equipment, including cars with lower CO2 emissions. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

capitalAllowanceSpecialRatePool
number
optional

Capital allowances at 8% on equipment, including cars with higher CO2 emissions. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

zeroEmissionsGoodsVehicleAllowance
number
optional

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

For example: 2000.99

businessPremisesRenovationAllowance
number
optional

Business Premises Renovation Allowance if converting or renovating unused qualifying business premises. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

enhancedCapitalAllowance
number
optional

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

For example: 2000.99

allowanceOnSales
number
optional

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

For example: 2000.99

capitalAllowanceSingleAssetPool
number
optional

Claim to capital allowances in respect of all single asset pools. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

electricChargePointAllowance
number
optional

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

For example: 2000.99

zeroEmissionsCarAllowance
number
optional

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

For example: 2000.99

tradingIncomeAllowance
number
optional

The amount of trading allowance (can not be supplied with any other allowances). The value must be between 0 and 1000.00 up to 2 decimal places.

For example: 2000.99

structuredBuildingAllowance
array
optional

Details about structured building allowance

amount
number
required

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

For example: 2000.99

firstYear
object
optional

Object containing the details about structured building allowance

qualifyingDate
string
required

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

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

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

For example: 2000.99

building
object
required

Postcode is mandatory and minimum one of name and number field must be supplied

name
string
optional

The name of the building.

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

For example: Green Oak’s

number
string
optional

The number of the building.

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

For example: 16D

postcode
string
required

The postcode for the building.

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

For example: SW1A 2AA

enhancedStructuredBuildingAllowance
array
optional

Details about enhanced structured building allowance

amount
number
required

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

For example: 5000.99

firstYear
object
optional

Object containing the details about enhanced structured building allowance

qualifyingDate
string
required

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

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

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

For example: 5000.99

building
object
required

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

name
string
optional

The name of the building.

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

For example: Green Oak’s

number
string
optional

The number of the building.

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

For example: 16D

postcode
string
required

The postcode for the building.

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

For example: SW1A 2AA

nonFinancials
object
optional

Object containing details about annual non financials

businessDetailsChangedRecently
boolean
required

A boolean to identify if business details have recently changed. The value must be true or false.

For example: false

class4NicsExemptionReason
string
optional

If exempt from paying Class 4 National Insurance, the reason for exemption.

Limited to the following possible values:

non-resident
trustee
diver
ITTOIA-2005
over-state-pension-age
under-16
links
array
optional

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

href
string
required

The relative url of the endpoint.

For example: /individuals/business/self-employment/AA999999A/XAIS12345678910/annual/2022-23

rel
string
required

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

Limited to the following possible values:

self
create-and-amend-self-employment-annual-submission
delete-self-employment-annual-submission
method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
DELETE

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_BUSINESS_ID

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

400 (Bad Request)

FORMAT_TAX_YEAR

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

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. The tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success response.

TRADING_ALLOWANCE

Simulates success response with trading allowance instead.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/self-employment/{nino}/{businessId}/annual/{taxYear}

Create and Amend Self-Employment Annual Submission [test only]
PUT

This end point allows a developer to create or amend a self-employment annual summary for a tax year. A National Insurance number, Business ID and tax year must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies in the format YYYY-YY. The start year and end year must not span two tax years. The minimum tax year is 2017-18. No gaps are allowed, for example, 2022-24 is not valid.

For example: 2022-23

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

For example: -
Content-Type
required

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Response With Trading Income Allowance Request

{
  "adjustments": {
    "includedNonTaxableProfits": 200.12,
    "basisAdjustment": 200.12,
    "overlapReliefUsed": 200.12,
    "accountingAdjustment": 200.12,
    "averagingAdjustment": -200.12,
    "outstandingBusinessIncome": 200.12,
    "balancingChargeBpra": 200.12,
    "balancingChargeOther": 200.12,
    "goodsAndServicesOwnUse": 200.12
  },
  "allowances": {
    "tradingIncomeAllowance": 1000.00
  },
  "nonFinancials": {
    "businessDetailsChangedRecently": true,
    "class4NicsExemptionReason": "non-resident"
  }
}

Scenario: Response Without Trading Income Allowance Request

{
  "adjustments": {
    "includedNonTaxableProfits": 200.12,
    "basisAdjustment": 200.12,
    "overlapReliefUsed": 200.12,
    "accountingAdjustment": 200.12,
    "averagingAdjustment": -200.12,
    "outstandingBusinessIncome": 200.12,
    "balancingChargeBpra": 200.12,
    "balancingChargeOther": 200.12,
    "goodsAndServicesOwnUse": 200.12
  },
  "allowances": {
    "annualInvestmentAllowance": 200.12,
    "capitalAllowanceMainPool": 200.12,
    "capitalAllowanceSpecialRatePool": 200.12,
    "zeroEmissionsGoodsVehicleAllowance": 200.12,
    "businessPremisesRenovationAllowance": 200.12,
    "enhancedCapitalAllowance": 200.12,
    "allowanceOnSales": 200.12,
    "capitalAllowanceSingleAssetPool": 200.12,
    "electricChargePointAllowance": 200.12,
    "zeroEmissionsCarAllowance": 200.12,
    "structuredBuildingAllowance": [
      {
        "amount": 1.23,
        "firstYear": {
          "qualifyingDate": "2021-11-11",
          "qualifyingAmountExpenditure": 1.23
        },
        "building": {
          "name": "Plaza 2",
          "postcode": "TF3 4NT"
        }
      }
    ],
    "enhancedStructuredBuildingAllowance": [
      {
        "amount": 1.23,
        "firstYear": {
          "qualifyingDate": "2021-11-11",
          "qualifyingAmountExpenditure": 1.23
        },
        "building": {
          "name": "Plaza 2",
          "postcode": "TF3 4NT"
        }
      }
    ]
  },
  "nonFinancials": {
    "businessDetailsChangedRecently": true
  }
}

Request table
Name Description
adjustments
object
optional

Object containing the details about annual adjustments

includedNonTaxableProfits
number
optional

Income, receipts and other profits included in business income or expenses but not taxable as business profits. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

basisAdjustment
number
optional

If your basis period is not the same as your accounting period, enter the adjustment needed to arrive at the profit or loss for the basis period. If the adjustment needs to be taken off the profit figure, this should be negative. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

overlapReliefUsed
number
optional

Overlap relief used this year. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

accountingAdjustment
number
optional

Adjustment for change of accounting practice. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

averagingAdjustment
number
optional

Averaging adjustment (only for farmers, market gardeners and creators of literary or artistic works) – if the adjustment needs to be taken off the profit figure, this should be negative. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

outstandingBusinessIncome
number
optional

Any other business income not included in other fields. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

balancingChargeBpra
number
optional

Balancing charge on sale or cessation of business use (only where Business Premises Renovation Allowance has been claimed). This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

balancingChargeOther
number
optional

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

For example: 2000.99

goodsAndServicesOwnUse
number
optional

Value of the normal sale price of goods or stock have been taken out of the business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

allowances
object
optional

Object containing the details about annual allowances

annualInvestmentAllowance
number
optional

Annual investment allowance on items that qualify up to the AIA amount. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

capitalAllowanceMainPool
number
optional

Capital allowances at 18% on equipment, including cars with lower CO2 emissions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

capitalAllowanceSpecialRatePool
number
optional

Capital allowances at 8% on equipment, including cars with higher CO2 emissions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

zeroEmissionsGoodsVehicleAllowance
number
optional

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

For example: 2000.99

businessPremisesRenovationAllowance
number
optional

Business Premises Renovation Allowance if converting or renovating unused qualifying business premises. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.45

enhancedCapitalAllowance
number
optional

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

For example: 1000.45

allowanceOnSales
number
optional

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

For example: 1000.45

capitalAllowanceSingleAssetPool
number
optional

Claim to capital allowances in respect of all single asset pools. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 500.25

electricChargePointAllowance
number
optional

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

For example: 1000.45

zeroEmissionsCarAllowance
number
optional

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

For example: 5000.99

tradingIncomeAllowance
number
optional

The amount of trading allowance (can not be supplied with any other allowances). The value must be between 0 and 1000 up to 2 decimal places.

For example: 500.99

structuredBuildingAllowance
array
optional

Details about structured building allowance

amount
number
required

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

For example: 5000.99

firstYear
object
optional

Object containing the details about structured building allowance

qualifyingDate
string
required

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

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

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

For example: 5000.99

building
object
required

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

name
string
optional

The name of the building.

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

For example: Green Oak’s

number
string
optional

The number of the building.

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

For example: 16D

postcode
string
required

The postcode for the building.

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

For example: SW1A 2AA

enhancedStructuredBuildingAllowance
array
optional

Details about enhanced structured building allowance

amount
number
required

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

For example: 5000.99

firstYear
object
optional

Object containing the details about enhanced structured building allowance

qualifyingDate
string
required

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

For example: 2020-01-01

qualifyingAmountExpenditure
number
required

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

For example: 5000.99

building
object
required

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

name
string
optional

The name of the building.

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

For example: Green Oak’s

number
string
optional

The number of the building.

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

For example: 16D

postcode
string
required

The postcode for the building.

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

For example: SW1A 2AA

nonFinancials
object
optional

Object containing details about annual non financials

businessDetailsChangedRecently
boolean
required

A boolean to identify if business details have recently changed. The value must be true or false.

For example: false

class4NicsExemptionReason
string
optional

If exempt from paying Class 4 National Insurance, the reason for exemption.

Limited to the following possible values:

non-resident
trustee
diver
ITTOIA-2005
over-state-pension-age
under-16

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response

{
  "links": [
    {
      "href": "/individuals/business/self-employment/AA999999A/XAIS12345678910/annual/2022-23",
      "rel": "create-and-amend-self-employment-annual-submission",
      "method": "PUT"
    },
    {
      "href": "/individuals/business/self-employment/AA999999A/XAIS12345678910/annual/2022-23",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/business/self-employment/AA999999A/XAIS12345678910/annual/2022-23",
      "rel": "delete-self-employment-annual-submission",
      "method": "DELETE"
    }
  ]
}

Response table
Name Description
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /individuals/business/self-employment/AA999999A/XAIS12345678910/annual/2022-23

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
DELETE
rel
string
required

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

Limited to the following possible values:

create-and-amend-self-employment-annual-submission
delete-self-employment-annual-submission
self

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_TAX_YEAR

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

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The specified tax year is not supported. The tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

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

400 (Bad Request)

FORMAT_VALUE

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

400 (Bad Request)

FORMAT_BUSINESS_ID

One of building name or number must be supplied.

400 (Bad Request)

RULE_BUILDING_NAME_NUMBER

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

400 (Bad Request)

FORMAT_STRING

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

400 (Bad Request)

RULE_BOTH_ALLOWANCES_SUPPLIED

One or more of the supplied allowances is not supported for the supplied tax year.

400 (Bad Request)

RULE_ALLOWANCE_NOT_SUPPORTED

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

The supplied date format is not valid.

400 (Bad Request)

FORMAT_DATE

The format of the supplied Class 4 National Insurance exemption reason is not valid.

400 (Bad Request)

FORMAT_CLASS_4_EXEMPTION_REASON

The client and/or agent is not authorised. This is normally 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 matching resource is not found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success response.

ALLOWANCE_NOT_SUPPORTED

Simulates the scenario where one or more of the supplied allowances is not supported for the supplied tax year.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section

Delete a Self-Employment Annual Submission [test only]
DELETE

This endpoint allows a developer to delete the self-employment annual submission for a tax year. A National Insurance number, Business ID and tax year must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

taxYear
string
required

The tax year to which the data applies in the format YYYY-YY. The start year and end year must not span two tax years. The minimum tax year is 2017-18. No gaps are allowed, for example, 2022-24 is not valid.

For example: 2022-23

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters

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

See also fraud prevention.

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_BUSINESS_ID

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

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. 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 and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

DELETE

Simulates success response.

NOT_FOUND

Simulates the scenario where no data found.


Close Section
/individuals/business/self-employment/{nino}/{businessId}/period

List Self-Employment Period Summaries [test only]
GET

This endpoint allows a developer to retrieve a list of all self-employment period summaries. A National Insurance number and Business ID must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response

{
  "periods": [
    {
      "periodId": "2017-04-06_2017-07-04",
      "periodStartDate": "2017-04-06",
      "periodEndDate": "2017-07-04",
      "links": [
        {
          "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2017-04-06_2017-07-04",
          "method": "GET",
          "rel": "self"
        }
      ]
    },
    {
      "periodId": "2017-07-05_2017-10-04",
      "periodStartDate": "2017-07-05",
      "periodEndDate": "2017-10-04",
      "links": [
        {
          "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2017-07-05_2017-10-04",
          "method": "GET",
          "rel": "self"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period",
      "method": "POST",
      "rel": "create-self-employment-period-summary"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Response table
Name Description
periods
array
required

Details about Self-Employment periods.

periodId
string
required

Concatenated Period Start and End dates.

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

periodStartDate
string
required

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

For example: 2020-01-01

periodEndDate
string
required

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

For example: 2020-01-01

links
array
optional

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

href
string
required

The relative url of the endpoint.

For example: /individuals/business/self-employment/TC663795B/XAIS12345678910/period

rel
string
required

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

Limited to the following possible values:

self
create-self-employment-period-summary
method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
POST

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_BUSINESS_ID

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/self-employment/{nino}/{businessId}/period

Create a Self-Employment Period Summary [test only]
POST

This endpoint allows a developer to create a self-employment period summary for submission of periodic data. Submissions must include values for incomes, expenses and deductions, even if the values are zero. For example, if you have no income for the period, submit a periodIncome object with 'turnover' and 'other' values of zero. A National Insurance number and business must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

For example: -
Content-Type
required

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Create Period Summary Request

{
  "periodDates": {
    "periodStartDate": "2019-08-24",
    "periodEndDate": "2019-08-24"
  },
  "periodIncome": {
    "turnover": 1000.99,
    "other": 1000.09
  },
  "periodAllowableExpenses": {
    "costOfGoodsAllowable": 1000.99,
    "paymentsToSubcontractorsAllowable": 1000.99,
    "wagesAndStaffCostsAllowable": 1000.99,
    "carVanTravelExpensesAllowable": 1000.99,
    "premisesRunningCostsAllowable": -99999.99,
    "maintenanceCostsAllowable": -1000.99,
    "adminCostsAllowable": 1000.99,
    "businessEntertainmentCostsAllowable": 1000.99,
    "advertisingCostsAllowable": 1000.99,
    "interestOnBankOtherLoansAllowable": -1000.99,
    "financeChargesAllowable": -1000.99,
    "irrecoverableDebtsAllowable": -1000.99,
    "professionalFeesAllowable": -99999999999.99,
    "depreciationAllowable": -1000.99,
    "otherExpensesAllowable": 1000.99
  },
  "periodDisallowableExpenses": {
    "costOfGoodsDisallowable": 91000.99,
    "paymentsToSubcontractorsDisallowable": 1000.99,
    "wagesAndStaffCostsDisallowable": 1000.99,
    "carVanTravelExpensesDisallowable": 1000.99,
    "premisesRunningCostsDisallowable": -1000.99,
    "maintenanceCostsDisallowable": -999.99,
    "adminCostsDisallowable": 1000.99,
    "businessEntertainmentCostsDisallowable": 1000.99,
    "advertisingCostsDisallowable": 1000.99,
    "interestOnBankOtherLoansDisallowable": -1000.99,
    "financeChargesDisallowable": -9999.99,
    "irrecoverableDebtsDisallowable": 1000.99,
    "professionalFeesDisallowable": 1000.99,
    "depreciationDisallowable": -99999999999.99,
    "otherExpensesDisallowable": 1000.99
  }
}

Scenario: Create Period Summary With Consolidated Request

{
  "periodDates": {
    "periodStartDate": "2019-08-24",
    "periodEndDate": "2019-08-24"
  },
  "periodIncome": {
    "turnover": 1000.99,
    "other": 1000.09
  },
  "periodAllowableExpenses": {
    "consolidatedExpenses": 99999999999.99
  }
}

Request table
Name Description
periodDates
object
required

Object containing the details about self-employment period dates.

periodStartDate
string
required

The first day that the income, expenses and deduction period summary covers.

Date in the format YYYY-MM-DD

For example: 2020-01-01

periodEndDate
string
required

The last day that the income, expenses and deduction period summary covers.

Date in the format YYYY-MM-DD

For example: 2020-01-01

periodIncome
object
optional

Object containing the details about self-employment income.

turnover
number
optional

The takings, fees, sales or money earned by your business. Income associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

other
number
optional

Any other business income not included in turnover. Income associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

periodAllowableExpenses
object
optional

Object containing the details about self-employment allowable expenses.

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

costOfGoodsAllowable
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 up to 2 decimal places.

For example: 10000.00

paymentsToSubcontractorsAllowable
number
optional

Payments to construction Industry subcontractors. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

wagesAndStaffCostsAllowable
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 up to 2 decimal places.

For example: 10000.00

carVanTravelExpensesAllowable
number
optional

Car, van and travel expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

premisesRunningCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

maintenanceCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

adminCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

businessEntertainmentCostsAllowable
number
optional

Business entertainment costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

advertisingCostsAllowable
number
optional

Advertising costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

interestOnBankOtherLoansAllowable
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 up to 2 decimal places.

For example: 10000.89

financeChargesAllowable
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 up to 2 decimal places.

For example: 10000.89

irrecoverableDebtsAllowable
number
optional

Irrecoverable debts written off. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

professionalFeesAllowable
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 up to 2 decimal places.

For example: 10000.89

depreciationAllowable
number
optional

Depreciation and loss/profit on sales of assets. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

otherExpensesAllowable
number
optional

Other business expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

periodDisallowableExpenses
object
optional

Object containing the details about self-employment disallowable expenses that cannot be claimed for tax purposes.

costOfGoodsDisallowable
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 up to 2 decimal places.

For example: 10000.45

paymentsToSubcontractorsDisallowable
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 up to 2 decimal places.

For example: 10000.89

wagesAndStaffCostsDisallowable
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 up to 2 decimal places.

For example: 10000.89

carVanTravelExpensesDisallowable
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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

interestOnBankOtherLoansDisallowable
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 up to 2 decimal places.

For example: 10000.89

financeChargesDisallowable
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 up to 2 decimal places.

For example: 10000.89

irrecoverableDebtsDisallowable
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 up to 2 decimal places.

For example: 10000.89

professionalFeesDisallowable
number
optional

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

otherExpensesDisallowable
number
optional

Other business expenses. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Create Period Summary Response

{
  "periodId": "2019-06-12_2020-06-12",
  "links": [
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel": "amend-self-employment-period-summary",
      "method": "PUT"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910}/period/2019-06-12_2020-06-12",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period",
      "rel": "list-self-employment-period-summaries",
      "method": "GET"
    }
  ]
}

Response table
Name Description
periodId
string
required

An identifier for the update period, unique to the customer's self-employment business.

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

links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

PUT
GET
self
rel
string
required

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

Limited to the following possible values:

amend-self-employment-period-summary
list-self-employment-period-summaries
self

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_BUSINESS_ID

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

400 (Bad Request)

FORMAT_VALUE

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

400 (Bad Request)

FORMAT_START_DATE

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

400 (Bad Request)

FORMAT_END_DATE

The End date is earlier than the Start date.

400 (Bad Request)

RULE_END_DATE_BEFORE_START_DATE

Both expenses and consolidatedExpenses can not be present at the same time.

400 (Bad Request)

RULE_BOTH_EXPENSES_SUPPLIED

Period summary overlaps with any of the existing period summaries.

400 (Bad Request)

RULE_OVERLAPPING_PERIOD

Period summary is not within the accounting period.

400 (Bad Request)

RULE_MISALIGNED_PERIOD

Period summaries are not contiguous.

400 (Bad Request)

RULE_NOT_CONTIGUOUS_PERIOD

Consolidated expenses are not allowed if the accumulative turnover amount exceeds the threshold.

400 (Bad Request)

RULE_NOT_ALLOWED_CONSOLIDATED_EXPENSES

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

Matching resource not found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

OVERLAPPING_PERIOD

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

MISALIGNED_PERIOD

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

NOT_CONTIGUOUS_PERIOD

Simulates the scenario where the period summaries are not contiguous.

NOT_ALLOWED_CONSOLIDATED_EXPENSES

Simulates the scenario where the cumulative turnover amount exceeds the consolidated expenses threshold.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/self-employment/{nino}/{businessId}/period/{periodId}

Retrieve a Self-Employment Period Summary [test only]
GET

This endpoint allows a developer to retrieve a single self-employment period summary for a given identifier. A National Insurance number, business ID and period ID must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

periodId
string
required

An identifier for the update period, unique to the customer's self-employment business.

For example: 2019-01-25_2020-01-25

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Non-Consolidated Response

{
  "periodDates":{
    "periodStartDate":"2019-08-24",
    "periodEndDate":"2019-08-24"
  },
  "periodIncome":{
    "turnover":200.00,
    "other":200.00
  },
  "periodAllowableExpenses":{
    "costOfGoodsAllowable":200.00,
    "paymentsToSubcontractorsAllowable":200.00,
    "wagesAndStaffCostsAllowable":200.00,
    "carVanTravelExpensesAllowable":200.00,
    "premisesRunningCostsAllowable":200.00,
    "maintenanceCostsAllowable":200.00,
    "adminCostsAllowable":200.00,
    "businessEntertainmentCostsAllowable":200.00,
    "advertisingCostsAllowable":200.00,
    "interestOnBankOtherLoansAllowable":200.00,
    "financeChargesAllowable":200.00,
    "irrecoverableDebtsAllowable":200.00,
    "professionalFeesAllowable":200.00,
    "depreciationAllowable":200.00,
    "otherExpensesAllowable":200.00
  },
  "periodDisallowableExpenses":{
    "costOfGoodsDisallowable":200.00,
    "paymentsToSubcontractorsDisallowable":200.00,
    "wagesAndStaffCostsDisallowable":200.00,
    "carVanTravelExpensesDisallowable":200.00,
    "premisesRunningCostsDisallowable":200.00,
    "maintenanceCostsDisallowable":200.00,
    "adminCostsDisallowable":200.00,
    "businessEntertainmentCostsDisallowable":200.00,
    "advertisingCostsDisallowable":200.00,
    "interestOnBankOtherLoansDisallowable":200.00,
    "financeChargesDisallowable":200.00,
    "irrecoverableDebtsDisallowable":200.00,
    "professionalFeesDisallowable":200.00,
    "depreciationDisallowable":200.00,
    "otherExpensesDisallowable":200.00
  },
  "links":[
    {
      "href":"/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel":"amend-self-employment-period-summary",
      "method":"PUT"
    },
    {
      "href":"/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/business/self-employment/TC663795B/XAIS12345678910/period",
      "rel":"list-self-employment-period-summaries",
      "method":"GET"
    }
  ]
}

Consolidated Response

{
  "periodDates":{
    "periodStartDate":"2019-08-24",
    "periodEndDate":"2019-08-24"
  },
  "periodIncome":{
    "turnover":200.00,
    "other":200.00
  },
  "periodAllowableExpenses":{
    "consolidatedExpenses":200.00
  },
  "links":[
    {
      "href":"/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel":"amend-self-employment-period-summary",
      "method":"PUT"
    },
    {
      "href":"/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/business/self-employment/TC663795B/XAIS12345678910/period",
      "rel":"list-self-employment-period-summaries",
      "method":"GET"
    }
  ]
}

Response table
Name Description
periodDates
object
required

Object containing the details about self-employment period dates.

periodStartDate
string
required

The first day that the income, expenses and deduction period summary covers.

Date in the format YYYY-MM-DD

For example: 2020-01-01

periodEndDate
string
required

The last day that the income, expenses and deduction period summary covers.

Date in the format YYYY-MM-DD

For example: 2020-01-01

periodIncome
object
optional

Object containing the details about self-employment income.

turnover
number
optional

The takings, fees, sales or money earned by your business. Income associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

other
number
optional

Any other business income not included in turnover. Income associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

periodAllowableExpenses
object
optional

Object containing the details about self-employment allowable expenses.

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

costOfGoodsAllowable
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 up to 2 decimal places.

For example: 10000.00

paymentsToSubcontractorsAllowable
number
optional

Payments to construction Industry subcontractors. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

wagesAndStaffCostsAllowable
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 up to 2 decimal places.

For example: 10000.00

carVanTravelExpensesAllowable
number
optional

Car, van and travel expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

premisesRunningCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

maintenanceCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

adminCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

businessEntertainmentCostsAllowable
number
optional

Business entertainment costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

advertisingCostsAllowable
number
optional

Advertising costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

interestOnBankOtherLoansAllowable
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 up to 2 decimal places.

For example: 10000.89

financeChargesAllowable
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 up to 2 decimal places.

For example: 10000.89

irrecoverableDebtsAllowable
number
optional

Irrecoverable debts written off. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

professionalFeesAllowable
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 up to 2 decimal places.

For example: 10000.89

depreciationAllowable
number
optional

Depreciation and loss/profit on sales of assets. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

otherExpensesAllowable
number
optional

Other business expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

periodDisallowableExpenses
object
optional

Object containing the details about self-employment disallowable expenses that cannot be claimed for tax purposes.

costOfGoodsDisallowable
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 up to 2 decimal places.

For example: 10000.45

paymentsToSubcontractorsDisallowable
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 up to 2 decimal places.

For example: 10000.89

wagesAndStaffCostsDisallowable
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 up to 2 decimal places.

For example: 10000.89

carVanTravelExpensesDisallowable
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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

interestOnBankOtherLoansDisallowable
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 up to 2 decimal places.

For example: 10000.89

financeChargesDisallowable
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 up to 2 decimal places.

For example: 10000.89

irrecoverableDebtsDisallowable
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 up to 2 decimal places.

For example: 10000.89

professionalFeesDisallowable
number
optional

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

otherExpensesDisallowable
number
optional

Other business expenses. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

links
array
optional

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

href
string
required

The relative url of the endpoint.

For example: /individuals/business/self-employment/{nino}/{businessId}/period/{periodId}

rel
string
required

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

Limited to the following possible values:

self
amend-self-employment-period-summary
list-self-employment-period-summaries
method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_BUSINESS_ID

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

400 (Bad Request)

FORMAT_PERIOD_ID

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

CONSOLIDATED_EXPENSES

Simulates success response with consolidatedExpenses.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section
/individuals/business/self-employment/{nino}/{businessId}/period/{periodId}

Amend a Self-Employment Period Summary [test only]
PUT

This endpoint allows a developer to amend a self-employment period summary. Submissions must include values for incomes, expenses and deductions, even if the values are zero. The periodExpenses object may contain either a consolidatedExpenses element, or a mixture of the other expenses elements. A National Insurance number, business ID and period ID must be provided.

Authorisation

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

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

businessId
string
required

An identifier for the business, unique to the customer. Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$.

For example: XAIS12345678910

periodId
string
required

An identifier for the update period, unique to the customer's self-employment business.

For example: 2019-01-25_2020-01-25

Request headers

Request headers Table
Name Description
Accept
required

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

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

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

For example: -
Content-Type
required

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

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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Amend Period Summary Consolidated Request

{
  "periodIncome": {
    "turnover": 1000.99,
    "other": 1000.99
  },
  "periodAllowableExpenses": {
    "consolidatedExpenses": 1000.99
  }
}

Scenario: Amend Period Summary Non-Consolidated Request

{
  "periodIncome": {
    "turnover": 1000.99,
    "other": 1000.99
  },
  "periodAllowableExpenses": {
    "costOfGoodsAllowable": 1000.99,
    "paymentsToSubcontractorsAllowable": 1000.99,
    "wagesAndStaffCostsAllowable": 1000.99,
    "carVanTravelExpensesAllowable": 1000.99,
    "premisesRunningCostsAllowable": 1000.99,
    "maintenanceCostsAllowable": 1000.99,
    "adminCostsAllowable": 1000.99,
    "businessEntertainmentCostsAllowable": 1000.99,
    "advertisingCostsAllowable": 1000.99,
    "interestOnBankOtherLoansAllowable": 1000.99,
    "financeChargesAllowable": 1000.99,
    "irrecoverableDebtsAllowable": 1000.99,
    "professionalFeesAllowable": 1000.99,
    "depreciationAllowable": 1000.99,
    "otherExpensesAllowable": 1000.99
  },
  "periodDisallowableExpenses": {
    "costOfGoodsDisallowable": 1000.99,
    "paymentsToSubcontractorsDisallowable": 1000.99,
    "wagesAndStaffCostsDisallowable": 1000.99,
    "carVanTravelExpensesDisallowable": 1000.99,
    "premisesRunningCostsDisallowable": 1000.99,
    "maintenanceCostsDisallowable": 1000.99,
    "adminCostsDisallowable": 1000.99,
    "businessEntertainmentCostsDisallowable": 1000.99,
    "advertisingCostsDisallowable": 1000.99,
    "interestOnBankOtherLoansDisallowable": 1000.99,
    "financeChargesDisallowable": 1000.99,
    "irrecoverableDebtsDisallowable": 1000.99,
    "professionalFeesDisallowable": 1000.99,
    "depreciationDisallowable": 1000.99,
    "otherExpensesDisallowable": 1000.99
  }
}

Request table
Name Description
periodIncome
object
optional

Object containing the details about self-employment income.

turnover
number
optional

The takings, fees, sales or money earned by your business. Income associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

other
number
optional

Any other business income not included in turnover. Income associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

periodAllowableExpenses
object
optional

Object containing the details about self-employment allowable expenses.

consolidatedExpenses
number
optional

The sum of all expenses for the specified period. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

costOfGoodsAllowable
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 up to 2 decimal places.

For example: 10000.00

paymentsToSubcontractorsAllowable
number
optional

Payments to construction Industry subcontractors. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.00

wagesAndStaffCostsAllowable
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 up to 2 decimal places.

For example: 10000.00

carVanTravelExpensesAllowable
number
optional

Car, van and travel expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

premisesRunningCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

maintenanceCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

adminCostsAllowable
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 up to 2 decimal places.

For example: 10000.89

businessEntertainmentCostsAllowable
number
optional

Business entertainment costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

advertisingCostsAllowable
number
optional

Advertising costs. Expenses associated with the running of the business. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

interestOnBankOtherLoansAllowable
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 up to 2 decimal places.

For example: 10000.89

financeChargesAllowable
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 up to 2 decimal places.

For example: 10000.89

irrecoverableDebtsAllowable
number
optional

Irrecoverable debts written off. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

professionalFeesAllowable
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 up to 2 decimal places.

For example: 10000.89

depreciationAllowable
number
optional

Depreciation and loss/profit on sales of assets. Expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

otherExpensesAllowable
number
optional

Other business expenses associated with the running of the business. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

periodDisallowableExpenses
object
optional

Object containing the details about self-employment disallowable expenses that cannot be claimed for tax purposes.

costOfGoodsDisallowable
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 up to 2 decimal places.

For example: 10000.45

paymentsToSubcontractorsDisallowable
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 up to 2 decimal places.

For example: 10000.89

wagesAndStaffCostsDisallowable
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 up to 2 decimal places.

For example: 10000.89

carVanTravelExpensesDisallowable
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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

interestOnBankOtherLoansDisallowable
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 up to 2 decimal places.

For example: 10000.89

financeChargesDisallowable
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 up to 2 decimal places.

For example: 10000.89

irrecoverableDebtsDisallowable
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 up to 2 decimal places.

For example: 10000.89

professionalFeesDisallowable
number
optional

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 up to 2 decimal places.

For example: 10000.89

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 up to 2 decimal places.

For example: 10000.89

otherExpensesDisallowable
number
optional

Other business expenses. Any expense or partial expense that cannot be claimed for tax purposes. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 10000.89

Responses

HTTP status 200 (OK)

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response

{
  "links": [
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel": "amend-self-employment-period-summary",
      "method": "PUT"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/business/self-employment/TC663795B/XAIS12345678910/period",
      "rel": "list-self-employment-period-summaries",
      "method": "GET"
    }
  ]
}

Response table
Name Description
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /individuals/business/self-employment/TC663795B/XAIS12345678910/period/2019-06-12_2020-06-12

method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET
PUT
rel
string
required

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

Limited to the following possible values:

amend-self-employment-period-summary
list-self-employment-period-summaries
self

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

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

400 (Bad Request)

FORMAT_BUSINESS_ID

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

400 (Bad Request)

FORMAT_PERIOD_ID

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

400 (Bad Request)

FORMAT_VALUE

An empty or non-matching body was submitted.

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

Both expenses and consolidatedExpenses can not be present at the same time.

400 (Bad Request)

RULE_BOTH_EXPENSES_SUPPLIED

Consolidated expenses are not allowed if the accumulative turnover amount exceeds the threshold.

400 (Bad Request)

RULE_NOT_ALLOWED_CONSOLIDATED_EXPENSES

The client and/or agent is not authorised. This is normally 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 matching resource is not found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response with full expenses.

NOT_ALLOWED_CONSOLIDATED_EXPENSES

Simulates the scenario where the cumulative turnover amount exceeds the consolidated expenses threshold.

NOT_FOUND

Simulates the scenario where no data is found.


Close Section

Skip to main content