--- title: "Retrieve Self Assessment Balance and Transactions" method: GET path: "/accounts/self-assessment/{nino}/balance-and-transactions" tags: ["Payments and Liabilities"] --- # Retrieve Self Assessment Balance and Transactions `GET /accounts/self-assessment/{nino}/balance-and-transactions` 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. ### Test data Scenario simulation using Gov-Test-Scenario headers is only available in the sandbox environment. | Header Value (Gov-Test-Scenario) | Scenario | |----------------------------------|---------------------------------------------------------------------| | N/A - DEFAULT | Simulates success response. | | NOT_FOUND | Simulates the scenario where no data is found. | ## Path parameters - `nino` string, required ## Query parameters - `docNumber` string - `fromDate` string - `toDate` string - `onlyOpenItems` boolean - `includeLocks` boolean - `calculateAccruedInterest` boolean - `removePOA` boolean - `customerPaymentInformation` boolean - `includeEstimatedCharges` boolean ## Headers - `Accept` 'application/vnd.hmrc.4.0+json', required - `Authorization` string, required - `Gov-Test-Scenario` string ## Response `200` Success - object — 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. - `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. - `payableDueDate` string — Next payment date for charges due in the format YYYY-MM-DD. - `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. - `pendingChargeDueDate` string — The date by when the next pending (not yet due) charge must be paid in the format YYYY-MM-DD. - `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. - `bcdBalancePerYear` object[], required — An array containing balance charge debit payment details. - `taxYear` string, required — The tax year for the appropriate balance charge debit. - `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. - `earliestPaymentDateOverdue` string — The next day after the payment due date in the format YYYY-MM-DD - `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. - `amountCodedOut` number — The total amount of underpayment codeout. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `totalBcdBalance` number — The total of the Balance charge debit balance amount. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places - `unallocatedCredit` number — 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. - `allocatedCredit` number — 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. - `totalCredit` number — Sum of unallocated credit + allocated credit. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `firstPendingAmountRequested` number — This will be the first pending amount that is requested. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `secondPendingAmountRequested` number — This will be the second pending amount that is requested. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `availableCredit` number — 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. - `codingDetails` object[] — An Object containing coding details - `returnTaxYear` string — The ending year of the tax year to which the return relates is in the format YYYY-YY. - `totalLiabilityAmount` number — 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. - `codingTaxYear` string — The tax year that the coded out charge will be attached to. - `coded` object — An object containing a coded amount and initiation date - `charge` number — The coded out charge. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places. - `initiationDate` string — Initiation date of the coded out charge, in the format YYYY-MM-DD. - `documentDetails` object[] — An array containing document details - `taxYear` string — 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. - `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,12}$ - `formBundleNumber` string — The form bundle number designates a package of related transactions gathered together. - `creditReason` 'Voluntary Payment' | 'Income tax Self Assessment Return' | 'Excess Payment' — Credit Reason gives the reason as to why there is a credit on the account. - `documentDate` string, required — The date when the document for a particular tax group containing charges was created in the format YYYY-MM-DD. - `documentText` string — Provides details about the tax group that the charge belongs to. - `documentDueDate` string — The date the item must be received in the format YYYY-MM-DD. - `documentDescription` 'ITSA- POA 1' | 'ITSA - POA 2' | 'ITSA- Bal Charge' | 'New Charge' | 'Clearing Document' | 'TRM New Charge' | 'TRM Amend Charge' | 'Payment' | 'Repayment' — The primary method to identify what type of document has been called. - `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. - `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. - `lastClearing` object — Details if the amount was previously modified. - `lastClearingDate` string — The date the outstanding amount was last modified, in the format YYYY-MM-DD. - `lastClearingReason` 'Incoming Payment' | 'Outgoing Payment' | 'Other' | 'Write-Off' | 'Reversal' — The reason for the change. For example, an interest charge was created. - `lastClearedAmount` number — The amount the transaction was last modified by. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `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. - `isCodedOut` boolean, required — An indicator to represent that the charge has been sent for coding out. - `paymentLot` string — A unique identifier for a credit that has been made direct to ETMP. - `paymentLotItem` string — A unique ID that is used in combination with Payment Lot to refer to an individual payment. - `effectiveDateOfPayment` string — The effective date of payment in the format YYYY-MM-DD. - `latePaymentInterest` object — An object containing late payment interest details. - `latePaymentInterestId` string — Late Payment Interest ID is the Charge Reference Number of all the monthly and final interest charges of the same parent charge. - `accruingInterestAmount` number — 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. - `interestRate` number — The latest interest rate for late payments. The value must be between 0 and 99.99 to 2 decimal places. - `interestStartDate` string — The date the interest charges started in the format YYYY-MM-DD. - `interestEndDate` string — The date the interest charges ended in the format YYYY-MM-DD. - `interestAmount` number — 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. - `interestDunningLockAmount` number — 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. - `interestOutstandingAmount` number — TThe unpaid amount of Accruing Interest or Late Payment Interest. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `amountCodedOut` number — 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. - `reducedCharge` object — Details if Charge has been reduced. - `chargeType` string — Document name of charge reduced. This will be the Charge type name of the original charge - `documentNumber` string — If Charge has been reduced, and credit arises, the document number to be shown. This will be the SAP Document number of this document - `amendmentDate` string — 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. - `taxYear` string — Tax Year of Charge that has been reduced. This is the tax year on the original charge. - `poaRelevantAmount` number — Payments on account relevant amount. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `financialDetails` object[] - `taxYear` string, required — The tax year to which the charge relates, in the format YYYY-YY - `chargeDetail` object, required - `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,12}$ - `documentType` string — A unique ID is used to reference the document type of which this is a subitem. - `documentTypeDescription` string — The Description of the main charge type - `chargeType` string — A unique ID is used to identify the type of sub-item. - `chargeTypeDescription` string — Name of charge type. Must conform to the regular expression: ^[0-9A-Za-z]{1,30}$ - `taxPeriodFrom` string — The 'from' date of this tax period. Date in the format: YYYY-MM-DD - `taxPeriodTo` string — The 'to' date of this tax period. Date in the format: YYYY-MM-DD - `contractAccount` string — A contract account is the accounting record for a particular charge type. - `documentNumber` string — 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}$ - `documentNumberItem` string — An identifier for this part of the overall transaction is used to link an allocation and charge. - `chargeReference` string — A unique reference number is associated with the charge. - `originalAmount` number — The original amount of this transaction. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `outstandingAmount` number — The remaining amount is due on this transaction. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `clearedAmount` number — 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. - `accruedInterest` number — 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 - `items` object[], required — This endpoint enables you to retrieve the history of changes to a single charge made by HMRC. A National Insurance number and transaction ID must be provided. - `itemId` string — An identifier for the item in the list. - `dueDate` string — 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 - `amount` number — The amount that this entry changed the transaction by. The value must be between -99999999999.99 and 99999999999.99 to 2 decimal places. - `clearingDate` string — The date this entry changed the item, in the format YYYY-MM-DD. - `clearingReason` 'Incoming Payment' | 'Outgoing Payment' | 'Reversal' | 'Manual Clearing' | 'Automatic Clearing' — The reason for the change to the item. - `outgoingPaymentMethod` 'Repayment to Card' | 'Payable Order Repayment' | 'BACS Payment out' — The method used to make the outgoing payment. One of Repayment to Card, Payable Order Repayment or BACS Payment out - `locks` object — An object holding the lock fields - `isChargeOnHold` boolean, required — A signal that indicates that the charge has been paused whilst under review or investigation. - `isEstimatedChargeOnHold` boolean, required — A clearing lock is used only for statistical or forecasted charges. - `isInterestAccrualOnHold` boolean, required — Indicates if the charge is not accruing interest due to a review or investigation. - `isInterestChargeOnHold` boolean, required — A lock has been put in so the interest will not be charged to the customer. - `isReturn` boolean — If it is true, that means the charge has been generated by a return. - `paymentReference` string — A unique reference number is associated with the payment. - `paymentAmount` number — 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. - `paymentMethod` string — The method used to make the payment. - `paymentLot` string — 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. - `paymentLotItem` string — A unique ID is used in combination with a payment ID to refer to an individual payment or credit. - `clearingSAPDocument` string — When a payment is used against a charge, this links payment and charge together. - `isChargeEstimate` boolean — Indicates whether the item represents an estimated charge. - `codedOutStatus` 'initiated' | 'not-collected' | 'partly-collected' | 'fully-collected' | 'awaiting-collection' | 'waiting-cancellation' | 'cancelled' | 'rejected' — Indicates whether an amount has been coded out through the PAYE system. ## Other responses - `400` — Bad request - `403` — Forbidden - `404` — Not found --- [API](https://skmtc.net/hmrc/apis/self-assessment-accounts-api.md) · [All operations](https://skmtc.net/hmrc/apis/self-assessment-accounts-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hmrc/self-assessment-accounts-api/revisions/beec40556a41/schema)