This version is in beta - expect some breaking changes.

Self Assessment Accounts (MTD) API

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

Overview

This API allows a developer to retrieve the overall liability broken down into overdue, payable and pending amounts.

With this API the developer can:

• Retrieve History of a Self Assessment Charge
• Retrieve Self Assessment Balance and Transactions
• Retrieve History of a Self Assessment Charge
• Retrieve, Create or Amend, or Delete coding out amounts

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

Support

• Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
• Raise technical issues on the income-tax-mtd-changelog GitHub page.

Testing

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

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

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

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

Skip to main content

Endpoints

Payments and Liabilities

These endpoints allow a developer to retrieve accounting information to be shown back to the customer. This includes listing payments the customer has made, how these payments have been allocated and details of any upcoming or outstanding liabilities. The data returned only relates to payments and liabilities arising for tax years since the customer joined the new service. There may also be outstanding liabilities and payment information a customer needs to view for the years prior to signing up to Making Tax Digital for Income Tax Self Assessment that can be viewed using their existing Personal Tax Account.

Payments and Liabilities resources

/accounts/self-assessment/{nino}/charges/{transactionId}

Retrieve History of a Self Assessment Charge

GET

This endpoint enables you to retrieve the history of changes to an individual charge. A National Insurance number and transaction ID must be provided.

Authorisation

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

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
transactionId string required	A unique identifier for the charge. Must conform to the regular expression: ^[0-9A-Za-z]{1,16}$ ^[0-9A-Za-z]{1,12}$ For example: A3948472839A

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

{
  "chargeHistoryDetails": [
    {
    "taxYear": "2022-23",
    "transactionId": "X123456790A",
    "transactionDate": "2018-04-05",
    "description": "POA1, Balancing charge",
    "totalAmount": 600.00,
    "changeDate": "2018-04-05",
    "changeReason": "Amended return, Customer Request"
  }
  ]
}

Name	Description
chargeHistoryDetails array required	A list of changes to a particular charge
taxYear string optional	The tax year that this charge relates to in the format: YYYY-YY. For example: 2022-23
transactionId string required	A unique identifier used to return a single charge. Must conform to the regular expression ^[A-Za-z0-9]{1,30}$ For example: X123456790A
transactionDate string required	The date the charge was created in the format: YYYY-MM-DD. For example: 2018-04-05
description string required	Primary method to identify what type of charge has been called. For example: POA1, Balancing charge
totalAmount number required	The value of the charge following the change. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. For example: 600.00
changeDate string required	The date the charge was changed in the format: YYYY-MM-DD. For example: 2018-04-05
changeReason string required	The reason for the change. For example: Amended return, Customer Request

Error scenarios

Scenario	HTTP status	Code
The format of the supplied nino value is invalid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied transaction identifier field is not valid.	400 (Bad Request)	FORMAT_TRANSACTION_ID
The client or agent is not authorised. This is because: the client is not enrolled for MTD, the agent is not enrolled for Agent Services, the client has not authorised the agent to act on their behalf, or the Authorization token provided is not correct.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates a successful response.
NOT_FOUND	Simulates the scenario where no data can be found.

Close Section

/accounts/self-assessment/{nino}/balance-and-transactions

Retrieve Self Assessment Balance and Transactions

GET

This endpoint enables you to retrieve the overall liability broken down into overdue, currently due (payable), and pending (not yet due) amounts. A 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

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B

Query parameters

Name	Description
docNumber string optional	The docNumber is a unique number per tax grouping in the Account display. (When onlyOpenItems has been set to false, either the date range (fromDate and toDate) or doc number should be supplied.) For example: 3060013199
fromDate string optional	The inclusive start date to return balances and transactions. The maximum date range between fromDate and toDate should not exceed 732 days. (When onlyOpenItems has been set to false, either the date range (fromDate and toDate) or docNumber should be supplied.) For example: 2023-12-12
toDate string optional	The inclusive end date to return balances and transactions. The maximum date range between fromDate and toDate should not exceed 732 days. (When onlyOpenItems has been set to false, either the date range (fromDate and toDate) or docNumber should be supplied.) For example: 2024-12-12
onlyOpenItems boolean optional	Limits the extraction to unpaid or not reversed charges. (When onlyOpenItems has been set to false, either the date range (fromDate and toDate) or docNumber should be supplied.) Defaults to false For example: false
includeLocks boolean optional	Include additional information related to claim and debt management. Defaults to false For example: true
calculateAccruedInterest boolean optional	Calculate accrued interest. Accruing interest is the amount of interest calculated a) To today’s date (or in the case of a created statement, to the statement date) b) On any overdue interest-bearing liability No interest charge is created for an amount of accruing interest. An interest charge is only created when the related liability is paid in full. For example: false
removePOA boolean optional	Remove Payment on Account details. When true, details of any payments that the customer has made will not be returned. Defaults to false. For example: false
customerPaymentInformation boolean optional	Include customer payment information in the response. When true, the following information is returned: Payment Reference, Payment Amount, Payment Method, Payment Lot, Payment Lot Item, Clearing SAP Document. Note that if removePOA is true, no information is returned even if customerPaymentInformation is true. Defaults to false. For example: false
includeEstimatedCharges boolean optional	Include statistical (estimated) values for monthly payments. Defaults to false. For example: true

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

