This version is in beta - expect some breaking changes.

Individual Calculations (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 Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

This API allows a developer to:

  • trigger a customer’s self assessment tax calculation
  • list a customer’s self assessment tax calculations for a tax year
  • retrieve a customer’s self assessment tax calculation result
  • submit a self assessment final declaration for a tax year

In previous versions, the term ‘crystallise’ was used to mean submit a final declaration, and the term ‘intent to crystallise’ was used to mean trigger a final declaration self-assessment tax calculation.

For information on how to connect to this API see the Income Tax MTD end-to-end service guide.

Send fraud prevention data

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

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

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

Versioning

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

Errors

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

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

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

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

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

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

Tax Calculations

Here a developer can:

  • list self-assessment tax calculations for a given National Insurance number (NINO) and tax year
  • trigger a self-assessment tax calculation for a given tax year
  • retrieve all the tax calculation data for a given NINO and Calculation ID

Tax Calculations resources

/individuals/calculations/{nino}/self-assessment

List Self Assessment Tax Calculations
GET

This endpoint allows the developer to list their Self Assessment tax calculations for a given NINO and tax year. The National Insurance number 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

Query parameters

Query parameters table
Name Description
taxYear
string
optional

The tax year the data applies to, for example, 2021-22. 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, 2020-22 is not valid.

For example: 2017-18

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

{
  "calculations": [
    {
      "calculationId": "c432a56d-e811-474c-a26a-76fc3bcaefe5",
      "calculationTimestamp": "2021-07-12T07:51:43.112Z",
      "calculationType": "finalDeclaration",
      "requestedBy": "customer",
      "taxYear": "2021-22",
      "totalIncomeTaxAndNicsDue": 10000.12,
      "intentToSubmitFinalDeclaration": true,
      "finalDeclaration": true,
      "finalDeclarationTimestamp": "2021-07-13T07:51:43.112Z",
      "links": [
        {
          "href": "/individuals/calculations/TC663795B/self-assessment/2021-22/c432a56d-e811-474c-a26a-76fc3bcaefe5",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "calculationTimestamp": "2021-06-22T08:53:44.122Z",
      "calculationType": "inYear",
      "requestedBy": "customer",
      "taxYear": "2021-22",
      "totalIncomeTaxAndNicsDue": 10000.12,
      "intentToSubmitFinalDeclaration": false,
      "finalDeclaration": false,
      "links": [
        {
          "href": "/individuals/calculations/TC663795B/self-assessment/2021-22/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/TC663795B/self-assessment/2021-22",
      "rel": "trigger",
      "method": "POST"
    },
    {
      "href": "/individuals/calculations/TC663795B/self-assessment",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response table
Name Description
calculations
array
required

The array holding calculation details.

calculationId
string
required

The unique identifier of the 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

calculationTimestamp
string
required

The timestamp of when the calculation was performed in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-07-13T07:51:43.112Z

calculationType
string
required

The type of calculation performed.

Limited to the following possible values:

inYear
finalDeclaration
biss
requestedBy
string
optional

The requestor of the calculation. Currently agent will default to customer until it can be supported.

Limited to the following possible values:

customer
hmrc
agent
taxYear
string
optional

The tax year the calculation was requested for.

Tax year in the format YYYY-YY

For example: 2020-21

totalIncomeTaxAndNicsDue
number
required

The total amount of Income Tax and National Insurance Contributions due. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

intentToSubmitFinalDeclaration
boolean
optional

A boolean to indicate whether the calculation can be used to make a final declaration. This value must be true or false.

For example: false

finalDeclaration
boolean
optional

A boolean to indicate whether the calculation has been used to make a final declaration. This value must be true or false.

For example: false

finalDeclarationTimestamp
string
optional

The timestamp of when the final calculation was performed, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-07-13T07:51:43.112Z

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/calculations/TC663795B/self-assessment/2020-21/c432a56d-e811-474c-a26a-76fc3bcaefe5

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/calculations/TC663795B/self-assessment

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
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 taxYear value is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

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

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

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

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The request did not match any available Sandbox data. Check that the supplied Gov-Test-Scenario is correct for this endpoint version. This error will only be returned in the Sandbox environment.

400 (Bad Request)

RULE_INCORRECT_GOV_TEST_SCENARIO

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

No tax calculations can be found for the supplied NINO and tax year.

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/calculations/{nino}/self-assessment/{taxYear}

Trigger a Self Assessment Tax Calculation
POST

This endpoint allows the user to trigger a self assessment tax calculation for a given tax year. It should be called whenever income data is updated through a periodic or annual endpoint. To trigger a final declaration self assessment tax calculation, you must supply the finalDeclaration query parameter as true.

A National Insurance number and tax year must be provided. The tax calculation process is asynchronous, so it is recommended you wait at least 5 seconds before calling the retrieval endpoint. The result of the calculation can be seen using the “Retrieve a Self Assessment Tax Calculation” endpoint.

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

taxYear
string
required

The tax year the data applies to, for example, 2021-22. 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, 2020-22 is not valid.

For example: 2021-22

Query parameters

Query parameters table
Name Description
finalDeclaration
string
optional

Must be sent as “true” when the user is ready to submit a final declaration. Acceptable values are “true” and “false”.

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.3.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 202 (Accepted)

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.

{
  "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment",
      "rel": "list",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/2020-21/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response table
Name Description
calculationId
string
required

The unique identifier of the 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/calculations/TC663795B/self-assessment/2020-21/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

rel
string
required

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

Limited to the following possible values:

list
self
method
string
required

The HTTP method type for the endpoint.

Limited to the following possible values:

GET

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 taxYear value is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of the supplied finalDeclaration value is not valid.

400 (Bad Request)

FORMAT_FINAL_DECLARATION

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

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

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

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The request did not match any available Sandbox data. Check that the supplied Gov-Test-Scenario is correct for this endpoint version. This error will only be returned in the Sandbox environment.

400 (Bad Request)

RULE_INCORRECT_GOV_TEST_SCENARIO

A calculation could not be performed because no income data has been submitted against the tax year.

403 (Forbidden)

RULE_NO_INCOME_SUBMISSIONS_EXIST

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

Final declaration has already been received.

403 (Forbidden)

RULE_FINAL_DECLARATION_RECEIVED

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.

NO_INCOME_SUBMISSIONS_EXIST

Simulates the scenario where no income submissions exist for the tax year.

FINAL_DECLARATION_RECEIVED

Simulates the scenario where a final declaration has already been received.


Close Section
/individuals/calculations/{nino}/self-assessment/{taxYear}/{calculationId}

Retrieve a Self Assessment Tax Calculation
GET

This endpoint allows the developer to retrieve all the tax calculation data for a given NINO and Calculation ID.

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

taxYear
string
required

The tax year the data applies to, for example, 2021-22. 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, 2020-22 is not valid.

For example: 2021-22

calculationId
string
required

The unique identifier of the 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

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

{
  "metadata": {
    "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
    "taxYear": "2021-22",
    "requestedBy": "customer",
    "requestedTimestamp": "2021-02-15T09:35:15.094Z",
    "calculationReason": "customerRequest",
    "calculationTimestamp": "2021-08-15T09:35:15.094Z",
    "calculationType": "finalDeclaration",
    "intentToSubmitFinalDeclaration": true,
    "finalDeclaration": true,
    "finalDeclarationTimestamp": "2021-02-15T09:35:15.094Z",
    "periodFrom": "2021-04-06",
    "periodTo": "2022-04-05"
  },
  "inputs": {
    "personalInformation": {
      "identifier": "VO123456A",
      "dateOfBirth": "1988-08-27",
      "taxRegime": "UK",
      "statePensionAgeDate": "2050-04-06",
      "studentLoanPlan": [
        {
          "planType": "plan1"
        }
      ],
      "class2VoluntaryContributions": true,
      "marriageAllowance": "transferor",
      "uniqueTaxpayerReference": "AGvHTfRUPO"
    },
    "incomeSources": {
      "businessIncomeSources": [
        {
          "incomeSourceId": "XBIS12345678910",
          "incomeSourceType": "self-employment",
          "incomeSourceName": "Self-Employment Business One",
          "accountingPeriodStartDate": "2021-04-06",
          "accountingPeriodEndDate": "2022-04-05",
          "source": "MTD-SA",
          "latestPeriodEndDate": "2022-04-05",
          "latestReceivedDateTime": "2022-12-02T15:25:48.475Z",
          "finalised": true,
          "finalisationTimestamp": "2022-02-15T09:35:15.094Z",
          "submissionPeriods": [
            {
              "periodId": "001",
              "startDate": "2021-04-06",
              "endDate": "2022-07-05",
              "receivedDateTime": "2022-02-15T09:35:04.843Z"
            }
          ]
        }
      ],
      "nonBusinessIncomeSources": [
        {
          "incomeSourceId": "XPIS12345678910",
          "incomeSourceType": "uk-savings-and-gains",
          "incomeSourceName": "Savings Account One",
          "startDate": "2021-04-06",
          "endDate": "2022-04-05",
          "source": "MTD-SA",
          "periodId": "001",
          "latestReceivedDateTime": "2022-08-01T13:02:09.775Z"
        }
      ]
    },
    "annualAdjustments": [
      {
        "incomeSourceId": "XBIS12345678910",
        "incomeSourceType": "self-employment",
        "bsasId": "123a456b-789c-1d23-845e-678b9d1bd2ab",
        "receivedDateTime": "2022-12-02T15:25:48.475Z",
        "applied": true
      }
    ],
    "lossesBroughtForward": [
      {
        "lossId": "0yriP9QrW2jTa6n",
        "incomeSourceId": "XBIS12345678910",
        "incomeSourceType": "self-employment",
        "submissionTimestamp": "2022-12-02T15:25:48.475Z",
        "lossType": "income",
        "taxYearLossIncurred": "2020-21",
        "currentLossValue": 12500,
        "mtdLoss": false
      }
    ],
    "claims": [
      {
        "claimId": "0vayS9JrW2jTa6n",
        "originatingClaimId": "1vayS9JrW2jTa6p",
        "incomeSourceId": "000000000000210",
        "incomeSourceType": "self-employment",
        "submissionTimestamp": "2022-12-02T15:25:48.475Z",
        "taxYearClaimMade": "2021-22",
        "claimType": "carry-forward",
        "sequence": 1
      }
    ],
    "constructionIndustryScheme": [
      {
        "employerRef": "123/AA12345",
        "contractorName": "Company-123 Ltd.",
        "periodData": [
          {
            "deductionFromDate": "2021-11-02",
            "deductionToDate": "2021-12-02",
            "submissionTimestamp": "2021-12-10T15:25:48.475Z",
            "source": "contractor",
            "deductionAmount": 5000.99
          }
        ]
      }
    ],
    "allowancesReliefsAndDeductions": [
      {
        "type": "investmentReliefs",
        "submittedTimestamp": "2021-12-10T15:25:48.475Z",
        "startDate": "2021-11-02",
        "endDate": "2021-12-02",
        "source": "MTD-SA"
      }
    ],
    "pensionContributionAndCharges": [
      {
        "type": "pensionReliefs",
        "submissionTimestamp": "2021-12-10T15:25:48.475Z",
        "startDate": "2021-11-02",
        "endDate": "2021-12-02",
        "source": "customer"
      }
    ],
    "other": [
      {
        "type": "codingOut",
        "submittedOn": "2021-12-04T15:25:48.475Z"
      }
    ]
  },
  "calculation": {
    "allowancesAndDeductions": {
      "personalAllowance": 12500,
      "marriageAllowanceTransferOut": {
        "personalAllowanceBeforeTransferOut": 5000.99,
        "transferredOutAmount": 5000.99
      },
      "reducedPersonalAllowance": 12500,
      "giftOfInvestmentsAndPropertyToCharity": 12500,
      "blindPersonsAllowance": 12500,
      "lossesAppliedToGeneralIncome": 12500,
      "cgtLossSetAgainstInYearGeneralIncome": 12500,
      "qualifyingLoanInterestFromInvestments": 5000.99,
      "postCessationTradeReceipts": 5000.99,
      "paymentsToTradeUnionsForDeathBenefits": 5000.99,
      "grossAnnuityPayments": 5000.99,
      "annuityPayments": {
        "reliefClaimed": 5000.99,
        "rate": 20.99
      },
      "pensionContributions": 5000.99,
      "pensionContributionsDetail": {
        "retirementAnnuityPayments": 5000.99,
        "paymentToEmployersSchemeNoTaxRelief": 5000.99,
        "overseasPensionSchemeContributions": 5000.99
      }
    },
    "reliefs": {
      "residentialFinanceCosts": {
        "adjustedTotalIncome": 5000.99,
        "totalAllowableAmount": 5000.99,
        "relievableAmount": 5000.99,
        "rate": 20.99,
        "totalResidentialFinanceCostsRelief": 5000.99,
        "ukProperty": {
          "amountClaimed": 12500,
          "allowableAmount": 5000.99,
          "carryForwardAmount": 5000.99
        },
        "foreignProperty": {
          "totalForeignPropertyAllowableAmount": 5000.99,
          "foreignPropertyRfcDetail": [
            {
              "countryCode": "FRA",
              "amountClaimed": 12500,
              "allowableAmount": 5000.99,
              "carryForwardAmount": 5000.99
            }
          ]
        },
        "allOtherIncomeReceivedWhilstAbroad": {
          "totalOtherIncomeAllowableAmount": 5000.99,
          "otherIncomeRfcDetail": [
            {
              "countryCode": "FRA",
              "residentialFinancialCostAmount": 5000.99,
              "broughtFwdResidentialFinancialCostAmount": 5000.99
            }
          ]
        }
      },
      "reliefsClaimed": [
        {
          "type": "vctSubscriptions",
          "amountClaimed": 5000.99,
          "allowableAmount": 5000.99,
          "amountUsed": 5000.99,
          "rate": 20.99,
          "reliefsClaimedDetail": [
            {
              "amountClaimed": 5000.99,
              "uniqueInvestmentRef": "BAO123456A",
              "name": "VCT fund",
              "socialEnterpriseName": "SE Inc",
              "companyName": "Company Ltd.",
              "deficiencyReliefType": "lifeInsurance",
              "customerReference": "INPOLY123A"
            }
          ]
        }
      ],
      "foreignTaxCreditRelief": {
        "customerCalculatedRelief": true,
        "totalForeignTaxCreditRelief": 5000.99,
        "foreignTaxCreditReliefOnProperty": 5000.99,
        "foreignTaxCreditReliefOnDividends": 5000.99,
        "foreignTaxCreditReliefOnSavings": 5000.99,
        "foreignTaxCreditReliefOnForeignIncome": 5000.99,
        "foreignTaxCreditReliefDetail": [
          {
            "incomeSourceType": "foreign-dividends",
            "incomeSourceId": "XFIS12345678910",
            "countryCode": "FRA",
            "foreignIncome": 5000.99,
            "foreignTax": 5000.99,
            "dtaRate": 20.99,
            "dtaAmount": 5000.99,
            "ukLiabilityOnIncome": 5000.99,
            "foreignTaxCredit": 5000.99,
            "employmentLumpSum": true
          }
        ]
      },
      "topSlicingRelief": {
        "amount": 5000.99
      }
    },
    "taxDeductedAtSource": {
      "bbsi": 5000.99,
      "ukLandAndProperty": 5000.99,
      "cis": 5000.99,
      "securities": 5000.99,
      "voidedIsa": 5000.99,
      "payeEmployments": 5000.99,
      "occupationalPensions": 5000.99,
      "stateBenefits": -99999999999.99,
      "specialWithholdingTaxOrUkTaxPaid": 5000.99,
      "inYearAdjustmentCodedInLaterTaxYear": 5000.99
    },
    "giftAid": {
      "grossGiftAidPayments": 12500,
      "rate": 20.99,
      "giftAidTax": 5000.99,
      "giftAidTaxReductions": 5000.99,
      "incomeTaxChargedAfterGiftAidTaxReductions": 5000.99,
      "giftAidCharge": 5000.99
    },
    "royaltyPayments": {
      "royaltyPaymentsAmount": 12500,
      "rate": 20.99,
      "grossRoyaltyPayments": 12500
    },
    "notionalTax": {
      "chargeableGains": 5000.99
    },
    "marriageAllowanceTransferredIn": {
      "amount": 5000.99,
      "rate": 20.99
    },
    "pensionContributionReliefs": {
      "totalPensionContributionReliefs": 5000.99,
      "pensionContributionDetail": {
        "regularPensionContributions": 5000.99,
        "oneOffPensionContributionsPaid": 5000.99
      }
    },
    "pensionSavingsTaxCharges": {
      "totalPensionCharges": 5000.99,
      "totalTaxPaid": 5000.99,
      "totalPensionChargesDue": 5000.99,
      "pensionSavingsTaxChargesDetail": {
        "excessOfLifeTimeAllowance": {
          "totalChargeableAmount": 5000.99,
          "totalTaxPaid": 5000.99,
          "lumpSumBenefitTakenInExcessOfLifetimeAllowance": {
            "amount": 5000.99,
            "taxPaid": 5000.99,
            "rate": 20.99,
            "chargeableAmount": 5000.99
          },
          "benefitInExcessOfLifetimeAllowance": {
            "amount": 5000.99,
            "taxPaid": 5000.99,
            "rate": 20.99,
            "chargeableAmount": 5000.99
          }
        },
        "pensionSchemeUnauthorisedPayments": {
          "totalChargeableAmount": 5000.99,
          "totalTaxPaid": 5000.99,
          "pensionSchemeUnauthorisedPaymentsSurcharge": {
            "amount": 5000.99,
            "taxPaid": 5000.99,
            "rate": 20.99,
            "chargeableAmount": 5000.99
          },
          "pensionSchemeUnauthorisedPaymentsNonSurcharge": {
            "amount": 5000.99,
            "taxPaid": 5000.99,
            "rate": 20.99,
            "chargeableAmount": 5000.99
          }
        },
        "pensionSchemeOverseasTransfers": {
          "transferCharge": 5000.99,
          "transferChargeTaxPaid": 5000.99,
          "rate": 20.99,
          "chargeableAmount": 5000.99
        },
        "pensionContributionsInExcessOfTheAnnualAllowance": {
          "totalContributions": 5000.99,
          "totalPensionCharge": 5000.99,
          "annualAllowanceTaxPaid": 5000.99,
          "totalPensionChargeDue": 5000.99,
          "pensionBands": [
            {
              "name": "basic-rate",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "contributionAmount": 5000.99,
              "pensionCharge": 5000.99
            }
          ]
        },
        "overseasPensionContributions": {
          "totalShortServiceRefund": 5000.99,
          "totalShortServiceRefundCharge": 5000.99,
          "shortServiceRefundTaxPaid": 5000.99,
          "totalShortServiceRefundChargeDue": 5000.99,
          "shortServiceRefundBands": [
            {
              "name": "lowerBand",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "shortServiceRefundAmount": 5000.99,
              "shortServiceRefundCharge": 5000.99
            }
          ]
        }
      }
    },
    "studentLoans": [
      {
        "planType": "plan1",
        "studentLoanTotalIncomeAmount": 5000.99,
        "studentLoanChargeableIncomeAmount": 5000.99,
        "studentLoanRepaymentAmount": 5000.99,
        "studentLoanDeductionsFromEmployment": 5000.99,
        "studentLoanRepaymentAmountNetOfDeductions": 5000.99,
        "studentLoanApportionedIncomeThreshold": 12500,
        "studentLoanRate": 20.99,
        "payeIncomeForStudentLoan": 5000.99,
        "nonPayeIncomeForStudentLoan": 5000.99
      }
    ],
    "codedOutUnderpayments": {
      "totalPayeUnderpayments": 5000.99,
      "payeUnderpaymentsDetail": [
        {
          "amount": 5000.99,
          "relatedTaxYear": "2021-22",
          "source": "customer"
        }
      ],
      "totalSelfAssessmentUnderpayments": 5000.99,
      "totalCollectedSelfAssessmentUnderpayments": 5000.99,
      "totalUncollectedSelfAssessmentUnderpayments": 5000.99,
      "selfAssessmentUnderpaymentsDetail": [
        {
          "amount": 5000.99,
          "relatedTaxYear": "2021-22",
          "source": "customer",
          "collectedAmount": 5000.99,
          "uncollectedAmount": 5000.99
        }
      ]
    },
    "foreignPropertyIncome": [
      {
        "incomeSourceId": "XFIS12345678911",
        "incomeSourceType": "foreign-property",
        "countryCode": "USA",
        "totalIncome": 5000.99,
        "totalExpenses": 5000.99,
        "netProfit": 5000.99,
        "netLoss": 5000.99,
        "totalAdditions": 5000.99,
        "totalDeductions": 5000.99,
        "taxableProfit": 5000.99,
        "adjustedIncomeTaxLoss": 5000.99
      }
    ],
    "businessProfitAndLoss": [
      {
        "incomeSourceId": "XBIS12345678911",
        "incomeSourceType": "self-employment",
        "incomeSourceName": "Self-Employment Business One",
        "totalIncome": 5000.99,
        "totalExpenses": -99999999999.99,
        "netProfit": 5000.99,
        "netLoss": 5000.99,
        "totalAdditions": -99999999999.99,
        "totalDeductions": 5000.99,
        "accountingAdjustments": -99999999999.99,
        "taxableProfit": 12500,
        "adjustedIncomeTaxLoss": 12500,
        "totalBroughtForwardIncomeTaxLosses": 12500,
        "lossForCSFHL": 12500,
        "broughtForwardIncomeTaxLossesUsed": 12500,
        "taxableProfitAfterIncomeTaxLossesDeduction": 12500,
        "carrySidewaysIncomeTaxLossesUsed": 12500,
        "broughtForwardCarrySidewaysIncomeTaxLossesUsed": 12500,
        "totalIncomeTaxLossesCarriedForward": 12500,
        "class4Loss": 12500,
        "totalBroughtForwardClass4Losses": 12500,
        "broughtForwardClass4LossesUsed": 12500,
        "carrySidewaysClass4LossesUsed": 12500,
        "totalClass4LossesCarriedForward": 12500
      }
    ],
    "employmentAndPensionsIncome": {
      "totalPayeEmploymentAndLumpSumIncome": 5000.99,
      "totalOccupationalPensionIncome": 5000.99,
      "totalBenefitsInKind": 5000.99,
      "tipsIncome": 5000.99,
      "employmentAndPensionsIncomeDetail": [
        {
          "incomeSourceId": "bb74c290-cae6-11ec-9b64-0242ac120002",
          "source": "customer",
          "occupationalPension": true,
          "employerRef": "123/AA12345",
          "employerName": "Green Ltd.",
          "payrollId": "YDIAHPcYFQbOXLCKQ",
          "startDate": "2021-01-02",
          "dateEmploymentEnded": "2021-12-02",
          "taxablePayToDate": 5000.99,
          "totalTaxToDate": -99999999999.99,
          "disguisedRemuneration": true,
          "lumpSums": {
            "totalLumpSum": 5000.99,
            "totalTaxPaid": 5000.99,
            "lumpSumsDetail": {
              "taxableLumpSumsAndCertainIncome": {
                "amount": 5000.99,
                "taxPaid": 5000.99,
                "taxTakenOffInEmployment": true
              },
              "benefitFromEmployerFinancedRetirementScheme": {
                "amount": 5000.99,
                "exemptAmount": 5000.99,
                "taxPaid": 5000.99,
                "taxTakenOffInEmployment": true
              },
              "redundancyCompensationPaymentsOverExemption": {
                "amount": 5000.99,
                "taxPaid": 5000.99,
                "taxTakenOffInEmployment": true
              },
              "redundancyCompensationPaymentsUnderExemption": {
                "amount": 5000.99
              }
            }
          },
          "studentLoans": {
            "uglDeductionAmount": 5000.99,
            "pglDeductionAmount": 5000.99
          },
          "benefitsInKind": {
            "totalBenefitsInKindReceived": 5000.99,
            "benefitsInKindDetail": {
              "apportionedAccommodation": 5000.99,
              "apportionedAssets": 5000.99,
              "apportionedAssetTransfer": 5000.99,
              "apportionedBeneficialLoan": 5000.99,
              "apportionedCar": 5000.99,
              "apportionedCarFuel": 5000.99,
              "apportionedEducationalServices": 5000.99,
              "apportionedEntertaining": 5000.99,
              "apportionedExpenses": 5000.99,
              "apportionedMedicalInsurance": 5000.99,
              "apportionedTelephone": 5000.99,
              "apportionedService": 5000.99,
              "apportionedTaxableExpenses": 5000.99,
              "apportionedVan": 5000.99,
              "apportionedVanFuel": 5000.99,
              "apportionedMileage": 5000.99,
              "apportionedNonQualifyingRelocationExpenses": 5000.99,
              "apportionedNurseryPlaces": 5000.99,
              "apportionedOtherItems": 5000.99,
              "apportionedPaymentsOnEmployeesBehalf": 5000.99,
              "apportionedPersonalIncidentalExpenses": 5000.99,
              "apportionedQualifyingRelocationExpenses": 5000.99,
              "apportionedEmployerProvidedProfessionalSubscriptions": 5000.99,
              "apportionedEmployerProvidedServices": 5000.99,
              "apportionedIncomeTaxPaidByDirector": 5000.99,
              "apportionedTravelAndSubsistence": 5000.99,
              "apportionedVouchersAndCreditCards": 5000.99,
              "apportionedNonCash": 5000.99
            }
          }
        }
      ]
    },
    "employmentExpenses": {
      "totalEmploymentExpenses": 5000.99,
      "employmentExpensesDetail": {
        "businessTravelCosts": 5000.99,
        "jobExpenses": 5000.99,
        "flatRateJobExpenses": 5000.99,
        "professionalSubscriptions": 5000.99,
        "hotelAndMealExpenses": 5000.99,
        "otherAndCapitalAllowances": 5000.99,
        "vehicleExpenses": 5000.99,
        "mileageAllowanceRelief": 5000.99
      }
    },
    "seafarersDeductions": {
      "totalSeafarersDeduction": 5000.99,
      "seafarersDeductionDetail": [
        {
          "nameOfShip": "Blue Bell",
          "amountDeducted": 5000.99
        }
      ]
    },
    "foreignTaxForFtcrNotClaimed": {
      "foreignTaxOnForeignEmployment": 5000.99
    },
    "stateBenefitsIncome": {
      "totalStateBenefitsIncome": 5000.99,
      "totalStateBenefitsTaxPaid": -99999999999.99,
      "stateBenefitsDetail": {
        "incapacityBenefit": [
          {
            "incomeSourceId": "bc51a3eb-e374-11b9-aa02-96db92561138",
            "amount": 5000.99,
            "taxPaid": 5000.99,
            "source": "customer"
          }
        ],
        "statePension": [
          {
            "incomeSourceId": "cb74c290-cae6-11ec-bb64-0242ac121114",
            "amount": 5000.99,
            "source": "customer"
          }
        ],
        "statePensionLumpSum": [
          {
            "incomeSourceId": "dc45c178-bac5-22ec-9b65-1351bd140002",
            "amount": 5000.99,
            "taxPaid": 5000.99,
            "rate": 20.99,
            "source": "customer"
          }
        ],
        "employmentSupportAllowance": [
          {
            "incomeSourceId": "e4bf331e-0e55-297f-8a74-c766674775d4",
            "amount": 5000.99,
            "taxPaid": -99999999999.99,
            "source": "customer"
          }
        ],
        "jobSeekersAllowance": [
          {
            "incomeSourceId": "f4af222e-0b44-286f-9a65-c655674776d8",
            "amount": 5000.99,
            "taxPaid": -99999999999.99,
            "source": "customer"
          }
        ],
        "bereavementAllowance": [
          {
            "incomeSourceId": "ae99d345-dab5-25dc-9b19-0252bc322252",
            "amount": 5000.99,
            "source": "customer"
          }
        ],
        "otherStateBenefits": [
          {
            "incomeSourceId": "bf87eb89-3d07-1496-89da-cf16d45c934b",
            "amount": 5000.99,
            "source": "customer"
          }
        ]
  }
    },
    "shareSchemesIncome": {
      "totalIncome": 5000.99,
      "shareSchemeDetail": [
        {
          "type": "shareOption",
          "employerName": "ABC-123 Ltd.",
          "employerRef": "123/AB56797",
          "taxableAmount": 5000.99
        }
      ]
    },
    "foreignIncome": {
      "chargeableOverseasPensionsStateBenefitsRoyalties": 5000.99,
      "overseasPensionsStateBenefitsRoyaltiesDetail": [
        {
          "countryCode": "FRA",
          "grossIncome": 5000.99,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99,
          "foreignTaxCreditRelief": true
        }
      ],
      "chargeableAllOtherIncomeReceivedWhilstAbroad": 5000.99,
      "allOtherIncomeReceivedWhilstAbroadDetail": [
        {
          "countryCode": "FRA",
          "grossIncome": 5000.99,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99,
          "foreignTaxCreditRelief": true
        }
      ],
      "overseasIncomeAndGains": {
        "gainAmount": 5000.99
      },
      "totalForeignBenefitsAndGifts": 5000.99,
      "chargeableForeignBenefitsAndGiftsDetail": {
        "transactionBenefit": 5000.99,
        "protectedForeignIncomeSourceBenefit": 5000.99,
        "protectedForeignIncomeOnwardGift": 5000.99,
        "benefitReceivedAsASettler": 5000.99,
        "onwardGiftReceivedAsASettler": 5000.99
      }
    },
    "chargeableEventGainsIncome": {
      "totalOfAllGains": 12500,
      "totalGainsWithTaxPaid": 12500,
      "gainsWithTaxPaidDetail": [
        {
          "type": "lifeInsurance",
          "customerReference": "string",
          "gainAmount": 5000.99,
          "yearsHeld": 0,
          "yearsHeldSinceLastGain": 0
        }
      ],
      "totalGainsWithNoTaxPaidAndVoidedIsa": 12500,
      "gainsWithNoTaxPaidAndVoidedIsaDetail": [
        {
          "type": "lifeInsurance",
          "customerReference": "INPOLY123B",
          "gainAmount": 5000.99,
          "yearsHeld": 0,
          "yearsHeldSinceLastGain": 0,
          "voidedIsaTaxPaid": 5000.99
        }
      ],
      "totalForeignGainsOnLifePoliciesTaxPaid": 12500,
      "foreignGainsOnLifePoliciesTaxPaidDetail": [
        {
          "customerReference": "INPOLY123C",
          "gainAmount": 5000.99,
          "taxPaidAmount": 5000.99,
          "yearsHeld": 0
        }
      ],
      "totalForeignGainsOnLifePoliciesNoTaxPaid": 12500,
      "foreignGainsOnLifePoliciesNoTaxPaidDetail": [
        {
          "customerReference": "INPOLY123D",
          "gainAmount": 5000.99,
          "yearsHeld": 0
        }
      ]
    },
    "savingsAndGainsIncome": {
      "totalChargeableSavingsAndGains": 12500,
      "totalUkSavingsAndGains": 12500,
      "ukSavingsAndGainsIncome": [
        {
          "incomeSourceId": "XPIS12345678911",
          "incomeSourceType": "uk-savings-and-gains",
          "incomeSourceName": "My Savings Account One",
          "grossIncome": 5000.99,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99
        }
      ],
      "chargeableForeignSavingsAndGains": 12500,
      "foreignSavingsAndGainsIncome": [
        {
          "incomeSourceType": "foreign-savings-and-gains",
          "countryCode": "DEU",
          "grossIncome": 5000.99,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99,
          "foreignTaxCreditRelief": true
        }
      ]
    },
    "dividendsIncome": {
      "totalChargeableDividends": 12500,
      "totalUkDividends": 12500,
      "ukDividends": {
        "incomeSourceId": "XPIS12345678912",
        "incomeSourceType": "uk-dividends",
        "dividends": 12500,
        "otherUkDividends": 12500
      },
      "otherDividends": [
        {
          "typeOfDividend": "stockDividend",
          "customerReference": "ODPDLY235A",
          "grossAmount": 5000.99
        }
      ],
      "chargeableForeignDividends": 12500,
      "foreignDividends": [
        {
          "incomeSourceType": "foreign-dividends",
          "countryCode": "FRA",
          "grossIncome": 5000.99,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99,
          "foreignTaxCreditRelief": true
        }
      ],
      "dividendIncomeReceivedWhilstAbroad": [
        {
          "incomeSourceType": "foreign-dividends",
          "countryCode": "ITA",
          "grossIncome": 5000.99,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99,
          "foreignTaxCreditRelief": true
        }
      ]
    },
    "incomeSummaryTotals": {
      "totalSelfEmploymentProfit": 12500,
      "totalPropertyProfit": 12500,
      "totalFHLPropertyProfit": 12500,
      "totalUKOtherPropertyProfit": 12500,
      "totalForeignPropertyProfit": 12500,
      "totalEeaFhlProfit": 12500,
      "totalEmploymentIncome": 12500
    },
    "taxCalculation": {
      "incomeTax": {
        "totalIncomeReceivedFromAllSources": 12500,
        "totalAllowancesAndDeductions": 12500,
        "totalTaxableIncome": 12500,
        "payPensionsProfit": {
          "incomeReceived": 12500,
          "allowancesAllocated": 12500,
          "taxableIncome": 12500,
          "incomeTaxAmount": 5000.99,
          "taxBands": [
            {
              "name": "savings-starter-rate",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "income": 12500,
              "taxAmount": 5000.99
            }
          ]
        },
        "savingsAndGains": {
          "incomeReceived": 12500,
          "allowancesAllocated": 12500,
          "taxableIncome": 12500,
          "incomeTaxAmount": 5000.99,
          "taxBands": [
            {
              "name": "savings-starter-rate",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "income": 12500,
              "taxAmount": 5000.99
            }
          ]
        },
        "dividends": {
          "incomeReceived": 12500,
          "allowancesAllocated": 12500,
          "taxableIncome": 12500,
          "incomeTaxAmount": 5000.99,
          "taxBands": [
            {
              "name": "savings-starter-rate",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "income": 12500,
              "taxAmount": 5000.99
            }
          ]
        },
        "lumpSums": {
          "incomeReceived": 12500,
          "allowancesAllocated": 12500,
          "taxableIncome": 12500,
          "incomeTaxAmount": 5000.99,
          "taxBands": [
            {
              "name": "savings-starter-rate",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "income": 12500,
              "taxAmount": 5000.99
            }
          ]
        },
        "gainsOnLifePolicies": {
          "incomeReceived": 12500,
          "allowancesAllocated": 12500,
          "taxableIncome": 12500,
          "incomeTaxAmount": 5000.99,
          "taxBands": [
            {
              "name": "savings-starter-rate",
              "rate": 20.99,
              "bandLimit": 12500,
              "apportionedBandLimit": 12500,
              "income": 12500,
              "taxAmount": 5000.99
            }
          ]
        },
        "incomeTaxCharged": 5000.99,
        "totalReliefs": 5000.99,
        "incomeTaxDueAfterReliefs": -99999999999.99,
        "totalNotionalTax": 5000.99,
        "marriageAllowanceRelief": 5000.99,
        "incomeTaxDueAfterTaxReductions": 5000.99,
        "incomeTaxDueAfterGiftAid": 5000.99,
        "totalPensionSavingsTaxCharges": 5000.99,
        "statePensionLumpSumCharges": 5000.99,
        "payeUnderpaymentsCodedOut": 5000.99,
        "totalIncomeTaxDue": 5000.99
      },
      "nics": {
        "class2Nics": {
          "amount": 5000.99,
          "weeklyRate": 5000.99,
          "weeks": 0,
          "limit": 12500,
          "apportionedLimit": 12500,
          "underSmallProfitThreshold": true,
          "actualClass2Nic": true
        },
        "class4Nics": {
          "totalIncomeLiableToClass4Charge": 12500,
          "totalClass4LossesAvailable": 12500,
          "totalClass4LossesUsed": 12500,
          "totalClass4LossesCarriedForward": 12500,
          "totalIncomeChargeableToClass4": 12500,
          "totalAmount": 5000.99,
          "nic4Bands": [
            {
              "name": "zero-rate",
              "rate": 20.99,
              "threshold": 12500,
              "apportionedThreshold": 12500,
              "income": 12500,
              "amount": 5000.99
            }
          ]
        },
        "nic2NetOfDeductions": -99999999999.99,
        "nic4NetOfDeductions": -99999999999.99,
        "totalNic": -99999999999.99
      },
      "totalTaxDeductedBeforeCodingOut": 5000.99,
      "saUnderpaymentsCodedOut": 5000.99,
      "totalAnnuityPaymentsTaxCharged": 12500,
      "totalRoyaltyPaymentsTaxCharged": 5000.99,
      "totalIncomeTaxNicsCharged": -99999999999.99,
      "totalStudentLoansRepaymentAmount": 5000.99,
      "totalTaxDeducted": -99999999999.99,
      "totalIncomeTaxAndNicsDue": -99999999999.99,
      "capitalGainsTax": {
        "totalCapitalGainsIncome": 5000.99,
        "annualExemptionAmount": 5000.99,
        "totalTaxableGains": 5000.99,
        "businessAssetsDisposalsAndInvestorsRel": {
          "gainsIncome": 5000.99,
          "lossesBroughtForward": 5000.99,
          "lossesArisingThisYear": 5000.99,
          "gainsAfterLosses": 5000.99,
          "annualExemptionAmount": 5000.99,
          "taxableGains": 5000.99,
          "rate": 20.99,
          "taxAmount": 5000.99
        },
        "residentialPropertyAndCarriedInterest": {
          "gainsIncome": 5000.99,
          "lossesBroughtForward": 5000.99,
          "lossesArisingThisYear": 5000.99,
          "gainsAfterLosses": 5000.99,
          "annualExemptionAmount": 5000.99,
          "taxableGains": 5000.99,
          "cgtTaxBands": [
            {
              "name": "lower-rate",
              "rate": 20.99,
              "income": 5000.99,
              "taxAmount": 5000.99
            }
          ],
          "totalTaxAmount": 5000.99
        },
        "otherGains": {
          "gainsIncome": 5000.99,
          "lossesBroughtForward": 5000.99,
          "lossesArisingThisYear": 5000.99,
          "gainsAfterLosses": 5000.99,
          "attributedGains": 5000.99,
          "netGains": 5000.99,
          "annualExemptionAmount": 5000.99,
          "taxableGains": 5000.99,
          "cgtTaxBands": [
            {
              "name": "lower-rate",
              "rate": 20.99,
              "income": 5000.99,
              "taxAmount": 5000.99
            }
          ],
          "totalTaxAmount": 5000.99
        },
        "capitalGainsTaxAmount": 5000.99,
        "adjustments": -99999999999.99,
        "adjustedCapitalGainsTax": 5000.99,
        "foreignTaxCreditRelief": 5000.99,
        "capitalGainsTaxAfterFTCR": 5000.99,
        "taxOnGainsAlreadyPaid": 5000.99,
        "capitalGainsTaxDue": 5000.99,
        "capitalGainsOverpaid": 5000.99
      },
      "totalIncomeTaxAndNicsAndCgt": 5000.99
    },
    "previousCalculation": {
      "calculationTimestamp": "2021-12-02T15:25:48.475Z",
      "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "totalIncomeTaxAndNicsDue": -99999999999.99,
      "cgtTaxDue": 5000.99,
      "totalIncomeTaxAndNicsAndCgtDue": 5000.99,
      "incomeTaxNicDueThisPeriod": -99999999999.99,
      "cgtDueThisPeriod": 99999999999.99,
      "totalIncomeTaxAndNicsAndCgtDueThisPeriod": 5000.99
    },
    "endOfYearEstimate": {
      "incomeSource": [
        {
          "incomeSourceId": "XBIS12345678920",
          "incomeSourceType": "self-employment",
          "incomeSourceName": "Self-Employment Business One",
          "taxableIncome": 12500,
          "finalised": true
        }
      ],
      "totalEstimatedIncome": 12500,
      "totalTaxableIncome": 12500,
      "incomeTaxAmount": 5000.99,
      "nic2": 5000.99,
      "nic4": 5000.99,
      "totalTaxDeductedBeforeCodingOut": 5000.99,
      "saUnderpaymentsCodedOut": 5000.99,
      "totalNicAmount": 5000.99,
      "totalStudentLoansRepaymentAmount": 5000.99,
      "totalAnnuityPaymentsTaxCharged": 5000.99,
      "totalRoyaltyPaymentsTaxCharged": 5000.99,
      "totalTaxDeducted": -99999999999.99,
      "incomeTaxNicAmount": -99999999999.99,
      "cgtAmount": 5000.99,
      "incomeTaxNicAndCgtAmount": 5000.99
    },
    "lossesAndClaims": {
      "resultOfClaimsApplied": [
        {
          "claimId": "0xcuS9JrW2jTa6d",
          "originatingClaimId": "0vbyS9JrW2jTa6x",
          "incomeSourceId": "XBIS12345678915",
          "incomeSourceType": "self-employment",
          "taxYearClaimMade": "2021-22",
          "claimType": "carry-forward",
          "mtdLoss": false,
          "taxYearLossIncurred": "2020-21",
          "lossAmountUsed": 12500,
          "remainingLossValue": 12500,
          "lossType": "income"
        }
      ],
      "unclaimedLosses": [
        {
          "incomeSourceId": "XBIS12345678916",
          "incomeSourceType": "self-employment",
          "taxYearLossIncurred": "2020-21",
          "currentLossValue": 12500,
          "lossType": "income"
        }
      ],
      "carriedForwardLosses": [
        {
          "claimId": "5xpu66JrW2jTa6c",
          "originatingClaimId": "0vXc69prW2jTar6",
          "incomeSourceId": "XBIS12345678917",
          "incomeSourceType": "self-employment",
          "claimType": "carry-forward",
          "taxYearClaimMade": "2021-22",
          "taxYearLossIncurred": "2020-21",
          "currentLossValue": 12500,
          "lossType": "income"
        }
      ],
      "defaultCarriedForwardLosses": [
        {
          "incomeSourceId": "XBIS12345678918",
          "incomeSourceType": "self-employment",
          "taxYearLossIncurred": "2020-21",
          "currentLossValue": 12500
        }
      ],
      "claimsNotApplied": [
        {
          "claimId": "6vry11JrW5jTvxt",
          "incomeSourceId": "XBIS12345678919",
          "incomeSourceType": "self-employment",
          "taxYearClaimMade": "2021-22",
          "claimType": "carry-forward"
        }
      ]
    }
  },
  "messages": {
    "info": [
      {
        "id": "C22203",
        "text": "Class 2 National Insurance has not been charged as your self-employed profits are under the small profit threshold."
      }
    ],
    "warnings": [
      {
        "id": "C11317",
        "text": "Class 4 exemption - calculation has been adjusted Individual’s age is equal to or greater than 16 years old on the 6th April of current tax year"
      }
    ],
    "errors": [
      {
        "id": "C95005",
        "text": "Final confirmation of income and expenses for all business sources has not been provided"
      }
    ]
  },
  "links": [
    {
      "href": "/individuals/calculations/TC663795B/self-assessment/2021-22",
      "rel": "trigger",
      "method": "POST"
    },
    {
      "href": "/individuals/calculations/TC663795B/self-assessment/2021-22/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response table
Name Description
metadata
object
required

Object containing top-level metadata information about the retrieved tax calculation.

calculationId
string
required

The unique identifier of the 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: 717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4

taxYear
string
required

The tax year in which the calculation was performed.

Tax year in the format YYYY-YY

For example: 2022-23

requestedBy
string
required

The requester of the calculation. Currently "customer" will be returned even in the case of an agent submission.

Limited to the following possible values:

customer
hmrc
agent
requestedTimestamp
string
optional

The timestamp of when the calculation was requested in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

calculationReason
string
required

The reason why the calculation was triggered.

Limited to the following possible values:

customerRequest - The calculation was triggered by the customer via software.
class2NICEvent - The calculation was triggered internally by HMRC once the actual Class 2 NIC amount became available. This event is only applicable for an in-year "finalDeclaration" calculation type.
newLossEvent - The calculation was triggered by HMRC on receipt of a new pre-MTD brought forward loss made by the customer. This event is only applicable for a "finalDeclaration" calculation type. This event is not currently supported and will be supported in the future.
newClaimEvent - The calculation was triggered by HMRC on receipt of a new loss claim made by the customer. This event is only applicable for a "finalDeclaration" calculation type. This event is not currently supported and will be supported in the future.
updatedClaimEvent - The calculation was triggered internally by HMRC on receipt of an updated loss claim made by the customer. This event is only applicable for a "finalDeclaration" calculation type. This event is not currently supported and will be supported in the future.
updatedLossEvent - The calculation was triggered internally by HMRC on receipt of an updated pre-MTD brought forward loss made by the customer. This event is only applicable for a "finalDeclaration" calculation type. This event is not currently supported and will be supported in the future.
newAnnualAdjustmentEvent - The calculation was triggered internally by HMRC on receipt of a request for a new adjustable summary calculation by the customer. This event is not currently supported.
updatedAnnualAdjustmentEvent - The calculation was triggered internally by HMRC on receipt of an adjustment to an adjustable summary calculation made by the customer. This event is not currently supported.
unattendedCalculation - HMRC has updated the calculation for you. You can see more details in your record-keeping software.
calculationTimestamp
string
optional

The timestamp of when the calculation was performed in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

calculationType
string
required

The type of calculation performed.

Limited to the following possible values:

inYear - Cannot be used for a final declaration.
finalDeclaration - Can be used when submitting a final declaration.
intentToSubmitFinalDeclaration
boolean
required

A boolean to indicate whether the calculation can be used to make a final declaration. This value must be true or false.

For example: true

finalDeclaration
boolean
required

A boolean to indicate whether the calculation has been used to make a final declaration. This value must be true or false.

For example: false

finalDeclarationTimestamp
string
optional

The timestamp of when the calculation was performed in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

periodFrom
string
required

This defines the earliest date from which the calculation was performed. This will be the accounting period start date (for self-employments) or the tax year start date, whichever occurs first for the income sources supplied.

Date in the format YYYY-MM-DD

For example: 2020-01-01

periodTo
string
required

This defines the latest date to which the calculation was performed and will be the point in the year to which income has been submitted.

Date in the format YYYY-MM-DD

For example: 2020-01-01

inputs
object
required

Object containing the input data supplied for use in the retrieved tax calculation.

personalInformation
object
required

Object containing personal information about the taxpayer for whom the calculation was performed.

identifier
required

Identifies the taxpayer for whom the calculation was performed.

Must conform to the regular expression ^[a-zA-Z0-9]+$

For example: VO123456A

dateOfBirth
string
optional

The date of birth of the taxpayer.

Date in the format YYYY-MM-DD

For example: 2020-01-01

taxRegime
string
required

The tax regime which applies to this calculation.

Limited to the following possible values:

UK
Scotland
Wales
statePensionAgeDate
string
optional

The date the taxpayer qualifies for state pension.

Date in the format YYYY-MM-DD

For example: 2020-01-01

studentLoanPlan
array
optional

An array containing details about student loan plans.

planType
string
required

Student Loan plan type.

Limited to the following possible values:

plan1
plan2
postgraduate
plan4
class2VoluntaryContributions
boolean
optional

A boolean to identify the Class 2 Voluntary Contributions. This value must be true.

For example: true

marriageAllowance
string
optional

Indicates whether the customer has transferred out their allowance or received an allowance.

Limited to the following possible values:

transferor
recipient
uniqueTaxpayerReference
string
optional

The Unique Taxpayer Reference for the customer.

For example: AGvHTfRUPO

incomeSources
object
required

Object containing the income sources used in the retrieved tax calculation.

businessIncomeSources
array
optional

Array containing business income sources used in the retrieved tax calculation.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

Business income source type.

Limited to the following possible values:

self-employment
uk-property-non-fhl
uk-property-fhl
foreign-property
foreign-property-fhl-eea
incomeSourceName
string
optional

The name of the income source.

For example: ABC-123 Ltd.

accountingPeriodStartDate
string
required

The accounting start date of the income source.

Date in the format YYYY-MM-DD

For example: 2020-01-01

accountingPeriodEndDate
string
required

The accounting end date of the income source.

Date in the format YYYY-MM-DD

For example: 2020-01-01

source
string
required

The source of the income data used in this calculation.

Limited to the following possible values:

MTD-SA
latestPeriodEndDate
string
required

The end date of the period for which income has been submitted for the income source.

Date in the format YYYY-MM-DD

For example: 2020-01-01

latestReceivedDateTime
string
required

The latest date & time when this income source had data submitted against it, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

finalised
boolean
optional

A boolean to identify whether the income source is finalised. This value must be true or false.

For example: false

finalisationTimestamp
string
optional

The timestamp of when finalisation was performed, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

submissionPeriods
array
optional

Array containing submission periods for the business income source.

periodId
string
optional

An identifier for the period, unique to the customer.

For example: 001

startDate
string
required

The first day the period covers.

Date in the format YYYY-MM-DD

For example: 2020-01-01

endDate
string
required

The last day the period covers.

Date in the format YYYY-MM-DD

For example: 2020-01-01

receivedDateTime
string
required

The date and time when the income data was received in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

nonBusinessIncomeSources
array
optional

Array containing non-business income sources used in the retrieved tax calculation.

incomeSourceId
string
optional

The unique identifier of the non-business income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

Non-business income source type.

Limited to the following possible values:

employments
foreign-dividends
uk-savings-and-gains
uk-dividends
state-benefits
gains-on-life-policies
foreign-savings-and-gains
other-dividends
uk-securities
other-income
foreign-pension
non-paye-income
capital-gains-tax
charitable-giving
incomeSourceName
optional

The name of the income source.

For example: Savings Account

startDate
string
required

The start date of the income source.

Date in the format YYYY-MM-DD

For example: 2020-01-01

endDate
string
optional

The end date of the income source.

Date in the format YYYY-MM-DD

For example: 2020-01-01

source
string
required

The source of the income data used in this calculation.

Limited to the following possible values:

MTD-SA
periodId
string
optional

An identifier for the period, unique to the customer.

For example: 001

latestReceivedDateTime
string
optional

The date and time when the latest income data was received by the source. This field may not be present for employments for which no pay data has been received. In ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

annualAdjustments
array
optional

An array containing income source annual adjustments for the retrieved tax calculation.

incomeSourceId
string
required

The unique identifier of the annual adjustment income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

Business income source type.

Limited to the following possible values:

self-employment
uk-property-non-fhl
uk-property-fhl
foreign-property
foreign-property-fhl-eea
bsasId
string
required

The unique identifier of the annual adjustment.

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: 123a456b-789c-1d23-845e-678b9d1bd2ab

receivedDateTime
string
required

The latest date of when the adjustment was created, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

applied
boolean
required

A boolean to identify whether the adjustment has been applied to this calculation. This value must be true or false.

For example: true

lossesBroughtForward
array
optional

An array containing losses which have been brought forward into the retrieved tax calculation.

lossId
string
optional

The unique identifier of the loss which the customer declared when joining MTD.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: AAZZ1234567890a

incomeSourceId
string
required

The unique identifier of the loss brought forward income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

The income source type on which the loss was made.

Limited to the following possible values:

self-employment
uk-property-non-fhl
uk-property-fhl
foreign-property
foreign-property-fhl-eea
submissionTimestamp
string
optional

The date and time the loss was recorded in MTD, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

lossType
string
optional

The type of loss.

Limited to the following possible values:

income
class4nics
taxYearLossIncurred
string
required

The tax year that the loss was incurred.

Tax year in the format YYYY-YY

For example: 2020-21

currentLossValue
integer
required

The current value of the loss. This value must be between 0 and 99999999999. No decimals.

For example: 5000

mtdLoss
boolean
optional

A boolean to identify whether the loss was registered by the taxpayer on joining MTD. Only returned when false.

For example: false

claims
array
optional

An array containing claims which have been applied in the retrieved tax calculation.

claimId
string
optional

An identifier for the claim made by the taxpayer.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: 1234568790ABCDE

originatingClaimId
string
optional

An identifier for the claim made by the taxpayer that resulted in this claim.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: 1234568790ABCDE

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

The income source type on which the loss was made.

Limited to the following possible values:

self-employment
uk-property-non-fhl
uk-property-fhl
foreign-property
foreign-property-fhl-eea
submissionTimestamp
string
optional

The date and time the claim was recorded in MTD, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

taxYearClaimMade
string
required

The tax year in which the claim was made.

Tax year in the format YYYY-YY

For example: 2020-21

claimType
string
required

The type of claim made.

Limited to the following possible values:

carry-forward
carry-sideways
carry-forward-to-carry-sideways
carry-sideways-fhl
carry-backwards
carry-backwards-general-income
sequence
integer
optional

The order in which this claim is to be used for a carry-sideways claim. It must be in the range 1 to 99. The sequence must start with 1 and have no gaps.

For example: 1

constructionIndustryScheme
array
optional

An array containing information about Construction Industry Scheme (CIS) deduction periods by contractor reference.

employerRef
string
required

A unique identifier, the contractor reference number.

Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$

For example: 123/AB56797

contractorName
optional

The name of the contractor the subcontractor worked for.

Must conform to the regular expression ^[A-Za-z0-9 \-,.&'/]{1,105}$

For example: Company-123 Ltd.

periodData
array
required

An array containing submission periods made.

deductionFromDate
string
required

The from date for when the deduction was made within the CIS tax year period.

Date in the format YYYY-MM-DD

For example: 2020-01-01

deductionToDate
string
required

The to date for when the deduction was made within the CIS tax year period.

Date in the format YYYY-MM-DD

For example: 2020-01-01

submissionTimestamp
string
required

The date and time the period information was recorded in MTD, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

source
string
required

Identifies whether the period information was submitted by the contractor or customer.

Limited to the following possible values:

contractor
customer
deductionAmount
number
required

The amount of tax deducted by the contractor. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

allowancesReliefsAndDeductions
array
optional

An array of allowances, reliefs, and deductions claimed as part of the retrieved tax calculation.

type
string
optional

The type of allowance, deduction or relief claimed.

Limited to the following possible values:

investmentReliefs
otherReliefs
otherExpenses
otherDeductions
foreignReliefs
submittedTimestamp
string
optional

The date and time when the latest submission was received, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

startDate
string
optional

The start date for the period of the submission.

Date in the format YYYY-MM-DD

For example: 2020-01-01

endDate
string
optional

The end date for the period of the submission.

Date in the format YYYY-MM-DD

For example: 2020-01-01

source
string
optional

The source of the income data used in this calculation.

Limited to the following possible values:

MTD-SA
pensionContributionAndCharges
array
optional

An array indicating pension information used in the retrieved tax calculation.

type
string
required

The type of pension contribution.

Limited to the following possible values:

pensionReliefs
pensionCharges
submissionTimestamp
string
optional

The date and time when the latest submission was received, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

startDate
string
optional

The start date of the period.

Date in the format YYYY-MM-DD

For example: 2020-01-01

endDate
string
optional

The end date of the period.

Date in the format YYYY-MM-DD

For example: 2020-01-01

source
string
optional

The source of the data.

Limited to the following possible values:

MTD-SA
customer
other
array
optional

An array other inputs used in the retrieved tax calculation.

type
string
required

An array of other inputs that have been pulled into this calculation.

Limited to the following possible values:

codingOut
submittedOn
string
optional

The date and time when the information was received, in ISO 8601 UTC format: YYYY-MM-DDThh:mm:ss.SSSZ.

For example: 2019-02-15T09:35:15.094Z

calculation
object
optional

Object containing the tax calculation result.

allowancesAndDeductions
object
optional

Object detailing allowances and deductions used in the retrieved tax calculation.

personalAllowance
integer
optional

The personal allowance available for the tax year. This value must be between 0 and 99999999999. No decimals.

For example: 5000

marriageAllowanceTransferOut
object
optional

Object containing details about marriage allowance transferred out.

personalAllowanceBeforeTransferOut
number
required

The amount of the personal allowance before transferring out. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.12

transferredOutAmount
number
required

The amount of the personal allowance that has been transferred out. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.13

reducedPersonalAllowance
integer
optional

The amount that the personal allowance has been reduced to. This value must be between 0 and 99999999999. No decimals.

For example: 5001

giftOfInvestmentsAndPropertyToCharity
integer
optional

Investments or property gifts made to charity. This value must be between 0 and 99999999999. No decimals.

For example: 5002

blindPersonsAllowance
integer
optional

Blind Person's Allowance. This value must be between 0 and 99999999999. No decimals.

For example: 5003

lossesAppliedToGeneralIncome
integer
optional

Losses that have been applied to general income. This value must be between 0 and 99999999999. No decimals.

For example: 5004

cgtLossSetAgainstInYearGeneralIncome
integer
optional

CGT losses that have been applied to general income. This value must be between 0 and 99999999999. No decimals.

For example: 5005

qualifyingLoanInterestFromInvestments
number
optional

Qualifying loan interest payments made. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5006.06

postCessationTradeReceipts
number
optional

Trade reliefs and other losses post cessation of a business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5007.77

paymentsToTradeUnionsForDeathBenefits
number
optional

Payments made to a trade union or friendly society for death benefits. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5008.88

grossAnnuityPayments
number
optional

The gross value of annuity payments made. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5009.99

annuityPayments
object
optional

Object containing details about annuity payments.

reliefClaimed
number
optional

The value of annual payments made. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

rate
number
optional

The tax rate used in the calculation. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 10.25

pensionContributions
number
optional

Total of 'Retirement Annuity Payments', 'Payment To Employers Scheme No Tax Relief' and 'Overseas Pension Scheme Contributions'. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2001.59

pensionContributionsDetail
object
optional

Object containing details of any pension contributions made.

retirementAnnuityPayments
number
optional

The value of retirement annuity payments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2002.60

paymentToEmployersSchemeNoTaxRelief
number
optional

Payments to employer's pension scheme with no tax relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2003.61

overseasPensionSchemeContributions
number
optional

The value of contributions to an overseas pension scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2004.62

reliefs
object
optional

Details the reliefs used in the calculation.

residentialFinanceCosts
object
optional

Details the total residential finance cost reliefs used in the calculation.

adjustedTotalIncome
number
required

The income (after losses and reliefs, and excluding savings and dividends income) that exceeds your personal allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

totalAllowableAmount
number
optional

The total allowable amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2001.58

relievableAmount
number
required

The lower of either Adjusted Total Income or Total Allowable Amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2002.58

rate
number
required

The tax rate used in the calculation. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 10.25

totalResidentialFinanceCostsRelief
number
required

The total value of residential finance costs relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2004.58

ukProperty
object
optional

Details the residential finance costs for UK property.

amountClaimed
integer
required

The total amount claimed for residential finance costs. This value must be between 0 and 99999999999. No decimals.

For example: 2000

allowableAmount
number
required

The total amount allowable for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2006.58

carryForwardAmount
number
optional

The amount of residential finance costs that can be carried forward to future tax years. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2007.58

foreignProperty
object
optional

Details the residential finance costs for foreign property.

totalForeignPropertyAllowableAmount
number
required

The total amount allowable for all foreign property residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2006.58

foreignPropertyRfcDetail
array
required

Details residential finance costs for foreign property broken down by country.

countryCode
string
required

A three-letter code that represents a country name. This value must in ISO 3166-1 Alpha-3 format.

For example: FRA

amountClaimed
integer
required

The total amount claimed for residential finance costs. This value must be between 0 and 99999999999. No decimals.

For example: 2000

allowableAmount
number
required

The total amount allowable for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2007.58

carryForwardAmount
number
optional

The amount of residential finance costs that can be carried forward to future tax years. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2008.58

allOtherIncomeReceivedWhilstAbroad
object
optional

Details the residential finance costs for other income received whilst abroad.

totalOtherIncomeAllowableAmount
number
required

The total amount allowable for all other income received whilst abroad for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2009.58

otherIncomeRfcDetail
array
required

Details residential finance costs for other income broken down by country.

countryCode
string
required

A three-letter code that represents a country name. This value must in ISO 3166-1 Alpha-3 format.

For example: FRA

residentialFinancialCostAmount
number
optional

The total amount claimed for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2010.58

broughtFwdResidentialFinancialCostAmount
number
optional

The amount of residential financial costs brought forward from previous tax years. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2010.58

reliefsClaimed
array
optional

Details of investment and other reliefs used in the calculation.

type
string
required

The type of relief claimed.

Limited to the following possible values:

vctSubscriptions
eisSubscriptions
communityInvestment
seedEnterpriseInvestment
socialEnterpriseInvestment
maintenancePayments
deficiencyRelief
nonDeductibleLoanInterest
qualifyingDistributionRedemptionOfSharesAndSecurities
amountClaimed
number
optional

The amount of relief claimed. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2011.58

allowableAmount
number
optional

The amount of allowable relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2012.58

amountUsed
number
optional

The amount of relief used. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2013.58

rate
number
optional

The rate associated with the relief claimed. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.99

reliefsClaimedDetail
array
optional

An array containing details about reliefs claimed.

amountClaimed
number
optional

The amount of relief claimed. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2014.58

uniqueInvestmentRef
string
optional

Unique identifier of the entity investment reference.

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

For example: BAO123456A

name
string
optional

The name of the entity invested in. Populated for Venture Capital Trust (VCT), Enterprise Investment Scheme (EIS) and Community Investments.

For example: EIS fund

socialEnterpriseName
string
optional

The name of the Social Enterprise Investment invested in.

For example: SE Inc

companyName
string
optional

The name of the Seed Enterprise Investment invested in.

For example: Company Ltd

deficiencyReliefType
string
optional

The type of relief. Populated only for deficiency relief.

Limited to the following possible values:

lifeInsurance
lifeAnnuity
capitalRedemption
customerReference
string
optional

Unique reference or friendly name used by the customer.

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

For example: INPOLY123A

foreignTaxCreditRelief
object
optional

Details the foreign tax credit relief (FTCR) used in the calculation.

customerCalculatedRelief
boolean
optional

When this field is true, it means the customer has calculated their own relief. When it is false it means HMRC determined the relief.

For example: true

totalForeignTaxCreditRelief
number
required

The total value of foreign tax credit relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2015.58

foreignTaxCreditReliefOnProperty
number
optional

The value of foreign tax credit relief on property. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2016.58

foreignTaxCreditReliefOnDividends
number
optional

The value of foreign tax credit relief on dividends. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2017.58

foreignTaxCreditReliefOnSavings
number
optional

The value of foreign tax credit relief on savings. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2018.58

foreignTaxCreditReliefOnForeignIncome
number
optional

The value of foreign tax credit relief on foreign income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2019.58

foreignTaxCreditReliefDetail
array
optional

An array containing details about foreign tax credit relief used in the retrieved tax calculation.

incomeSourceType
string
optional

A list of income source types for foreign tax credit.

Limited to the following possible values:

foreign-dividends
foreign-property
foreign-savings-and-gains
other-income
foreign-pension
incomeSourceId
string
optional

An identifier for the business, unique to the customer.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

countryCode
string
required

A three-letter code that represents a country name. This value must in ISO 3166-1 Alpha-3 format.

For example: FRA

foreignIncome
number
required

The value of foreign income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2016.58

foreignTax
number
optional

The amount of foreign tax. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2017.58

dtaRate
number
optional

Defines a percentage rate for Double Tax Agreement. This value must be between 0 and 100.00 up to 2 decimal places.

For example: 20.99

dtaAmount
number
optional

Amount for Double Tax Agreement. This value must be between 0 and 99999999999 up to 2 decimal places.

For example: 2000.77

ukLiabilityOnIncome
number
optional

The amount of UK Liability on income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2001.77

foreignTaxCredit
number
required

The amount of foreign tax. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2002.77

employmentLumpSum
boolean
optional

A boolean to identify whether or not the income type was an employment lump sum. This value must be true or false.

For example: true

topSlicingRelief
object
optional

Details the top slicing reliefs used in the calculation.

amount
number
optional

The amount of top slicing relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

taxDeductedAtSource
object
optional

Object representing amounts that have been deducted for tax at source in the retrieved tax calculation.

bbsi
number
optional

Amount of Bank and Building Society Interest (BBSI). This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

ukLandAndProperty
number
optional

Amount of UK Land & Property. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2001.59

cis
number
optional

Amount of Construction Industry Scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2002.60

securities
number
optional

Amount of securities. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2003.61

voidedIsa
number
optional

Amount of voided Individual Savings Account (ISA). This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2004.62

payeEmployments
number
optional

Amount of Pay As You Earn (PAYE) employments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2005.63

occupationalPensions
number
optional

Amount of occupational pensions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2006.64

stateBenefits
number
optional

Amount of state benefits. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2007.65

specialWithholdingTaxOrUkTaxPaid
number
optional

Amount of Special Withholding Tax or UK Tax Paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2008.66

inYearAdjustmentCodedInLaterTaxYear
number
optional

Amount of in-year adjustment coded in later tax year. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2009.67

giftAid
object
optional

Object representing gift aid payments and tax due for the retrieved tax calculation.

grossGiftAidPayments
integer
required

The total amount of Gift Aid payments made for the tax year. This value must be between 0 and 99999999999. No decimals.

For example: 2000

rate
number
required

The basic rate of tax that applies to Gift Aid payments made. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.12

giftAidTax
number
required

The amount of Gift Aid tax charged if no reliefs or deductions apply. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.12

giftAidTaxReductions
number
optional

The amount of Gift Aid tax reductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 101.13

incomeTaxChargedAfterGiftAidTaxReductions
number
optional

The income tax charged after Gift Aid tax reductions have been applied. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 102.14

giftAidCharge
number
optional

The amount of Gift Aid tax charged after appropriate reliefs and deductions have been applied. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 103.15

royaltyPayments
object
optional

Object representing any royalty payments in the retrieved tax calculation.

royaltyPaymentsAmount
integer
required

The total amount of tax charged on royalty payments. This value must be between 0 and 99999999999. No decimals.

For example: 2000

rate
number
required

The rate of the royalty payment. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 10.12

grossRoyaltyPayments
integer
optional

The gross royalty payments. This value must be between 0 and 99999999999. No decimals.

For example: 2000

notionalTax
object
optional

Object containing notional tax amounts for the retrieved tax calculation.

chargeableGains
number
optional

The chargeable gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

marriageAllowanceTransferredIn
object
optional

Object detailing marriage allowance transfer in for the retrieved tax calculation.

amount
number
optional

The amount of marriage allowance transferred in. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3000.00

rate
number
optional

The percentage of the relief applied. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 10.52

pensionContributionReliefs
object
optional

Details the pension contribution reliefs used in the calculation.

totalPensionContributionReliefs
number
required

The total value of pension contribution reliefs made. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

pensionContributionDetail
object
required

Object containing a detailed breakdown of pension contribution reliefs for the retrieved tax calculation.

regularPensionContributions
number
optional

The total value of regular pension contributions made. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

oneOffPensionContributionsPaid
number
optional

The total value of one-off pension contributions made. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.58

pensionSavingsTaxCharges
object
optional

Details of pension savings tax charges.

totalPensionCharges
number
optional

Total of pension charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.99

totalTaxPaid
number
optional

Total tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.99

totalPensionChargesDue
number
optional

Total pension charges due after tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 130.00

pensionSavingsTaxChargesDetail
object
optional

Breakdown of pension savings tax charges.

excessOfLifeTimeAllowance
object
optional

Details of chargeable amounts in excess of lifetime allowance.

totalChargeableAmount
number
optional

Total chargeable amount for lump sum benefit taken in excess of lifetime allowance and benefit in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

totalTaxPaid
number
optional

Total tax paid for lump sum benefit taken in excess of lifetime allowance and benefit in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 200.00

lumpSumBenefitTakenInExcessOfLifetimeAllowance
object
optional

Details of lump sum benefit taken in excess of lifetime allowance.

amount
number
optional

The amount of lump sum benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

taxPaid
number
optional

Tax paid on lump sum benefit taken in excess of the lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

rate
number
optional

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

chargeableAmount
number
optional

The amount chargeable on the lump sum benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

benefitInExcessOfLifetimeAllowance
object
optional

Details of benefits taken in excess of lifetime allowance.

amount
number
optional

The amount of benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

taxPaid
number
optional

Tax paid on benefit taken in excess of the lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

rate
number
optional

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

chargeableAmount
number
optional

The amount chargeable on benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

pensionSchemeUnauthorisedPayments
object
optional

Details of pension scheme unauthorised payments.

totalChargeableAmount
number
optional

Total chargeable amount for pension scheme unauthorised payments surcharge and pension scheme unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

totalTaxPaid
number
optional

Total tax paid for pension scheme unauthorised payments surcharge and pension scheme unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

pensionSchemeUnauthorisedPaymentsSurcharge
object
optional

Details of pension scheme unauthorised payments surcharge.

amount
number
optional

The amount of unauthorised payments surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

taxPaid
number
optional

Tax paid on unauthorised payments surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

rate
number
optional

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

chargeableAmount
number
optional

The amount chargeable on unauthorised payments surcharges. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

pensionSchemeUnauthorisedPaymentsNonSurcharge
object
optional

Details of pension scheme unauthorised payments non surcharge.

amount
number
optional

The amount of unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

taxPaid
number
optional

Tax paid on unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

rate
number
optional

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

chargeableAmount
number
optional

The amount chargeable on unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

pensionSchemeOverseasTransfers
object
optional

Details of pension scheme overseas transfers.

transferCharge
number
optional

The amount of overseas pension scheme transfer charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

transferChargeTaxPaid
number
optional

Tax paid on overseas pension scheme transfer charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

rate
number
optional

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

chargeableAmount
number
optional

The amount chargeable on overseas pension scheme transfer charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

pensionContributionsInExcessOfTheAnnualAllowance
object
optional

Details of pension contributions in excess of the annual allowance.

totalContributions
number
required

The total amount of pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

totalPensionCharge
number
required

The total amount of pension charges on contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

annualAllowanceTaxPaid
number
optional

The amount of annual allowance tax paid on pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

totalPensionChargeDue
number
required

The amount chargeable on pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

pensionBands
array
optional

Details the relevant tax bands for the pension charges.

name
string
required

The name of the tax band.

Limited to the following possible values:

basic-rate
intermediate-rate
higher-rate
additional-rate
rate
number
required

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

bandLimit
integer
required

The tax band limit. This value must be between 0 and 99999999999. No decimals.

For example: 2000

apportionedBandLimit
integer
required

The apportioned tax band limit. This value must be between 0 and 99999999999. No decimals.

For example: 2000

contributionAmount
number
required

The amount of pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

pensionCharge
number
required

The amount chargeable on pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

overseasPensionContributions
object
optional

Details of overseas pensions contributions.

totalShortServiceRefund
number
required

The total amount of short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.00

totalShortServiceRefundCharge
number
required

The total amount of charges due on short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

shortServiceRefundTaxPaid
number
optional

The amount of tax paid on short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

totalShortServiceRefundChargeDue
number
required

The amount chargeable on short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 160.12

shortServiceRefundBands
array
optional

Details the relevant refund bands for overseas pension contributions.

name
string
required

The name of the tax band.

Limited to the following possible values:

lowerBand
upperBand
rate
number
required

The percentage rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 20.50

bandLimit
integer
required

The tax band limit. This value must be between 0 and 99999999999. No decimals.

For example: 2000

apportionedBandLimit
integer
required

The apportioned tax band limit. This value must be between 0 and 99999999999. No decimals.

For example: 2000

shortServiceRefundAmount
number
required

The amount of short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

shortServiceRefundCharge
number
required

The amount chargeable. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

studentLoans
array
optional

Array containing information about student loan repayment amount and employment deductions per plan type for the retrieved tax calculation.

planType
string
required

The repayment plan type.

Limited to the following possible values:

plan1
plan2
postgraduate
plan4
studentLoanTotalIncomeAmount
number
required

The total income used in the student loan calculation. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

studentLoanChargeableIncomeAmount
number
required

The total student loan income less the threshold. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

studentLoanRepaymentAmount
number
required

The student loan repayment before deductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

studentLoanDeductionsFromEmployment
number
optional

The student loan deduction collected by the employer. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

studentLoanRepaymentAmountNetOfDeductions
number
required

The student loan repayment after deductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

studentLoanApportionedIncomeThreshold
integer
required

The student loan threshold. This value must be between 0 and 99999999999. No decimals.

For example: 2000

studentLoanRate
number
required

The percentage rate income is charged at. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 3.52

payeIncomeForStudentLoan
number
optional

The PAYE income for student loan threshold. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

nonPayeIncomeForStudentLoan
number
optional

The non-PAYE income for student loan threshold. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 100.50

codedOutUnderpayments
object
optional

Object containing detail for coded out amounts in the retrieved tax calculation.

totalPayeUnderpayments
number
optional

The total coded out amount attributed to PAYE underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

payeUnderpaymentsDetail
array
optional

Array containing details for PAYE-related underpayments in the retrieved tax calculation.

amount
number
required

Coded out amount attributed to PAYE underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

relatedTaxYear
string
required

The tax year this underpayment relates to.

Tax year in the format YYYY-YY

For example: 2020-21

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
totalSelfAssessmentUnderpayments
number
optional

The total amount of Self Assessment underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

totalCollectedSelfAssessmentUnderpayments
number
optional

The total amount collected for Self Assessment underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

totalUncollectedSelfAssessmentUnderpayments
number
optional

The total amount of uncollected Self Assessment underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

selfAssessmentUnderpaymentsDetail
array
optional

Array containing details about Self Assessment related underpayments in the retrieved tax calculation.

amount
number
required

The total coded out amount attributed to Self Assessment underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

relatedTaxYear
string
required

The tax year this underpayment relates to.

Tax year in the format YYYY-YY

For example: 2020-21

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
collectedAmount
number
optional

The amount of underpayment you have paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

uncollectedAmount
number
optional

The outstanding amount you now need to pay. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

foreignPropertyIncome
array
optional

Array containing a breakdown of the income received for foreign property by country code for the retrieved tax calculation.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

The income source type.

Limited to the following possible values:

foreign-property
countryCode
string
required

A three-letter code that represents a country name. This value must in ISO 3166-1 Alpha-3 format.

For example: FRA

totalIncome
number
optional

The total income for foreign property. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalExpenses
number
optional

The total expenses for foreign property. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

netProfit
number
optional

The net profit for foreign property. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

netLoss
number
optional

The net loss for foreign property. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalAdditions
number
optional

The total additions to the net profit (or deductions from the net loss) for the foreign property business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalDeductions
number
optional

The total deductions from the net loss (or additions to the net profit) for the foreign property business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxableProfit
number
optional

The taxable profit after all additions and deductions have been applied for the foreign property business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

adjustedIncomeTaxLoss
number
optional

The adjusted Income Tax loss after all additions and deductions have been applied for the foreign property business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

businessProfitAndLoss
array
optional

An array of objects summarising the profit and loss position for business income sources. The enum in the incomeSourceType will determine the business type. When the incomeSourceType is "self-employment", totalExpenses and totalAdditions may be negative amounts. Other business sources will continue to return positive amounts.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: XAIS12345678910

incomeSourceType
string
required

The income source type.

Limited to the following possible values:

self-employment
uk-property-non-fhl
uk-property-fhl
foreign-property
foreign-property-fhl-eea
incomeSourceName
string
optional

The name of the income source.

For example: ABC-123 Ltd.

totalIncome
number
optional

The total income used in the business calculation. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

totalExpenses
number
optional

The total expenses used in the business calculation. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

netProfit
number
optional

The net profit for the business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

netLoss
number
optional

The net loss for the business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

totalAdditions
number
optional

The total additions to the net profit (or deductions from the net loss) for the business. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

totalDeductions
number
optional

The total deductions from the net loss (or additions to the net profit) for the business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

accountingAdjustments
number
optional

Accounting adjustments applied to the profit or loss calculation for Foreign Property. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxableProfit
integer
optional

The taxable profit after all additions and deductions have been applied for the business. This value must be between 0 and 99999999999. No decimals.

For example: 160

adjustedIncomeTaxLoss
integer
optional

The adjusted Income Tax loss after all additions and deductions have been applied for the business. This value must be between 0 and 99999999999. No decimals.

For example: 160

totalBroughtForwardIncomeTaxLosses
integer
optional

The total sum of Income Tax losses brought forward from earlier years for the business. This value must be between 0 and 99999999999. No decimals.

For example: 160

lossForCSFHL
integer
optional

The losses from UK Property Non-FHL that have been carried sideways to UK Property FHL. This value must be between 0 and 99999999999. No decimals.

For example: 160

broughtForwardIncomeTaxLossesUsed
integer
optional

This is the total sum of losses brought forward from previous years used against the taxable profit for the business for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

taxableProfitAfterIncomeTaxLossesDeduction
integer
optional

The taxable profit after income tax losses have been deducted for the business. This value must be between 0 and 99999999999. No decimals.

For example: 160

carrySidewaysIncomeTaxLossesUsed
integer
optional

The Income Tax losses for the business that have been carried sideways in this calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

broughtForwardCarrySidewaysIncomeTaxLossesUsed
integer
optional

The total sum of the carry sideways losses for the business brought forward from previous tax years. This value must be between 0 and 99999999999. No decimals.

For example: 160

totalIncomeTaxLossesCarriedForward
integer
optional

The total sum of Income Tax losses to be carried forward that have not been utilised against the business profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

class4Loss
integer
optional

The Class 4 National Insurance Contributions loss for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

totalBroughtForwardClass4Losses
integer
optional

The total sum of Class 4 National Insurance Contributions losses brought forward from earlier years for the business. This value must be between 0 and 99999999999. No decimals.

For example: 160

broughtForwardClass4LossesUsed
integer
optional

The total sum of Class 4 National Insurance Contributions losses brought forward from earlier years that have been used against the Class 4 National Insurance Contributions for the business for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

carrySidewaysClass4LossesUsed
integer
optional

The Class 4 National Insurance Contributions losses for the business that have been carried sideways in this calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

totalClass4LossesCarriedForward
integer
optional

The total sum of Class 4 National Insurance Contributions losses to be carried forward that have not been used against the business profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 160

employmentAndPensionsIncome
object
optional

Object containing income from employments and pension in the retrieved tax calculation.

totalPayeEmploymentAndLumpSumIncome
number
optional

Total PAYE employment & lump sum income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalOccupationalPensionIncome
number
optional

Total occupational pension income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalBenefitsInKind
number
optional

Total benefits in kind. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

tipsIncome
number
optional

Total tips income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

employmentAndPensionsIncomeDetail
array
optional

Array detailing any income received from employment and pension sources.

incomeSourceId
string
optional

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
occupationalPension
boolean
optional

A boolean to identify whether the occupational pension is true or false.

For example: false

employerRef
string
optional

A unique identifier, the employer reference number.

Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$

For example: 123/AB56797

employerName
string
optional

The name of the employer the employee worked for.

For example: ABC-123 Ltd

payrollId
string
optional

The unique identifier used by the employer to identify the employee.

Must conform to the regular expression ^[A-Za-z0-9.,\-()/=!"%&*; <>'+:\?]{0,38}$

For example: S9500206

startDate
string
optional

The date the employment began.

Date in the format YYYY-MM-DD

For example: 2020-01-01

dateEmploymentEnded
string
optional

The date the employment ended.

Date in the format YYYY-MM-DD

For example: 2020-01-01

taxablePayToDate
number
optional

Total taxable pay to date. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalTaxToDate
number
optional

Total tax to date. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

disguisedRemuneration
boolean
optional

Indicates whether this is disguised remuneration. This value must be true or false.

For example: false

lumpSums
object
optional

Object containing any lump sums relating to pension or employment income.

totalLumpSum
number
required

Total lump sum. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalTaxPaid
number
optional

Total tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

lumpSumsDetail
object
required

Object detailing any lump sums relating to pension or employment income.

taxableLumpSumsAndCertainIncome
object
optional

Object detailing any taxable lump sums and certain income.

amount
number
optional

The amount from lump sums and certain income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxPaid
number
optional

Tax paid on lump sums and certain income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxTakenOffInEmployment
boolean
optional

A boolean to identify whether tax was taken off in employment. This value must be true or false.

For example: false

benefitFromEmployerFinancedRetirementScheme
object
optional

Object detailing any benefits received from employer financed retirement schemes.

amount
number
optional

The amount from benefits from employment finance retirement scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

exemptAmount
number
optional

The exempt amount from benefits from employment finance retirement scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxPaid
number
optional

Tax paid on benefits from employment finance retirement scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxTakenOffInEmployment
boolean
optional

A boolean to identify whether tax was taken off in employment. This value must be true or false.

For example: false

redundancyCompensationPaymentsOverExemption
object
optional

Object detailing any redundancy compensation payments over exemption.

amount
number
optional

The amount from redundancy compensation payments over exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxPaid
number
optional

Tax Paid on redundancy compensation payments over exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

taxTakenOffInEmployment
boolean
optional

A boolean to identify whether tax was taken off in employment. This value must be true or false.

For example: false

redundancyCompensationPaymentsUnderExemption
object
optional

Object detailing any redundancy compensation payments under exemption.

amount
number
optional

The amount of redundancy compensation payments under exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

studentLoans
object
optional

Object detailing any amounts relating to undergraduate and postgraduate student loans.

uglDeductionAmount
number
optional

Student loan undergraduate deduction amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

pglDeductionAmount
number
optional

Student loan postgraduate deduction amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

benefitsInKind
object
optional

Object containing information about any received benefits in kind.

totalBenefitsInKindReceived
number
optional

Total benefits in kind received. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

benefitsInKindDetail
object
optional

Object detailing any received benefits in kind.

apportionedAccommodation
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedAssets
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedAssetTransfer
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedBeneficialLoan
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedCar
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedCarFuel
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedEducationalServices
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedEntertaining
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedExpenses
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedMedicalInsurance
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedTelephone
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedService
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedTaxableExpenses
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedVan
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedVanFuel
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedMileage
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedNonQualifyingRelocationExpenses
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedNurseryPlaces
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedOtherItems
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedPaymentsOnEmployeesBehalf
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedPersonalIncidentalExpenses
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedQualifyingRelocationExpenses
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedEmployerProvidedProfessionalSubscriptions
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedEmployerProvidedServices
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedIncomeTaxPaidByDirector
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedTravelAndSubsistence
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedVouchersAndCreditCards
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

apportionedNonCash
number
optional

Apportioned benefit amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

employmentExpenses
object
optional

Object containing information about employment related expenses in the retrieved tax calculation.

totalEmploymentExpenses
number
optional

Total employment expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

employmentExpensesDetail
object
optional

Object detailing employment related expenses.

businessTravelCosts
number
optional

Total business travel costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

jobExpenses
number
optional

Total job expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

flatRateJobExpenses
number
optional

Total flat rate job expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

professionalSubscriptions
number
optional

Total professional subscriptions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

hotelAndMealExpenses
number
optional

Total hotel and meal expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

otherAndCapitalAllowances
number
optional

Total other and capital allowances. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

vehicleExpenses
number
optional

Total vehicle expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

mileageAllowanceRelief
number
optional

Total Mileage Allowance Relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

seafarersDeductions
object
optional

Object detailing any seafarers deductions for the retrieved tax calculation.

totalSeafarersDeduction
number
required

Total seafarers deductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

seafarersDeductionDetail
array
required

Array containing a breakdown of each deduction submitted for seafarers deductions for the retrieved tax calculation.

nameOfShip
string
required

The name of the ship for this deduction.

For example: Blue Bell

amountDeducted
number
required

Amount deducted for this ship. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

foreignTaxForFtcrNotClaimed
object
optional

Object detailing foreign tax for which tax credit relief was not claimed in the retrieved tax calculation.

foreignTaxOnForeignEmployment
number
required

Amount of foreign tax on foreign employment. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

stateBenefitsIncome
object
optional

Object containing information about any state benefits income in the retrieved tax calculation.

totalStateBenefitsIncome
number
optional

Total state benefits income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

totalStateBenefitsTaxPaid
number
optional

Total state benefits tax paid. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5001.99

stateBenefitsDetail
object
optional

Object detailing state benefits income.

incapacityBenefit
array
optional

Array detailing Incapacity Benefit income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of Incapacity Benefit. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5002.99

taxPaid
number
optional

The amount of tax paid on Incapacity Benefit. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5003.99

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
statePension
array
optional

Array detailing State Pension income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of State Pension. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5004.99

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
statePensionLumpSum
array
optional

Array detailing State Pension lump sum income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of State Pension lump sum. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5005.99

taxPaid
number
optional

The amount of tax paid on State Pension lump sum. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5006.99

rate
number
required

Tar rate of tax paid on State Pension lump sum. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 4.85

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
employmentSupportAllowance
array
optional

Array detailing Employment Support Allowance income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of Employment Support Allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5008.99

taxPaid
number
optional

The amount of tax paid on Employment Support Allowance. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5009.99

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
jobSeekersAllowance
array
optional

Array detailing Job Seekers Allowance income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of Job Seekers Allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5010.99

taxPaid
number
optional

The amount of tax paid on Job Seekers Allowance. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 5011.99

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
bereavementAllowance
array
optional

Array detailing Bereavement Allowance income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of Bereavement Allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5012.99

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
otherStateBenefits
array
optional

Array detailing other benefits income.

incomeSourceId
string
required

The unique identifier of the income source.

Must conform to the regular expression ^[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: bb74c290-cae6-11ec-9b64-0242ac120002

amount
number
required

The amount of other state benefits. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5013.99

source
string
optional

The source of the data.

Limited to the following possible values:

customer
HMRC HELD
shareSchemesIncome
object
optional

Object containing information about income received from share schemes in the retrieved tax calculation.

totalIncome
number
required

The total income used in the calculation. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

shareSchemeDetail
array
optional

Array detailing share schemes income.

type
string
required

The type of share scheme.

Limited to the following possible values:

shareOption
sharesAwardedOrReceived
employerName
string
optional

The name of the employer the employee worked for.

Must conform to the regular expression ^[A-Za-z0-9 \-,.&'/]{1,105}$

For example: ABC-123 Ltd

employerRef
string
optional

A unique identifier, the employer reference number.

Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$

For example: 123/AB56797

taxableAmount
number
required

Taxable amount for the share scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

foreignIncome
object
optional

Object containing information about foreign income in the received tax calculation.

chargeableOverseasPensionsStateBenefitsRoyalties
number
optional

Chargeable overseas pensions and state benefits royalties income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 500.99

overseasPensionsStateBenefitsRoyaltiesDetail
array
optional

Array containing information about income from overseas pensions, state benefits, and royalties.

countryCode
string
required

A three-letter code that represents a country name. This value must in ISO 3166-1 Alpha-3 format.

For example: FRA

grossIncome
number
optional

Gross income for overseas pensions, state benefits and royalties. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 501.99

netIncome
number
optional

Net income for overseas pensions, state benefits and royalties. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 502.99

taxDeducted
number
optional

Tax deducted for overseas pensions, state benefits and royalties. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 503.99

foreignTaxCreditRelief
boolean
optional

A boolean indicating whether it's a Foreign Tax Credit Relief. This value must be true or false.

For example: true

chargeableAllOtherIncomeReceivedWhilstAbroad
number
optional

Chargeable income received whilst abroad. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 504.99

allOtherIncomeReceivedWhilstAbroadDetail
array
optional

Array detailing all other income received whilst abroad.

countryCode
string
required

A three-letter code that represents a country name. This value must in ISO 3166-1 Alpha-3 format.

For example: FRA

grossIncome
number
optional

Gross income from all other income received whilst abroad. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 502.99

netIncome
number
optional

Net income from all other income received whilst abroad. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 503.99

taxDeducted
number
optional

Tax deducted from all other income received whilst abroad. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 504.99

foreignTaxCreditRelief
boolean
optional

A boolean indicating whether it's a Foreign Tax Credit Relief. This value must be true or false.

For example: true

overseasIncomeAndGains
object
optional

Object detailing overseas income and gains.

gainAmount
number
required

Gain from overseas income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 506.99

totalForeignBenefitsAndGifts
number
optional

Total foreign benefits and gifts. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 507.99

chargeableForeignBenefitsAndGiftsDetail
object
optional

Object detailing chargeable foreign benefits and gifts.

transactionBenefit
number
optional

Amount of transaction benefit. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 508.99

protectedForeignIncomeSourceBenefit
number
optional

Amount of protected foreign income source benefit. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 509.99

protectedForeignIncomeOnwardGift
number
optional

Amount of protected foreign income onward gift. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 510.99

benefitReceivedAsASettler
number
optional

Amount of benefit received as a settler. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 511.99

onwardGiftReceivedAsASettler
number
optional

Amount of onward gift received as a settler. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 512.99

chargeableEventGainsIncome
object
optional

Object containing information about chargeable event gains income in the retrieved tax calculation.

totalOfAllGains
integer
required

Total gains for chargeable event gains income. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalGainsWithTaxPaid
integer
optional

Total gains with tax paid for chargeable event gains income. This value must be between 0 and 99999999999. No decimals.

For example: 5002

gainsWithTaxPaidDetail
array
optional

Array detailing gains with tax paid.

type
string
required

The type of gains with tax paid.

Limited to the following possible values:

lifeInsurance
capitalRedemption
lifeAnnuity
customerReference
string
optional

A reference unique to the customer.

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

For example: S1000z

gainAmount
number
optional

Gain amount for gains with tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 180.00

yearsHeld
integer
optional

Years held. This value must be between 0 and 99. No decimals.

For example: 50

yearsHeldSinceLastGain
integer
optional

Years held since last gain. This value must be between 0 and 99. No decimals.

For example: 35

totalGainsWithNoTaxPaidAndVoidedIsa
integer
optional

Total of gains with no tax paid and voided ISA. This value must be between 0 and 99999999999. No decimals.

For example: 5000

gainsWithNoTaxPaidAndVoidedIsaDetail
array
optional

Array detailing gains with no tax paid and voided Isa.

type
string
required

The type of gains with no tax paid and voided ISA.

Limited to the following possible values:

lifeInsurance
capitalRedemption
lifeAnnuity
voidedIsa
customerReference
string
optional

A reference unique to the customer.

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

For example: S1000z

gainAmount
number
optional

Gain amount for gains with no tax paid and voided ISA. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 180.00

yearsHeld
integer
optional

Years held. This value must be between 0 and 99. No decimals.

For example: 50

yearsHeldSinceLastGain
integer
optional

Years held since last gain. This value must be between 0 and 99. No decimals.

For example: 83

voidedIsaTaxPaid
number
optional

Voided ISA tax paid amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 180.55

totalForeignGainsOnLifePoliciesTaxPaid
integer
optional

Total of foreign gains on life policies with tax paid. This value must be between 0 and 99999999999. No decimals.

For example: 5000

foreignGainsOnLifePoliciesTaxPaidDetail
array
optional

Array detailing foreign gains on life policies with tax paid.

customerReference
string
optional

A reference unique to the customer.

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

For example: S1000z

gainAmount
number
optional

Gain amount for foreign gains on life policies with tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

taxPaidAmount
number
optional

Foreign gains on life policies with tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3500.99

yearsHeld
integer
optional

Years held. This value must be between 0 and 99. No decimals.

For example: 5

totalForeignGainsOnLifePoliciesNoTaxPaid
integer
optional

Total of foreign gains on life policies with no tax paid. This value must be between 0 and 99999999999. No decimals.

For example: 3100

foreignGainsOnLifePoliciesNoTaxPaidDetail
array
optional

Array detailing foreign gains on life policies with no tax paid.

customerReference
string
optional

A reference unique to the customer.

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

For example: S1000z

gainAmount
number
optional

Foreign gain on life policies with no tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 5000.99

yearsHeld
integer
optional

Years held. This value must be between 0 and 99. No decimals.

For example: 62

savingsAndGainsIncome
object
optional

Object containing information about savings and gains income in the retrieved tax calculation.

totalChargeableSavingsAndGains
integer
optional

The total chargeable savings and gains. This value must be between 0 and 99999999999. No decimals.

For example: 5055

totalUkSavingsAndGains
integer
optional

The total UK savings and gains. This value must be between 0 and 99999999999. No decimals.

For example: 6400

ukSavingsAndGainsIncome
array
optional

Array detailing UK savings and gains income.

incomeSourceId
string
optional

The unique identifier of the income source.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: 000000000000210

incomeSourceType
string
required

The income source type for the UK savings and gains.

Limited to the following possible values:

uk-savings-and-gains
uk-securities
incomeSourceName
string
optional

The name of the income source.

For example: Savings Account 1

grossIncome
number
required

The amount of gross income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 180.00