Self Assessment Accounts (MTD) API
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 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.
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.
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.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
transactionId
string
required
|
A unique identifier for the charge.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
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 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: |
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: |
transactionDate
string
required
|
The date the charge was created in the format: YYYY-MM-DD.
For example: |
description
string
required
|
Primary method to identify what type of charge has been called.
For example: |
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: |
changeDate
string
required
|
The date the charge was changed in the format: YYYY-MM-DD.
For example: |
changeReason
string
required
|
The reason for the change.
For example: |
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.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
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: |
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: |
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: |
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: |
includeLocks
boolean
optional
|
Include additional information related to claim and debt management. Defaults to false
For example: |
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: |
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: |
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: |
includeEstimatedCharges
boolean
optional
|
Include statistical (estimated) values for monthly payments. Defaults to false.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
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 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: |
payableDueDate
string
optional
|
Next payment date for charges due in the format YYYY-MM-DD.
For example: |
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: |
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: |
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: |
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: |
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: |
earliestPaymentDateOverdue
string
optional
|
The next day after the payment due date in the format YYYY-MM-DD
For example: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
codingTaxYear
string
optional
|
The tax year that the coded out charge will be attached to.
For example: |
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: |
initiationDate
string
optional
|
Initiation date of the coded out charge, in the format YYYY-MM-DD.
For example: |
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: |
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: |
formBundleNumber
string
optional
|
The form bundle number designates a package of related transactions gathered together.
For example: |
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: |
documentText
string
optional
|
Provides details about the tax group that the charge belongs to.
For example: |
documentDueDate
string
required
|
The date the item must be received in the format YYYY-MM-DD.
For example: |
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: |
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: |
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: |
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: |
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: |
isCodedOut
boolean
required
|
An indicator to represent that the charge has been sent for coding out.
For example: |
paymentLot
string
optional
|
A unique identifier for a credit that has been made direct to ETMP.
For example: |
paymentLotItem
string
optional
|
A unique ID that is used in combination with Payment Lot to refer to an individual payment.
For example: |
effectiveDateOfPayment
string
optional
|
The effective date of payment in the format YYYY-MM-DD.
For example: |
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: |
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: |
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: |
interestStartDate
string
optional
|
The date the interest charges started in the format YYYY-MM-DD.
For example: |
interestEndDate
string
optional
|
The date the interest charges ended in the format YYYY-MM-DD.
For example: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
taxYear
string
optional
|
Tax Year of Charge that has been reduced. This is the tax year on the original charge.
For example: |
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: |
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: |
documentType
string
optional
|
A unique ID is used to reference the document type of which this is a subitem.
For example: |
documentTypeDescription
string
optional
|
The Description of the main charge type
For example: |
chargeType
string
optional
|
A unique ID is used to identify the type of sub-item.
For example: |
chargeTypeDescription
string
optional
|
Name of charge type. Must conform to the regular expression: ^[0-9A-Za-z]{1,30}$
For example: |
taxPeriodFrom
string
optional
|
The 'from' date of this tax period. Date in the format: YYYY-MM-DD
For example: |
taxPeriodTo
string
optional
|
The 'to' date of this tax period. Date in the format: YYYY-MM-DD
For example: |
contractAccount
string
optional
|
A contract account is the accounting record for a particular charge type.
For example: |
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: |
documentNumberItem
string
optional
|
An identifier for this part of the overall transaction is used to link an allocation and charge.
For example: |
chargeReference
string
optional
|
A unique reference number is associated with the charge.
For example: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
clearingDate
string
optional
|
The date this entry changed the item, in the format YYYY-MM-DD.
For example: |
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: |
isEstimatedChargeOnHold
boolean
required
|
A clearing lock is used only for statistical or forecasted charges.
For example: |
isInterestAccrualOnHold
boolean
required
|
Indicates if the charge is not accruing interest due to a review or investigation.
For example: |
isInterestChargeOnHold
boolean
required
|
A lock has been put in so the interest will not be charged to the customer.
For example: |
isReturn
boolean
optional
|
If it is true, that means the charge has been generated by a return.
For example: |
paymentReference
string
optional
|
A unique reference number is associated with the payment.
For example: |
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: |
paymentMethod
string
optional
|
The method used to make the payment.
For example: |
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: |
paymentLotItem
string
optional
|
A unique ID is used in combination with a payment ID to refer to an individual payment or credit.
For example: |
clearingSAPDocument
string
optional
|
When a payment is used against a charge, this links payment and charge together.
For example: |
isChargeEstimate
boolean
optional
|
Indicates whether the item represents an estimated charge.
For example: |
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.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
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: |
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: |
paymentLot
string
optional
|
An identifier for the batch process that processed the payment and assigned it to the taxpayer's account.
For example: |
paymentLotItem
string
optional
|
An identifier for each payment within a payment lot. paymentLot and paymentLotItem together uniquely identify a payment.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
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 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: |
paymentLotItem
string
optional
|
An identifier for each payment within a payment lot. paymentLot and paymentLotItem together uniquely identify a payment.
For example: |
paymentReference
string
optional
|
A unique reference number associated with the payment.
For example: |
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: |
paymentMethod
string
optional
|
The method used to make the payment. Must conform to the regular expression: ^[0-9A-Za-z]{1,30}$
For example: |
transactionDate
string
optional
|
The date the payment was received into the account in the format: YYYY-MM-DD
For example: |
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: |
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: |
periodKeyDescription
string
optional
|
A description of the period key as a tax period.
For example: |
startDate
string
optional
|
The start date of the tax year for the charge in the format YYYY-MM-DD
For example: |
endDate
string
optional
|
The end date of the tax year for the charge in the format YYYY-MM-DD
For example: |
dueDate
string
optional
|
The date the charge must be paid by. Interest or penalties will be accrued after this date.
For example: |
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: |
documentType
string
optional
|
A code to specify the document type of which this is a subitem.
For example: |
documentTypeDescription
string
optional
|
Description of the document type.
For example: |
chargeType
string
optional
|
A code to specify the type of charge.
For example: |
chargeTypeDescription
string
optional
|
Description of the charge type.
For example: |
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: |
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: |
contractAccount
string
optional
|
The accounting record for a particular charge type.
For example: |
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: |
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.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
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:
For example: |
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:
|
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
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 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: |
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: |
relatedTaxYear
string
optional
|
The tax year related to the underpayment.
For example: |
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: |
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: |
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: |
relatedTaxYear
string
optional
|
The tax year related to the underpayment.
For example: |
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: |
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: |
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: |
relatedTaxYear
string
optional
|
The tax year related to the debt.
For example: |
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: |
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: |
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: |
relatedTaxYear
string
optional
|
The tax year related to the in-year adjustment.
For example: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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: |
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 |
Simulates a successful response with latest values. |
N/A - DEFAULT |
Simulates a successful response with HMRC-held values. |
N/A - DEFAULT |
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.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
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:
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
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: |
amount
number
required
|
The total coded out amount attributed to PAYE underpayments. The value must be between 0 and 99999999999.99.
For example: |
selfAssessmentUnderpayment
array
optional
|
Array containing details of coded out Self Assessment underpayments. |
id
number
required
|
The identifier for the Self Assessment underpayments.
For example: |
amount
number
required
|
The total coded out amount attributed to Self Assessment underpayments. The value must be between 0 and 99999999999.99.
For example: |
debt
array
optional
|
Array containing details of coded out debts. |
id
number
required
|
The identifier for the HMRC classified debts.
For example: |
amount
number
required
|
The total coded out amount attributed to HMRC classified debts. The value must be between 0 and 99999999999.99.
For example: |
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: |
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: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking 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: |
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.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
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:
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.2.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
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 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