{
  "balanceDetails": {
    "payableAmount": -99999999999.99,
    "payableDueDate": "1920-02-29",
    "pendingChargeDueAmount": -99999999999.99,
    "pendingChargeDueDate": "1920-02-29",
    "overdueAmount": -99999999999.99,
    "bcdBalancePerYear": [
      {
        "taxYear": "2022-23",
        "bcdAmount": 1300.12
      },
      {
        "taxYear": "2020-21",
        "bcdAmount": 1600.12
      }
    ],
    "earliestPaymentDateOverdue": "1920-02-29",
    "totalBalance": -99999999999.99,
    "amountCodedOut": 3456.67,
    "totalBcdBalance": 2600.24,
    "unallocatedCredit": 3456.67,
    "allocatedCredit": 2345.67,
    "totalCredit": 4567.67,
    "firstPendingAmountRequested": 1234.67,
    "secondPendingAmountRequested": 3100.67,
    "availableCredit": 1212.67
  },
  "codingDetails": [
    {
      "returnTaxYear": "2020-21",
      "totalLiabilityAmount": 5009.99,
      "codingTaxYear": "2020-21",
      "coded": {
        "charge": 5009.99,
        "initiationDate": "2021-04-05"
      }
    }
  ],
  "documentDetails": {
    "taxYear": "2020-21",
    "documentId": "1455",
    "formBundleNumber": "88888888",
    "creditReason": "Voluntary Payment",
    "documentDate": "2018-04-05",
    "documentText": "ITSA- Bal Charge",
    "documentDueDate": "2021-04-05",
    "documentDescription": "ITSA- POA 1",
    "originalAmount": 5009.99,
    "outstandingAmount": 5009.99,
    "lastClearing": {
      "lastClearingDate": "2018-04-05",
      "lastClearingReason": "Incoming Payment",
      "lastClearedAmount": 5009.99
    },
    "isChargeEstimate": true,
    "isCodedOut": true,
    "paymentLot": "AB1023456789",
    "paymentLotItem": "000001",
    "effectiveDateOfPayment": "2021-04-05",
    "latePaymentInterest": {
      "latePaymentInterestId": "1234567890123456",
      "accruingInterestAmount": 5009.99,
      "interestRate": 5.99,
      "interestStartDate": "2020-04-01",
      "interestEndDate": "2020-04-05",
      "interestAmount": 5009.99,
      "interestDunningLockAmount": 5009.99,
      "interestOutstandingAmount": 5009.99
    },
    "amountCodedOut": 5009.99,
    "reducedCharge": {
      "chargeType": "AA",
      "documentNumber": "1234567890123456",
      "amendmentDate": "2018-04-05",
      "taxYear": "2017-18"
    }
  },
  "financialDetails": [
    {
      "taxYear": "2016-17",
      "chargeDetail": {
        "documentId": "12345678901234568",
        "documentType": "1234",
        "documentTypeDescription": "Income Tax Estimate",
        "chargeType": "5678",
        "chargeTypeDescription": "Income Tax Estimate - ITSA"
      },
      "taxPeriodFrom": "2018-08-13",
      "taxPeriodTo": "2018-08-14",
      "contractAccount": "X",
      "documentNumber": "1040000872",
      "documentNumberItem": "XM00",
      "chargeReference": "XM002610011594",
      "originalAmount": 10000,
      "outstandingAmount": 10000,
      "clearedAmount": 10000,
      "accruedInterest": 10000,
      "items": [
        {
          "itemId": "001",
          "dueDate": "2018-08-13",
          "amount": 10000,
          "clearingDate": "2018-08-13",
          "clearingReason": "Outgoing Payment",
          "outgoingPaymentMethod": "Payable Order Repayment",
          "locks": {
            "isChargeOnHold": false,
            "isEstimatedChargeOnHold": false,
            "isInterestAccrualOnHold": false,
            "isInterestChargeOnHold": false
          },
          "isReturn": true,
          "paymentReference": "Ab12453535",
          "paymentAmount": 10000,
          "paymentMethod": "Payment",
          "paymentLot": "81203010024",
          "paymentLotItem": "000001",
          "clearingSAPDocument": "3350000253",
          "isChargeEstimate": true
        }
      ]
    }
  ]
}

