This version is in beta - expect some breaking changes.

Self Assessment Accounts (MTD) API

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

Overview

This API allows a developer to 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

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

Path parameters table
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

Request headers Table
Name Description
Accept
required

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

For example: application/vnd.hmrc.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

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

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

Response table
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

Error scenarios table
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

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

Query parameters

Query parameters table
Name Description
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

Request headers Table
Name Description
Accept
required

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

For example: application/vnd.hmrc.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

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

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

Response table
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

Error scenarios table
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

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

Query parameters

Query parameters table
Name Description
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

Request headers Table
Name Description
Accept
required

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

For example: application/vnd.hmrc.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

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

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



Response table
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

Error scenarios table
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

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 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

Query parameters table
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

Request headers Table
Name Description
Accept
required

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

For example: application/vnd.hmrc.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

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response

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

Response table
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

Error scenarios table
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

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 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

Request headers Table
Name Description
Accept
required

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

For example: application/vnd.hmrc.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
    }
  }
}

Request table
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

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Example Response

{
  "links":[
    {
      "href":"/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"
    }
  ]
}

Response table
Name Description
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /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

Error scenarios table
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

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

taxYear
string
required

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 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

Request headers Table
Name Description
Accept
required

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

For example: application/vnd.hmrc.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

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

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

See also fraud prevention.

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied nino 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