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 No

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 a list of charges and payments for a given date range
  • retrieve details about a specific transaction
  • retrieve a list of charges made to an account for a given date range
  • retrieve the history of changes to an individual charge
  • retrieve a list of payments for a given date range
  • retrieve the allocation details of a specific payment against one or more liabilities
  • 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.

Versioning

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

Errors

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

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

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

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

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

Changelog

You can find the changelog in the income-tax-mtd-changelog GitHub wiki.

Support

Testing

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

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

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

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

Skip to main content

Endpoints

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}/balance

Retrieve a Self Assessment Balance [test only]
GET

This endpoint allows a developer to retrieve the overall liability broken down into overdue, currently due (payable) and pending (not yet due) amounts. A unique identifier (National Insurance Number) for the account must be used.

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

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

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.

Response

HTTP status: 200 (OK)

Example response

{
  "overdueAmount": 10.99,
  "payableAmount": 20.99,
  "payableDueDate": "2020-03-01",
  "pendingChargeDueAmount": 30.99,
  "pendingChargeDueDate": "2020-06-01",
  "totalBalance": 62.97,
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/balance",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Example response with nothing due

{
  "overdueAmount": 0.00,
  "payableAmount": 0.00,
  "pendingChargeDueAmount": 0.00,
  "totalBalance": 0.00,
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/balance",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Example response with an overdue payment

{
  "overdueAmount": 10.99,
  "payableAmount": 20.99,
  "payableDueDate": "2020-03-01",
  "pendingChargeDueAmount": 30.99,
  "totalBalance": 62.97,
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/balance",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Response table
Name Description
overdueAmount
number
required

The sum of any non-zero charges whose payment due date has passed.

For example: 1000.25

payableAmount
number
required

The sum of any non-zero charges whose payment due date is imminent.

For example: 1000.25

payableDueDate
string
optional

The date by when the amount is due to be paid. Date in the format YYYY-MM-DD

For example: 2020-03-01

pendingChargeDueAmount
number
required

The sum of any charges whose payment is pending (not yet due).

For example: 1000.25

pendingChargeDueDate
string
optional

The date by when the next pending (not yet due) charge must be paid.

For example: 2020-04-01

totalBalance
number
required

The total of the payable amount, pending charge due amount and over due amount.

For example: 1000.30

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/AA999999A/balance

rel
string
required

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

Limited to the following possible values:

self
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied nino value is invalid.

400 (Bad Request)

FORMAT_NINO

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

The supplied income source could not be 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

Simulate a successful response.

NOTHING_DUE

Simulates a successful response where no payments are due.

OVERDUE

Simulates a successful response where a payment is overdue.

NOT_FOUND

Simulates the scenario where no data can be found.


Close Section
/accounts/self-assessment/{nino}/transactions

List Self Assessment Transactions [test only]
GET

This endpoint allows a developer to retrieve a list of charges and payments for a given date range. A unique identifier (National Insurance Number) for the account must be used and a search period 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
from
string
required

From date to return charges.

Date in the format: YYYY-MM-DD

For example: 2019-05-04

to
string
required

To date to return charges.

Date in the format: YYYY-MM-DD

For example: 2019-06-12

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

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.

Response

HTTP status: 200 (OK)

Example response

{
  "transactions": [
    {
      "taxYear": "2019-20",
      "transactionId": "X1234567890A",
      "transactionDate": "2020-01-01",
      "type": "Balancing Charge Debit",
      "originalAmount": 12.34,
      "outstandingAmount": 10.33,
      "lastClearingDate": "2020-01-02",
      "lastClearingReason": "Incoming payment",
      "lastClearedAmount": 2.01,
      "links": [
        {
          "href": "/accounts/self-assessment/AA999999A/transactions/X1234567890A",
          "method": "GET",
          "rel": "retrieve-transaction-details"
        }
      ]
    },
    {
      "taxYear": "2019-20",
      "transactionId": "X1234567890B",
      "paymentId": "081203010024-000001",
      "transactionDate": "2020-01-05",
      "type": "Payment On Account",
      "originalAmount": 12.34,
      "outstandingAmount": 10.33,
      "lastClearingDate": "2020-01-06",
      "lastClearingReason": "Outgoing payment paid",
      "lastClearedAmount": 2.01,
      "links": [
        {
          "href": "/accounts/self-assessment/AA999999A/payments/081203010024-000001",
          "method": "GET",
          "rel": "retrieve-payment-allocations"
        },
        {
          "href": "/accounts/self-assessment/AA999999A/transactions/X1234567890B",
          "method": "GET",
          "rel": "retrieve-transaction-details"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/transactions?from=2019-01-01&to=2020-01-06",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/accounts/self-assessment/AA999999A/charges?from=2019-01-01&to=2020-01-06",
      "method": "GET",
      "rel": "list-charges"
    },
    {
      "href": "/accounts/self-assessment/AA999999A/payments?from=2019-01-01&to=2020-01-06",
      "method": "GET",
      "rel": "list-payments"
    }
  ]
}

Response table
Name Description
transactions
array
required

A list of one or more charges and payments.

taxYear
string
required

The tax year that this item relates to. In the format YYYY-YY.

For example: 2018-19

transactionId
string
required

A unique identifier for this item.

For example: X123456790A

paymentId
string
optional

A unique identifier for the payment.

For example: 081203010024-000001

transactionDate
string
required

The date the item was created. Date in the format YYYY-MM-DD.

For example: 2018-04-05

type
string
optional

The type of financial transaction.

For example: Balancing charge debit

originalAmount
number
required

The original value of this transaction.

For example: 600.00

outstandingAmount
number
required

The remaining due amount on this transaction.

For example: 600.00

lastClearingDate
string
optional

The date the outstanding amount was last modified. Date in the format YYYY-MM-DD.

For example: 2018-04-05

lastClearingReason
string
optional

The reason for the change.

For example: Incoming Payment

lastClearedAmount
number
optional

The amount the transaction was last modified by.

For example: 600.00

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/AA999999A/payments/081203010024-000001

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:

retrieve-payment-allocations
retrieve-transaction-details
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /accounts/self-assessment/AA999999A/transactions?from=2019-01-01&to=2020-01-06

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
list-charges
list-payments
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied nino value is invalid.

400 (Bad Request)

FORMAT_NINO

The From date is not a valid ISO format date.

400 (Bad Request)

FORMAT_FROM_DATE

The To date is not a valid ISO format date.

400 (Bad Request)

FORMAT_TO_DATE

The From date parameter is missing.

400 (Bad Request)

MISSING_FROM_DATE

The To date parameter is missing.

400 (Bad Request)

MISSING_TO_DATE

The To date is before the From date.

400 (Bad Request)

RANGE_TO_DATE_BEFORE_FROM_DATE

The date range is longer than 732 days.

400 (Bad Request)

RANGE_DATE_TOO_LONG

The from date specified is before 2018-04-06.

400 (Bad Request)

RULE_FROM_DATE_NOT_SUPPORTED

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

The supplied income source could not be 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

Simulate a successful response.

NOT_FOUND

Simulates the scenario where no data can be found.


Close Section
/accounts/self-assessment/{nino}/transactions/{transactionId}

Retrieve a Self Assessment Transaction's Detail [test only]
GET

This endpoint allows a developer to retrieve more detail about a specific transaction. A unique identifier must be used for both the account (National Insurance number) and the transaction (transactionId).

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

Must conform to the regular expression
^[0-9A-Za-z]{1,12}$

For example: X92AM39DLE3D

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

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.

Response

HTTP status: 200 (OK)

Payment example

{
  "transactionItems": [
    {
      "transactionItemId": "0001",
      "type": "Payment on account",
      "originalAmount": -5000.45,
      "outstandingAmount": 0.00,
      "dueDate": "2021-01-31",
      "paymentMethod": "BACS RECEIPTS",
      "paymentId": "P01010180112-000001",
      "subItems": [
        {
          "subItemId": "002",
          "clearingDate": "2021-01-31",
          "clearingReason": "Payment allocation",
          "paymentAmount": 1100.21
        },
        {
          "subItemId": "003",
          "clearingDate": "2021-01-31",
          "clearingReason": "Payment allocation",
          "paymentAmount": 3000.22
        },
        {
          "subItemId": "004",
          "amount": -900.12,
          "clearingDate": "2021-01-31",
          "clearingReason": "Outgoing Payment - Paid",
          "paymentMethod": "Payable Order Repayment"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/accounts/self-assessment/AA123456A/transactions/X92AM39DLE3D",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/accounts/self-assessment/AA123456A/payments/P01010180112-000001",
      "method": "GET",
      "rel": "retrieve-payment-allocations"
    }
  ]
}

Charge example

{
  "transactionItems": [
    {
      "transactionItemId": "0001",
      "type": "National Insurance Class 2",
      "taxPeriodFrom": "2019-04-06",
      "taxPeriodTo": "2020-04-05",
      "originalAmount": 100.45,
      "outstandingAmount": 0.00,
      "dueDate": "2021-01-31",
      "subItems": [
        {
          "subItemId": "002",
          "amount": 110.56,
          "clearingDate": "2021-01-31",
          "clearingReason": "Incoming payment",
          "paymentAmount": 110.56,
          "paymentMethod": "BACS RECEIPTS",
          "paymentId": "P01010180112-000005"
        },
        {
          "subItemId": "003",
          "amount": -10.11,
          "clearingDate": "2021-01-31",
          "clearingReason": "Outgoing payment - Paid",
          "outgoingPaymentMethod": "Payable Order Repayment"
        }
      ]
    },
    {
      "transactionItemId": "0002",
      "type": "National Insurance Class 4",
      "taxPeriodFrom": "2019-04-06",
      "taxPeriodTo": "2020-04-05",
      "originalAmount": 100.23,
      "outstandingAmount": 10.45,
      "dueDate": "2021-01-31",
      "subItems": [
        {
          "subItemId": "002",
          "amount": 89.78,
          "clearingDate": "2021-01-31",
          "clearingReason": "Incoming payment",
          "paymentAmount": 89.78,
          "paymentMethod": "BACS RECEIPTS",
          "paymentId": "P01010180112-000006"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/accounts/self-assessment/AA123456A/transactions/X92AM39DLE3D",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Response table
Name Description
transactionItems
array
required

A list of the items that make up the overall transaction. The items may include subitems.

transactionItemId
string
optional

An identifier for this part of the overall transaction.

For example: X234567891BY-AT3579

type
string
optional

The type of financial transaction.

For example: National Insurance Class 2

taxPeriodFrom
string
optional

The 'from' date of this tax period. Date in the format: YYYY-MM-DD

For example: 2019-04-06

taxPeriodTo
string
optional

The 'to' date of this tax period. Date in the format: YYYY-MM-DD

For example: 2020-04-05

originalAmount
number
optional

The original value of this transaction.

For example: 600.00

outstandingAmount
number
optional

The remaining amount due on this transaction.

For example: 600.00

dueDate
string
optional

The date by when the amount is due to be paid. Date in the format: YYYY-MM-DD

For example: 2021-01-31

paymentMethod
string
optional

The method used to make the payment.

For example: BACS RECEIPTS

paymentId
string
optional

The unique identifier for the payment.

For example: AB1023456789-000001

subItems
array
required

The list of updates to this part of the charge or payment.

subItemId
string
optional

The unique identifier for this entry.

For example: 001

amount
number
optional

The amount that this entry changed the transaction by.

For example: 350.00

clearingDate
string
optional

The date this entry changed the item. Date in the format: YYYY-MM-DD

For example: 2020-01-21

clearingReason
string
optional

The reason given for clearing

For example: Incoming payment

outgoingPaymentMethod
string
optional

The method used to make the outgoing payment.

For example: Payable Order Repayment

paymentAmount
number
optional

The amount that this entry changed the transaction by.

For example: 350.00

paymentMethod
string
optional

The method used to make the payment.

For example: BACS RECEIPTS

paymentId
string
optional

The unique identifier for the payment.

For example: AB1023456789-000001

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/AA123456A/transactions/X92AM39DLE3D

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
retrieve-payment-allocations
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

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

No transaction details found for the supplied transaction ID.

404 (Not Found)

NO_DETAILS_FOUND

The supplied income source could not be 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

Simulate a successful response with a charge.

PAYMENT_ON_ACCOUNT

Simulate a successful response with a payment.

NO_DETAILS_FOUND

Simulate the scenario where no transaction details can be found for this transaction ID.

NOT_FOUND

Simulates the scenario where no data can be found.


Close Section
/accounts/self-assessment/{nino}/charges

List Self Assessment Charges [test only]
GET

This endpoint allows a developer to retrieve the details of charges made to an account between two dates. A unique identifier (National Insurance Number) for the account must be used and a valid date range 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
from
string
required

From date to return charges.

Date in the format: YYYY-MM-DD

For example: 2019-05-04

to
string
required

To date to return charges.

Date in the format: YYYY-MM-DD

For example: 2019-06-12

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

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.

Response

HTTP status: 200 (OK)

{
  "charges": [
    {
      "taxYear": "2018-19",
      "transactionId": "1234567890AB",
      "transactionDate": "2019-01-01",
      "type": "Balancing Charge Debit",
      "totalAmount": 100.23,
      "outstandingAmount": 50.01,
      "links": [
        {
          "href": "/accounts/self-assessment/AA999999A/transactions/1234567890AB",
          "method": "GET",
          "rel": "retrieve-transaction-details"
        }
      ]
    }
  ],
  "links":[
    {
      "href": "/accounts/self-assessment/AA999999A/charges?from=2018-07-01&to=2019-01-01",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/accounts/self-assessment/AA999999A/transactions?from=2018-07-01&to=2019-01-01",
      "method": "GET",
      "rel": "list-transactions"
    }
  ]
}

Response table
Name Description
charges
array
required

A list of charges.

taxYear
string
required

The tax year that this charge relates to in the format: YYYY-YY.

For example: 2019-20

transactionId
string
required

A unique identifier for the charge.

For example: 1234567890AB

transactionDate
string
required

The date the charge was created.

For example: 2019-08-11

type
string
optional

A description of the type of charge.

For example: Balancing Charge Debit

totalAmount
number
required

The original amount of the charge.

For example: 1000.25

outstandingAmount
number
required

The amount of the charge still due.

For example: 1000.25

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/AA999999A/transactions/1234567890AB

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:

retrieve-transaction-details
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /accounts/self-assessment/AA999999A/charges?from=2018-07-01&to=2019-01-01

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
list-transactions
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied nino value is invalid.

400 (Bad Request)

FORMAT_NINO

The From date is not a valid ISO format date.

400 (Bad Request)

FORMAT_FROM_DATE

The To date is not a valid ISO format date.

400 (Bad Request)

FORMAT_TO_DATE

The From date parameter is missing.

400 (Bad Request)

MISSING_FROM_DATE

The To date parameter is missing.

400 (Bad Request)

MISSING_TO_DATE

The To date is before the From date.

400 (Bad Request)

RANGE_TO_DATE_BEFORE_FROM_DATE

The date range is longer than 732 days.

400 (Bad Request)

RULE_DATE_RANGE_INVALID

The from date specified is before 2018-04-06.

400 (Bad Request)

RULE_FROM_DATE_NOT_SUPPORTED

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

The supplied income source could not be 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

Simulate a successful response.

NOT_FOUND

Simulates the scenario where no data can be found.


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

Retrieve a Self Assessment Charge's History [test only]
GET

This endpoint allows a developer to retrieve the history of changes to an individual charge. A unique identifier (National Insurance Number) for the account must be used and a charge identifier 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,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.1.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.

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.

Response

HTTP status: 200 (OK)

{
  "history": [
    {
      "taxYear": "2019-20",
      "transactionId": "X123456790A",
      "transactionDate": "2019-06-01",
      "type": "Balancing Charge Debit",
      "amount": 600.01,
      "reversalDate": "2019-06-05",
      "reversalReason": "Customer request"
    }
  ],
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/charges/X1234567890A",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "/accounts/self-assessment/AA999999A/transactions/X1234567890A",
      "method": "GET",
      "rel": "retrieve-transaction-details"
    }
  ]
}

Response table
Name Description
history
array
required

A list of changes to one or more charges.

taxYear
string
optional

The tax year that this charge relates to in the format: YYYY-YY.

For example: 2018-19

transactionId
string
required

A unique identifier for this charge.

For example: X123456790A

transactionDate
string
optional

The date the charge was created. Date in the format: YYYY-MM-DD.

For example: 2018-04-05

type
string
optional

The type of financial transaction.

For example: Balancing Charge Debit

amount
number
optional

The original value of this transaction.

For example: 600.00

reversalDate
string
optional

The date the charge was changed. Date in the format: YYYY-MM-DD.

For example: 2018-04-05

reversalReason
string
optional

The reason for the change.

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/{nino}/charges/{transactionId}

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
retrieve-transaction-details
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied nino value is invalid.

400 (Bad Request)

FORMAT_NINO

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

The supplied income source could not be 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

Simulate a successful response.

NOT_FOUND

Simulates the scenario where no data can be found.


Close Section
/accounts/self-assessment/{nino}/payments

List Self Assessment Payments [test only]
GET

This endpoint allows a developer to retrieve a list of payments for a given date range. A unique identifier (National Insurance Number) for the account must be used and a valid date range 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
from
string
required

From date to return payments.

Date in the format: YYYY-MM-DD

For example: 2019-05-04

to
string
required

To date to return payments.

Date in the format: YYYY-MM-DD

For example: 2019-06-12

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

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.

Response

HTTP status: 200 (OK)

{
  "payments":[
    {
      "paymentId":"123456789012-123456",
      "amount":11.99,
      "method":"Payment by Card",
      "transactionDate":"2019-02-26",
      "links":[
        {
          "href":"/accounts/self-assessment/AA123456A/payments/123456789012-123456",
          "method":"GET",
          "rel":"retrieve-payment-allocations"
        }
      ]
    },
    {
      "paymentId":"223456789012-123456",
      "amount":12.99,
      "method":"Payment by Card",
      "transactionDate":"2019-02-27",
      "links":[
        {
          "href":"/accounts/self-assessment/AA123456A/payments/223456789012-123456",
          "method":"GET",
          "rel":"retrieve-payment-allocations"
        }
      ]
    }
  ],
  "links":[
    {
      "href":"/accounts/self-assessment/AA123456A/payments?from=2018-01-01&to=2019-01-01",
      "method":"GET",
      "rel":"self"
    },
    {
      "href":"/accounts/self-assessment/AA123456A/transactions?from=2018-01-01&to=2019-01-01",
      "method":"GET",
      "rel":"list-transactions"
    }
  ]
}

Response table
Name Description
payments
array
required

A list of payments.

paymentId
string
optional

A unique identifier for the payment.

For example: X234567891BY-AT3579

amount
number
optional

The amount of the payment received into the account.

For example: 1000.25

method
string
optional

The method used to make the payment.

For example: Payment by Card

transactionDate
string
optional

The date the payment was received into the account. Date in the format: YYYY-MM-DD.

For example: 2019-12-29

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/{nino}/payments/{paymentId}

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:

retrieve-payment-allocations
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /accounts/self-assessment/{nino}/payments?from={from}&to={to}

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
list-transactions
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied nino value is invalid.

400 (Bad Request)

FORMAT_NINO

The From date is not a valid ISO format date.

400 (Bad Request)

FORMAT_FROM_DATE

The To date is not a valid ISO format date.

400 (Bad Request)

FORMAT_TO_DATE

The From date parameter is missing.

400 (Bad Request)

MISSING_FROM_DATE

The To date parameter is missing.

400 (Bad Request)

MISSING_TO_DATE

The To date is before the From date.

400 (Bad Request)

RANGE_TO_DATE_BEFORE_FROM_DATE

The date range is longer than 732 days.

400 (Bad Request)

RULE_DATE_RANGE_INVALID

The from date specified is before 2018-04-06.

400 (Bad Request)

RULE_FROM_DATE_NOT_SUPPORTED

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

The supplied income source could not be 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

Simulate a successful response.

NOT_FOUND

Simulates the scenario where no data can be found.


Close Section
/accounts/self-assessment/{nino}/payments/{paymentId}

Retrieve a Self Assessment Payment's Allocation Details [test only]
GET

This endpoint allows a developer to retrieve the allocation details of a specific payment against one or more liabilities. The unique identifier must be used for both the account (National Insurance Number) and the payment (Payment Reference).

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

paymentId
string
required

A unique identifier for the payment.

Must conform to the regular expression: ^[0-9A-Za-z]{1,12}-[0-9A-Za-z]{1,6}$

For example: X234567891BY-AT3456

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

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.

Response

HTTP status: 200 (OK)

Example Response with Allocations

{
  "amount": 2000.00,
  "method": "Payment by Card",
  "transactionDate": "2020-01-29",
  "allocations": [
    {
      "transactionId": "XA012599973Z11",
      "from": "2018-04-06",
      "to": "2019-04-05",
      "type": "ITSA Balancing Charge Debit",
      "amount": 400.00,
      "clearedAmount": 400.00,
      "links": [
        {
          "href": "/accounts/self-assessment/AA999999A/charges/XA012599973Z11",
          "method": "GET",
          "rel": "retrieve-charge-history"
        },
        {
          "href": "/accounts/self-assessment/AA999999A/transactions/XA012599973Z11",
          "method": "GET",
          "rel": "retrieve-transaction-details"
        }
      ]
    },
    {
      "transactionId": "XA012599973Z12",
      "from": "2019-04-06",
      "to": "2020-04-05",
      "type": "ITSA Payment On Account Charge",
      "amount": 800.00,
      "clearedAmount": 800.00,
      "links": [
        {
          "href": "/accounts/self-assessment/AA999999A/charges/XA012599973Z12",
          "method": "GET",
          "rel": "retrieve-charge-history"
        },
        {
          "href": "/accounts/self-assessment/AA999999A/transactions/XA012599973Z12",
          "method": "GET",
          "rel": "retrieve-transaction-details"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/payments/X23456789012-A23456",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Example Response with no Allocations

{
  "amount": 3000.00,
  "method": "Payment by Card",
  "transactionDate": "2020-02-27",
  "allocations": [
  ],
  "links": [
    {
      "href": "/accounts/self-assessment/AA999999A/payments/123456789012-123456",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Response table
Name Description
amount
number
optional

The amount of the payment received into the account.

For example: 1000.25

method
string
optional

The method used to make the payment.

For example: Payment by Card

transactionDate
string
optional

The date the payment was received into the account. Date in the format: YYYY-MM-DD.

For example: 2019-12-29

allocations
array
required

A list of charges, allocated amounts from the payment.

transactionId
string
optional

The unique identifier for the charge.

For example: XA012599973Z11

from
string
optional

The 'from' date of this tax period. Date in the format: YYYY-MM-DD.

For example: 2019-11-29

to
string
optional

The 'to' date of this tax period. Date in the format: YYYY-MM-DD.

For example: 2019-12-29

type
string
optional

The type of financial transaction.

For example: ITSA

amount
number
optional

The original value of this transaction.

For example: 100.25

clearedAmount
number
optional

The cleared value of this transaction.

For example: 100.25

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/AA999999A/charges/{transactionId}

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:

retrieve-charge-history
retrieve-transaction-details
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
links
array
optional

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

href
string
required

The relative url of the endpoint

For example: /accounts/self-assessment/AA999999A/payments/{paymentId}

rel
string
required

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

Limited to the following possible values:

self
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

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 payment identifier field is not valid.

400 (Bad Request)

FORMAT_PAYMENT_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

The supplied income source could not be 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

Simulate a successful response.

NO_ALLOCATIONS

Simulates a successful response with no allocations.

NOT_FOUND

Simulates the scenario where no data can be found.


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 [test only]
GET

This endpoint allows the developer to retrieve HMRC-held coding out underpayment and debt amounts, or user submitted coding out amounts for a previous tax year and given NINO.

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

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.

Response

HTTP status: 200 (OK)

Example Response

{
  "taxCodeComponents": {
    "selfAssessmentUnderpayment": [
      {
        "amount": 89.78,
        "relatedTaxYear": "2021-22",
        "submittedOn": "2021-08-24T14:15:22Z",
        "source": "user",
        "id": 1234567891
      }
    ],
    "payeUnderpayment": [
      {
        "amount": 14.45,
        "relatedTaxYear": "2021-22",
        "submittedOn": "2021-08-24T14:15:22Z",
        "source": "user",
        "id": 1234567891
      }
    ],
    "debt": [
      {
        "amount": 12.01,
        "relatedTaxYear": "2021-22",
        "submittedOn": "2021-08-24T14:15:22Z",
        "source": "user",
        "id": 1234567891
      }
    ],
    "inYearAdjustment": {
      "amount": 75.99,
      "relatedTaxYear": "2021-22",
      "submittedOn": "2021-08-24T14:15:22Z",
      "source": "user",
      "id": 1234567891
    }
  },
  "unmatchedCustomerSubmissions": {
    "selfAssessmentUnderpayment": [
      {
        "amount": 12.32,
        "submittedOn": "2021-08-24T14:15:22Z",
        "id": 1234567891
      }
    ],
    "payeUnderpayment": [
      {
        "amount": 71.99,
        "submittedOn": "2021-08-24T14:15:22Z",
        "id": 1234567891
      }
    ],
    "debt": [
      {
        "amount": 54.79,
        "submittedOn": "2021-08-24T14:15:22Z",
        "id": 1234567891
      }
    ],
    "inYearAdjustment": {
      "amount": 56.74,
      "submittedOn": "2021-08-24T14:15:22Z",
      "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
required

The ID for the Self Assessment underpayment.

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:ssZ.

For example: 2020-07-06T09:37:17Z

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
required

The ID for the PAYE underpayment.

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:ssZ.

For example: 2020-07-06T09:37:17Z

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
required

The ID for the coded out debts.

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:ssZ.

For example: 2020-07-06T09:37:17Z

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
required

The ID for the HMRC classified debts.

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:ssZ.

For example: 2020-07-06T09:37:17Z

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
required

The ID for the Self Assessment underpayment.

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:ssZ.

For example: 2020-07-06T09:37:17Z

payeUnderpayment
array
optional

Array containing details of coded out PAYE underpayments.

id
number
required

The ID for the PAYE underpayment.

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:ssZ.

For example: 2020-07-06T09:37:17Z

debt
array
optional

Array containing details of coded out debts.

id
number
required

The ID for the coded out debts.

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:ssZ.

For example: 2020-07-06T09:37:17Z

inYearAdjustment
object
optional

Details of coded out in-year adjustments

id
number
required

The ID for the HMRC classified debts.

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:ssZ.

For example: 2020-07-06T09:37:17Z

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 taxYear is not supported. The taxYear specified is before the minimum 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 underpayment and debt amounts [test only]
PUT

This endpoint allows the developer to overwrite coding out underpayment and debt amounts held by HMRC for a previous tax year and given NINO, and 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.1.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

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.

Response

HTTP status: 200 (OK)

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 taxYear is not supported. The taxYear specified is before the minimum 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

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

Delete Coding Out underpayments and debt amounts [test only]
DELETE

This endpoint allows the developer to delete custom coding out amounts for a given tax year and NINO.

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

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.

Response

HTTP status: 204 (No Content)

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 taxYear is not supported. The taxYear specified is before the minimum 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