Name	Description
balanceDetails object required
payableAmount number required	The sum of any non-zero charges whose payment due date is within 30 days. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
payableDueDate string optional	Next payment date for charges due in the format YYYY-MM-DD. For example: 2018-04-05
pendingChargeDueAmount number required	The sum of any charges whose payment is pending (not yet due). The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
pendingChargeDueDate string optional	The date by when the next pending (not yet due) charge must be paid in the format YYYY-MM-DD. For example: 2018-04-05
overdueAmount number required	The total amount of charges under each documentID whose due date is in the past Accrued Interest Amount / LPI Amount will also be included (where applicable). The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
bcdBalancePerYear array required	An array containing balance charge debit payment details.
taxYear string required	The tax year for the appropriate balance charge debit. For example: 2018-19
bcdAmount number required	The balancing charge debit amount is the balancing payment due by the taxpayer calculated when the return is captured. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
earliestPaymentDateOverdue string optional	The next day after the payment due date in the format YYYY-MM-DD For example: 2018-04-05
totalBalance number required	The sum of all the unpaid charges excluding statistical and EOY coded out. The total balance should be equal to the sum of the balance due within 30 days, balance not due in 30 days, and overdue amount. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
amountCodedOut number optional	The total amount of underpayment codeout. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
totalBcdBalance number optional	The total of the Balance charge debit balance amount. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places For example: 5009.99
unallocatedCredit number optional	Sum of all the Open credit Items on the customer's account, posted for Income tax Self-assessment. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
allocatedCredit number optional	Sum of all the closed credit items on the customer's account, posted for Income tax Self-assessment. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
totalCredit number optional	Sum of unallocated credit + allocated credit. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
firstPendingAmountRequested number optional	This will be the first pending amount that is requested. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
secondPendingAmountRequested number optional	This will be the second pending amount that is requested. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
availableCredit number optional	This will be equal to total credit minus the pending amount(s) requested. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
codingDetails array optional	An Object containing coding details
returnTaxYear string optional	The ending year of the tax year to which the return relates is in the format YYYY-YY. For example: 2021-22
totalLiabilityAmount number optional	The total amount of the Self Assessment tax return inclusive of coded charges. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. For example: 5009.99
codingTaxYear string optional	The tax year that the coded out charge will be attached to. For example: 2021-22
coded object optional	An object containing a coded amount and initiation date
charge number optional	The coded out charge. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. For example: 5009.99
initiationDate string optional	Initiation date of the coded out charge, in the format YYYY-MM-DD. For example: 2021-04-05
documentDetails object optional	An array containing document details
documentDetails array optional	An object containing document details
taxYear string optional	The tax year of the Document (Billing period from – billing period to), in the format YYYY-YY. For example, the tax year 2020 to 2021 is expressed as 2020-21. For example: 2020-21
documentId string required	DocumentID may contain SAP document number or Form Bundle Number for zero-amount documents. Must conform to the regular expression ^[0-9a-zA-Z]{1,30}$ For example: 1455
formBundleNumber string optional	The form bundle number designates a package of related transactions gathered together. For example: 88888888
creditReason string optional	Credit Reason gives the reason as to why there is a credit on the account. Limited to the following possible values: Voluntary Payment Income tax Self Assessment Return Excess Payment
documentDate string required	The date when the document for a particular tax group containing charges was created in the format YYYY-MM-DD. For example: 2018-04-05
documentText string optional	Provides details about the tax group that the charge belongs to. For example: ITSA- Bal Charge
documentDueDate string required	The date the item must be received in the format YYYY-MM-DD. For example: 2021-04-05
documentDescription string optional	The primary method to identify what type of document has been called. Limited to the following possible values: ITSA- POA 1 ITSA - POA 2 ITSA- Bal Charge New Charge Clearing Document TRM New Charge TRM Amend Charge Payment Repayment
originalAmount number required	The original value of this transaction before payments, credits, or adjustments. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5000.99
outstandingAmount number required	The amount remaining of this transaction after payments, credits, or adjustments. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5000.99
lastClearing object optional	Details if the amount was previously modified.
lastClearingDate string optional	The date the outstanding amount was last modified, in the format YYYY-MM-DD. For example: 2018-04-05
lastClearingReason string optional	The reason for the change. For example, an interest charge was created. Limited to the following possible values: Incoming Payment Outgoing Payment Other Write-Off Reversal
lastClearedAmount number optional	The amount the transaction was last modified by. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5000.99
isChargeEstimate boolean required	An indicator to represent that the charge is an estimate and not an actual charge. The value must be true or false. For example: false
isCodedOut boolean required	An indicator to represent that the charge has been sent for coding out. For example: false
paymentLot string optional	A unique identifier for a credit that has been made direct to ETMP. For example: AB1023456789
paymentLotItem string optional	A unique ID that is used in combination with Payment Lot to refer to an individual payment. For example: 000001
effectiveDateOfPayment string optional	The effective date of payment in the format YYYY-MM-DD. For example: 2021-04-05
latePaymentInterest object optional	An object containing late payment interest details.
latePaymentInterestId string optional	Late Payment Interest ID is the Charge Reference Number of all the monthly and final interest charges of the same parent charge. For example: 1234567890123456
accruingInterestAmount number optional	The total value of all the monthly interest charges and accruing (unposted) interest charges is grouped by Charge Reference level. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5000.99
interestRate number optional	The latest interest rate for late payments. The value must be between 0 and 99.99 to 2 decimal places. For example: 5.99
interestStartDate string optional	The date the interest charges started in the format YYYY-MM-DD. For example: 2020-04-05
interestEndDate string optional	The date the interest charges ended in the format YYYY-MM-DD. For example: 2020-05-05
interestAmount number optional	The total value of all the monthly interest charges and final interest charges is grouped by Charge Reference level. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 201.99
interestDunningLockAmount number optional	Late payment interest amount where the Interest is temporarily not being charged on (A lock has been put so the interest will not be charged to the customer). The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
interestOutstandingAmount number optional	TThe unpaid amount of Accruing Interest or Late Payment Interest. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5000.99
amountCodedOut number optional	The amount from the total tax return charge that has been coded out. The value must be between -9999.99 and 2999.99 to 2 decimal places. For example: 5009.99
reducedCharge object optional	Details if Charge has been reduced.
chargeType string optional	Document name of charge reduced. This will be the Charge type name of the original charge For example: AA
documentNumber string optional	If Charge has been reduced, and credit arises, the document number to be shown. This will be the SAP Document number of this document For example: 1234567890123456
amendmentDate string optional	Amendment date of charge that has been reduced. This will be the date the charge was reduced/changed/reversed in the format YYYY-MM-DD. For example: 2018-04-05
taxYear string optional	Tax Year of Charge that has been reduced. This is the tax year on the original charge. For example: 2018-19
financialDetails array optional	A list of charges that make up the overall transaction. The items may include subitems.
taxYear string required	The tax year to which the charge relates, in the format YYYY-YY For example: 2020-21
chargeDetail object required
documentId string required	A unique ID is used to reference the document of which this is a subitem. Must conform to the regular expression: ^[0-9a-zA-Z]{1,30}$ For example: XAIS12345678910
documentType string optional	A unique ID is used to reference the document type of which this is a subitem. For example: 1234
documentTypeDescription string optional	The Description of the main charge type For example: SA Balancing Charge
chargeType string optional	A unique ID is used to identify the type of sub-item. For example: 3175
chargeTypeDescription string optional	Name of charge type. Must conform to the regular expression: ^[0-9A-Za-z]{1,30}$ For example: Income Tax Estimate - NIC2 NI
taxPeriodFrom string optional	The 'from' date of this tax period. Date in the format: YYYY-MM-DD For example: 2020-04-06
taxPeriodTo string optional	The 'to' date of this tax period. Date in the format: YYYY-MM-DD For example: 2021-04-05
contractAccount string optional	A contract account is the accounting record for a particular charge type. For example: X
documentNumber string optional	Same as Document Number/ID unless on output there is no postings (zero amounts) then the Form Bundle is returned Must conform to the regular expression: ^[0-9A-Za-z]{1,12}$ For example: 1040000872
documentNumberItem string optional	An identifier for this part of the overall transaction is used to link an allocation and charge. For example: XM00
chargeReference string optional	A unique reference number is associated with the charge. For example: XM002610011594
originalAmount number optional	The original amount of this transaction. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
outstandingAmount number optional	The remaining amount is due on this transaction. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
clearedAmount number optional	The cleared value of this transaction. For example, the paid amount of a charge. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
accruedInterest number optional	The accrued interest of this transaction. Accrued interest is interest calculated and charged. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places For example: 5009.99
items array required	The list of items as part of the financial details
itemId string optional	An identifier for the item in the list. For example: 001
dueDate string optional	If the requested item relates to a charge, the due date is the date by which the amount is due to be paid. If the requested item relates to a payment, the due date refers to the date the payment was made to HMRC in the format YYY-MM-DD For example: 2018-04-05
amount number optional	The amount that this entry changed the transaction by. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
clearingDate string optional	The date this entry changed the item, in the format YYYY-MM-DD. For example: 2018-04-05
clearingReason string optional	The reason for the change to the item. Limited to the following possible values: Incoming Payment Outgoing Payment Reversal Manual Clearing Automatic Clearing
outgoingPaymentMethod string optional	The method used to make the outgoing payment. One of Repayment to Card, Payable Order Repayment or BACS Payment out Limited to the following possible values: Repayment to Card Payable Order Repayment BACS Payment out
locks object optional	An object holding the lock fields
isChargeOnHold boolean required	A signal that indicates that the charge has been paused whilst under review or investigation. For example: false
isEstimatedChargeOnHold boolean required	A clearing lock is used only for statistical or forecasted charges. For example: false
isInterestAccrualOnHold boolean required	Indicates if the charge is not accruing interest due to a review or investigation. For example: true
isInterestChargeOnHold boolean required	A lock has been put in so the interest will not be charged to the customer. For example: true
isReturn boolean optional	If it is true, that means the charge has been generated by a return. For example: true
paymentReference string optional	A unique reference number is associated with the payment. For example: Ab12453535
paymentAmount number optional	If the item relates to a payment, the payment amount is the amount of the payment received into the account. If the item relates to a charge, the payment amount is the amount that this entry changed the transaction by. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. For example: 5009.99
paymentMethod string optional	The method used to make the payment. For example: BACS RECEIPTS
paymentLot string optional	If the item is a payment, the payment lot is a unique identifier for a credit. If the item is a charge, the payment lot is a unique identifier for an allocation within the charge and allows you to identify where the payment came from. For example: 81203010024
paymentLotItem string optional	A unique ID is used in combination with a payment ID to refer to an individual payment or credit. For example: 000001
clearingSAPDocument string optional	When a payment is used against a charge, this links payment and charge together. For example: 3350000253
isChargeEstimate boolean optional	Indicates whether the item represents an estimated charge. For example: true

Error scenarios

Scenario	HTTP status	Code
The format of the supplied nino value is invalid.	400 (Bad Request)	FORMAT_NINO
The format of docNumber is not valid.	400 (Bad Request)	FORMAT_DOC_NUMBER
The format of onlyOpenItem is not valid.	400 (Bad Request)	FORMAT_ONLY_OPEN_ITEMS
The format of includeLocks is not valid.	400 (Bad Request)	FORMAT_INCLUDE_LOCKS
The format for calculatingAccruedInterest is not valid.	400 (Bad Request)	FORMAT_CALCULATE_ACCRUED_INTEREST
The format of customerPaymentInformation is not valid.	400 (Bad Request)	FORMAT_CUSTOMER_PAYMENT_INFORMATION
The format of the fromDate is not valid.	400 (Bad Request)	FORMAT_FROM_DATE
The format of toDate is not valid.	400 (Bad Request)	FORMAT_TO_DATE
The format of removePOA is not valid.	400 (Bad Request)	FORMAT_REMOVE_PAYMENT_ON_ACCOUNT
The format of includeEstimatedCharges is not valid	400 (Bad Request)	FORMAT_INCLUDE_ESTIMATED_CHARGES
The provided date range is not valid.	400 (Bad Request)	RULE_INVALID_DATE_RANGE
Provide date range or docNumber when onlyOpenItems is false.	400 (Bad Request)	RULE_INCONSISTENT_QUERY_PARAMS
The To date parameter is missing.	400 (Bad Request)	MISSING_TO_DATE
The From date parameter is missing	400 (Bad Request)	MISSING_FROM_DATE
The To date must be after the From date.	400 (Bad Request)	RANGE_TO_DATE_BEFORE_FROM_DATE
The client or agent is not authorised. This is because: the client is not enrolled for MTD, the agent is not enrolled for Agent Services, the client has not authorised the agent to act on their behalf, or the Authorization token provided is not correct.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates a successful response.
NOT_FOUND	Simulates the scenario where no data can be found.
INCONSISTENT_QUERY_PARAMS	Simulates the scenario where the query parameters are inconsistent.
INVALID_DATE_RANGE	Simulates the scenario where the provided date range is invalid.

Close Section

/accounts/self-assessment/{nino}/payments-and-allocations

List Self Assessment Payments & Allocation Details

GET

This endpoint enables you to list the payments and allocation details of one or more liabilities for a National Insurane number.

Authorisation

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

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B

Query parameters

Name	Description
fromDate string optional	The inclusive start date of the period to filter payments. The maximum date range between fromDate and toDate should not exceed 732 days. For example: 2019-01-02
toDate string optional	The inclusive end date of the period to filter payments. The maximum date range between fromDate and toDate should not exceed 732 days. For example: 2020-01-02
paymentLot string optional	An identifier for the batch process that processed the payment and assigned it to the taxpayer's account. For example: 081203010024
paymentLotItem string optional	An identifier for each payment within a payment lot. paymentLot and paymentLotItem together uniquely identify a payment. For example: 000001

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

{
  "payments": [
    {
      "paymentLot": "081203010024",
      "paymentLotItem": "000001",
      "paymentReference": "1594",
      "paymentAmount": 12345678912.02,
      "paymentMethod": "A",
      "transactionDate": "2010-02-27",
      "allocations": [
        {
          "chargeReference": "XM002610011594",
          "periodKey": "16RL",
          "periodKeyDescription": "2016/17 month 12 RTI",
          "startDate": "2010-03-27",
          "endDate": "2010-06-27",
          "dueDate": "2010-07-27",
          "chargeDetail":{
            "documentId": "1040000872",
            "documentType": "1234",
            "documentTypeDescription": "Income Tax Estimate",
            "chargeType": "5678",
            "chargeTypeDescription": "Income Tax Estimate - ITSA"
          },
          "amount": 12345678912.02,
          "clearedAmount": 345678912.02,
          "contractAccount": "ABC"
        },
        {
          "chargeReference": "XM002610011560",
          "periodKey": "16RR",
          "periodKeyDescription": "2016/17 month 10 RTI",
          "startDate": "2010-04-21",
          "endDate": "2010-09-20",
          "dueDate": "2010-11-29",
          "chargeDetail":{
            "documentId": "1040000872",
            "documentType": "1234",
            "documentTypeDescription": "Income Tax Estimate",
            "chargeType": "5678",
            "chargeTypeDescription": "Income Tax Estimate - ITSA"
          },
          "amount": 12345678999.92,
          "clearedAmount": 345678992.92,
          "contractAccount": "ABS"
        }
      ]
    }
  ],
  "links":[
    {
      "href":"/individuals/accounts/self-assessment/NS345678A/payments-and-allocations",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Name	Description
payments array required	An array containing payments made by the customer.
paymentLot string optional	An identifier for the batch process that processed the payment and assigned it to the taxpayer's account. For example: AB1023456789-000001
paymentLotItem string optional	An identifier for each payment within a payment lot. paymentLot and paymentLotItem together uniquely identify a payment. For example: 000001
paymentReference string optional	A unique reference number associated with the payment. For example: 000001700000001
paymentAmount number optional	The amount of the payment received into the account. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. For example: 10000.00
paymentMethod string optional	The method used to make the payment. Must conform to the regular expression: ^[0-9A-Za-z]{1,30}$ For example: BACS, Payment by card
transactionDate string optional	The date the payment was received into the account in the format: YYYY-MM-DD For example: 2018-04-05
allocations array required	A list of charges which are allocated amounts from the payment
chargeReference string required	A unique reference for the original charge that the payment was made against. For example: XM002610011595
periodKey string optional	The period key attributed to the charge. A four digit reference containing characters and numbers to identify the specific tax period. For example: 16RL
periodKeyDescription string optional	A description of the period key as a tax period. For example: 6th April 2020 to 5th April 2021
startDate string optional	The start date of the tax year for the charge in the format YYYY-MM-DD For example: 2018-04-06
endDate string optional	The end date of the tax year for the charge in the format YYYY-MM-DD For example: 2019-04-05
dueDate string optional	The date the charge must be paid by. Interest or penalties will be accrued after this date. For example: 2019-07-27
chargeDetail object optional
documentId string optional	Same as Document Number unless on output there are no postings then the Form Bundle number is returned. Must conform to the regular expression: ^[0-9A-Za-z]{1,12}$ For example: 1040000872
documentType string optional	A code to specify the document type of which this is a subitem. For example: 3880
documentTypeDescription string optional	Description of the document type. For example: Income Tax Estimate
chargeType string optional	A code to specify the type of charge. For example: 1005
chargeTypeDescription string optional	Description of the charge type. For example: Income Tax Estimate - ITSA
amount number optional	The original value of this transaction. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. For example: 600.00
clearedAmount number optional	The cleared value of this transaction. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. For example: 600.00
contractAccount string optional	The accounting record for a particular charge type. For example: 000404772537
links array required
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET
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
href string required	The relative URL of the endpoint. For example: /accounts/self-assessment/AA999999A/payments-and-allocations

Error scenarios

Scenario	HTTP status	Code
The format of the supplied nino value is invalid.	400 (Bad Request)	FORMAT_NINO
The format of the fromDate is not valid.	400 (Bad Request)	FORMAT_FROM_DATE
The format of toDate is not valid.	400 (Bad Request)	FORMAT_TO_DATE
The To date must be after the From date.	400 (Bad Request)	RANGE_TO_DATE_BEFORE_FROM_DATE
The provided date range is not valid.	400 (Bad Request)	RULE_INVALID_DATE_RANGE
The To date parameter is missing.	400 (Bad Request)	MISSING_TO_DATE
The From date parameter is missing	400 (Bad Request)	MISSING_FROM_DATE
The format of the supplied paymentLot value is not valid.	400 (Bad Request)	FORMAT_PAYMENT_LOT
The format of the supplied paymentLotItem value is not valid.	400 (Bad Request)	FORMAT_PAYMENT_LOT_ITEM
The paymentLotItem value has been provided, but paymentLot value is missing.	400 (Bad Request)	MISSING_PAYMENT_LOT
The client or agent is not authorised. This is because: the client is not enrolled for MTD, the agent is not enrolled for Agent Services, the client has not authorised the agent to act on their behalf, or the Authorization token provided is not correct.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
Matching resource not found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates a successful response.
NOT_FOUND	Simulates the scenario where no data can be found.
INVALID_DATE_RANGE	Simulates the scenario where the provided date range is invalid.

Close Section

Coding Out Underpayments and Debts

Coding out is a concept used to retrieve underpaid tax and debts through a taxpayers PAYE tax code.

The coding out underpayments and debts endpoints allow software packages to overwrite coding out underpayment and debt amounts that are held by HMRC for a previous tax year and given NINO. Software packages can then amend previously submitted overwrite amounts, retrieve the HMRC held or user submitted coding out amounts or delete the user submitted amounts.

Coding Out Underpayments and Debts resources

/accounts/self-assessment/{nino}/{taxYear}/collection/tax-code

Retrieve Coding Out Underpayments and Debt Amounts

GET

This endpoint enables you to retrieve HMRC-held coding out underpayments and debt amounts or user submitted amended coding out amounts for a previous tax year and given National Insurance number.

Authorisation

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

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
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 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.). Must conform to the regular expression: ^2[0-9]{3}-[0-9]{2}$ For example: 2021-22

Query parameters

Name	Description
source string optional	Specifies the source of data to be returned. If source is not provided, the latest values will be returned. Limited to the following possible values: hmrcHeld user latest

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

Example Response

{
  "taxCodeComponents": {
    "selfAssessmentUnderpayment": [
      {
        "amount": 89.78,
        "relatedTaxYear": "2021-22",
        "submittedOn": "2021-07-06T09:37:17.000Z",
        "source": "user",
        "id": 1234567891
      }
    ],
    "payeUnderpayment": [
      {
        "amount": 14.45,
        "relatedTaxYear": "2021-22",
        "submittedOn": "2021-07-06T09:37:17.000Z",
        "source": "user",
        "id": 1234567891
      }
    ],
    "debt": [
      {
        "amount": 12.01,
        "relatedTaxYear": "2021-22",
        "submittedOn": "2021-07-06T09:37:17.000Z",
        "source": "user",
        "id": 1234567891
      }
    ],
    "inYearAdjustment": {
      "amount": 75.99,
      "relatedTaxYear": "2021-22",
      "submittedOn": "2021-07-06T09:37:17.000Z",
      "source": "user",
      "id": 1234567891
    }
  },
  "unmatchedCustomerSubmissions": {
    "selfAssessmentUnderpayment": [
      {
        "amount": 12.32,
        "submittedOn": "2021-07-06T09:37:17.000Z",
        "id": 1234567891
      }
    ],
    "payeUnderpayment": [
      {
        "amount": 71.99,
        "submittedOn": "2021-07-06T09:37:17.000Z",
        "id": 1234567891
      }
    ],
    "debt": [
      {
        "amount": 54.79,
        "submittedOn": "2021-07-06T09:37:17.000Z",
        "id": 1234567891
      }
    ],
    "inYearAdjustment": {
      "amount": 56.74,
      "submittedOn": "2021-07-06T09:37:17.000Z",
      "id": 1234567891
    }
  },
  "links": [
    {
      "href": "/accounts/self-assessment/TC663795B/2021-22/collection/tax-code",
      "method": "PUT",
      "rel": "create-or-amend-coding-out-underpayments"
    },
    {
      "href": "/accounts/self-assessment/TC663795B/2021-22/collection/tax-code",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/accounts/self-assessment/TC663795B/2021-22/collection/tax-code",
      "method": "DELETE",
      "rel": "delete-coding-out-underpayments"
    }
  ]
}

Name	Description
taxCodeComponents object optional	Object holding underpayment arrays.
selfAssessmentUnderpayment array optional	Array containing details of coded out Self Assessment underpayments.
id number optional	The ID for the Self Assessment underpayment. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total coded out amount attributed to Self Assessment underpayments. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
relatedTaxYear string optional	The tax year related to the underpayment. For example: 2021-22
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
source string required	Specifies the source of data. Limited to the following possible values: hmrcHeld user
payeUnderpayment array optional	Array containing details of coded out PAYE underpayments.
id number optional	The ID for the PAYE underpayment. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total coded out amount attributed to PAYE underpayments. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
relatedTaxYear string optional	The tax year related to the underpayment. For example: 2021-22
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
source string required	Specifies the source of data. Limited to the following possible values: hmrcHeld user
debt array optional	Array containing details of coded out debts.
id number optional	The ID for the coded out debts. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total amount of debt coded out. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
relatedTaxYear string optional	The tax year related to the debt. For example: 2021-22
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
source string required	Specifies the source of data. Limited to the following possible values: hmrcHeld user
inYearAdjustment object optional	Details of coded out in-year adjustments
id number optional	The ID for the HMRC classified debts. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total amount of PAYE coded out in-year adjustment. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
relatedTaxYear string optional	The tax year related to the in-year adjustment. For example: 2021-22
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
source string required	Specifies the source of data. Limited to the following possible values: hmrcHeld user
unmatchedCustomerSubmissions object optional	Object holding underpayment arrays for unmatched customer submissions.
selfAssessmentUnderpayment array optional	Array containing details of coded out Self Assessment underpayments.
id number optional	The ID for the Self Assessment underpayment. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total coded out amount attributed to Self Assessment underpayments. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
payeUnderpayment array optional	Array containing details of coded out PAYE underpayments.
id number optional	The ID for the PAYE underpayment. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total coded out amount attributed to PAYE underpayments. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
debt array optional	Array containing details of coded out debts.
id number optional	The ID for the coded out debts. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total amount of debt coded out. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
inYearAdjustment object optional	Details of coded out in-year adjustments
id number optional	The ID for the HMRC classified debts. It will only be returned after the tax year has ended. For example: 1234567890
amount number required	The total amount of PAYE coded out in-year adjustment. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
submittedOn string required	The date the coded out information was added. It is either the latest change date held within HMRC or the latest user submitted date. It is in the format YYYY-MM-DDThh:mm:ss.sssZ. For example: 2021-07-06T09:37:17.000Z
links array required	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: /accounts/self-assessment/TC663795B/2021-22/collection/tax-code
rel string required	A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource Limited to the following possible values: create-or-amend-coding-out-underpayments self delete-coding-out-underpayments
method string required	The HTTP method type for the endpoint Limited to the following possible values: PUT GET DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied nino value is invalid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied taxYear value is invalid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
A taxYear range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The format of the supplied source is not valid.	400 (Bad Request)	FORMAT_SOURCE
The client or agent is not authorised. This is because: the client is not enrolled for MTD, the agent is not enrolled for Agent Services, the client has not authorised the agent to act on their behalf, or the Authorization token provided is not correct.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
Coding out amounts could not be found for the supplied nino and taxYear.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates a successful response with latest values.
N/A - DEFAULT using ?source=latest	Simulates a successful response with latest values.
N/A - DEFAULT using ?source=hmrcHeld	Simulates a successful response with HMRC-held values.
N/A - DEFAULT using ?source=user	Simulates a successful response with user submitted values.
NOT_FOUND	Simulates the scenario where no data is found.

Close Section

/accounts/self-assessment/{nino}/{taxYear}/collection/tax-code

Create or Amend Coding Out Underpayments and Debt Amounts

PUT

This endpoint enables you to overwrite coding out underpayments and debt amounts held by HMRC for a previous tax year and given National Insurance number, and to amend previously submitted overwrite amounts. This endpoint can only be used after the tax year has ended.

Authorisation

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

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
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 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.). Must conform to the regular expression: ^2[0-9]{3}-[0-9]{2}$ For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Example Request

{
  "taxCodeComponents": {
    "payeUnderpayment": [
      {
        "amount": 2000.50,
        "id": 1234567890
      }
    ],
    "selfAssessmentUnderpayment": [
      {
        "amount": 1123.45,
        "id": 4657839807
      }
    ],
    "debt": [
      {
        "amount": 100.25,
        "id": 2134693857
      }
    ],
    "inYearAdjustment": {
      "amount": 123.45,
      "id": 9873562901
    }
  }
}

Name	Description
taxCodeComponents object required	Object holding underpayment arrays.
payeUnderpayment array optional	Array containing details of coded out PAYE underpayments.
id number required	The identifier for the PAYE underpayments. For example: 1234567890
amount number required	The total coded out amount attributed to PAYE underpayments. The value must be between 0 and 99999999999.99. For example: 1000.25
selfAssessmentUnderpayment array optional	Array containing details of coded out Self Assessment underpayments.
id number required	The identifier for the Self Assessment underpayments. For example: 1234567890
amount number required	The total coded out amount attributed to Self Assessment underpayments. The value must be between 0 and 99999999999.99. For example: 1000.25
debt array optional	Array containing details of coded out debts.
id number required	The identifier for the HMRC classified debts. For example: 1234567890
amount number required	The total coded out amount attributed to HMRC classified debts. The value must be between 0 and 99999999999.99. For example: 1000.25
inYearAdjustment object optional	Details of coded out in-year adjustments.
id number required	The identifier for the total coded out amount attributed to in-year tax code adjustments to collect underpayments or debts. For example: 1234567890
amount number required	The total coded out amount attributed to in-year tax code adjustments to collect underpayments or debts. The value must be between 0 and 99999999999.99. For example: 1000.25

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Example Response

{
  "links":[
    {
      "href":"/accounts/self-assessment/TC663795B/2021-22/collection/tax-code",
      "method":"PUT",
      "rel":"create-or-amend-coding-out-underpayments"
    },
    {
      "href":"/accounts/self-assessment/TC663795B/2021-22/collection/tax-code",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/accounts/self-assessment/TC663795B/2021-22/collection/tax-code",
      "method":"DELETE",
      "rel":"delete-coding-out-underpayments"
    }
  ]
}

Name	Description
links array optional	A list of endpoint links that indicate possible actions related to the current resource
href string required	The relative url of the endpoint For example: /accounts/self-assessment/TC663795B/2021-22/collection/tax-code
rel string required	A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource Limited to the following possible values: create-or-amend-coding-out-underpayments self delete-coding-out-underpayments
method string required	The HTTP method type for the endpoint Limited to the following possible values: PUT GET DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied nino value is invalid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied taxYear value is invalid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
A taxYear range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The submission has been made before the taxYear it relates to has ended.	400 (Bad Request)	RULE_TAX_YEAR_NOT_ENDED
The request data contains duplicate ID values.	400 (Bad Request)	RULE_DUPLICATE_ID_NOT_ALLOWED
One or more values have been added with the incorrect format.	400 (Bad Request)	FORMAT_VALUE
The format of the supplied ID is invalid.	400 (Bad Request)	FORMAT_ID
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED
The client or agent is not authorised. This is because: the client is not enrolled for MTD, the agent is not enrolled for Agent Services, the client has not authorised the agent to act on their behalf, or the Authorization token provided is not correct.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

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

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulate a successful response.

Close Section

/accounts/self-assessment/{nino}/{taxYear}/collection/tax-code

Delete Coding Out Underpayments and Debt Amounts

DELETE

This endpoint enables you to delete custom coding out amounts for a given tax year and National Insurance number.

Authorisation

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

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
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 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.). Must conform to the regular expression: ^2[0-9]{3}-[0-9]{2}$ For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253

See also fraud prevention.

Error scenarios

Scenario	HTTP status	Code
The format of the supplied nino value is invalid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied taxYear value is invalid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
A taxYear range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not enrolled for MTD, the agent is not enrolled for Agent Services, the client has not authorised the agent to act on their behalf, or the Authorization token provided is not correct.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
Coding out amounts could not be found for the supplied nino and taxYear.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates a success response.
NOT_FOUND	Simulates the scenario where coding out amounts could not be found.

Close Section

Skip to main content

Is this page not working properly? (opens in new tab)