Individual Losses (MTD) API
Date | Amount |
---|---|
Version and status | |
Available in Sandbox | Yes |
Sandbox base URL | https://test-api.service.hmrc.gov.uk |
Available in Production | Yes |
Production base URL | https://api.service.hmrc.gov.uk |
Overview
This API allows developers to provide financial data for Brought Forward Losses and Loss Claims.
For Brought Forward losses a developer can:
- provide a list of brought forward losses
- create a new brought forward loss
- show a single brought forward loss
- update an existing brought forward loss
- delete an existing brought forward loss
For Loss claims a developer can:
- provide a list of loss claims
- create a loss claim against an income source for a specific tax year
- show the detail of an existing loss claim
- update a previously entered loss claim
- delete an existing loss claim
For information on how to connect to this API see the Income Tax MTD end-to-end service guide .
Send fraud prevention data
HMRC monitors transactions to help protect your customers' confidential data from criminals and fraudsters.
Check the data you need to send. You can also use the Test API during initial development and as part of your quality assurance checks.
Versioning
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
Errors
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
Single errors will be returned in the following format:
{ "code": "FORMAT_FIELD_NAME", "message": "The provided FieldName is invalid"
}
Where possible, multiple errors will be returned with INVALID_REQUEST
in the following format:
{ "code": "INVALID_REQUEST", "message": "Invalid request", "errors": [
{ "code": "RULE_FIELD_NAME", "message": "The provided FieldName is not allowed"
}, { "code": "FORMAT_FIELD_NAME", "message": "The provided FieldName is invalid"
} ]
}
Where it is possible for the same error to be returned multiple times, message
will describe the expected format
and paths
will show the fields which are invalid.
Where arrays are submitted a number indicates the object in the array sequence, for example, /arrayName/1/fieldName
.
An example with single error:
{ "code": "FORMAT_STRING_NAME", "message": "The provided field is not valid", "paths": [ "/arrayName/0/fieldName" ]
}
An example with multiple errors:
{ "code": "INVALID_REQUEST", "message": "Invalid request", "errors": [
{ "code": "FORMAT_VALUE", "message": "The value should be between 0 and 99999999999.99", "paths": [ "/objectName/fieldName1", "/arrayName/0/fieldName2" ]
}, { "code": "FORMAT_STRING_NAME", "message": "The provided field is not valid", "paths": [ "/arrayName/0/fieldName3", "/arrayName/1/fieldName3" ]
} ]
}
Changelog
You can find the changelog in the income-tax-mtd-changelog GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the income-tax-mtd-changelog GitHub page.
Testing
You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.
It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.
If you have a specific testing need that is not supported in the sandbox, contact our support team.
Some APIs may be marked [test only]. This means that they are not available for use in production and may change.
Endpoints
Brought Forward Losses
Resources related to a customer’s financial data for their brought forward losses.
Brought Forward Losses resources
/individuals/losses/{nino}/brought-forward-losses
List Brought Forward Losses
GET
This endpoint allows a developer to retrieve a list of all brought forward losses that have incurred before joining MTD. A National Insurance number must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Query parameters
Name | Description |
---|---|
businessId
string
optional
|
An identifier for the business, unique to the customer.
For example: |
typeOfLoss
string
optional
|
The type of business the loss applies to.
|
taxYearBroughtForwardFrom
string
optional
|
The tax year to which the loss applies. The start year and end year must not span two tax years. No gaps are allowed, for example, 2020-22 is not valid. The minimum tax year is 2018-19. The tax year must have ended.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "losses": [ { "lossId": "A2Za0911235813a", "businessId": "XBIS12345678901", "typeOfLoss": "self-employment", "lossAmount": 9420.01, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-02T11:55:55.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/A2Za0911235813a", "rel": "self", "method": "GET" } ] }, { "lossId": "A2Za0911235813b", "businessId": "XBIS12345678902", "typeOfLoss": "self-employment-class4", "lossAmount": 3298.50, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-03T11:55:55.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/A2Za0911235813b", "rel": "self", "method": "GET" } ] }, { "lossId": "A2Za0911235813c", "businessId": "XPIS12345678903", "typeOfLoss": "uk-property-fhl", "lossAmount": 1882.99, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-04T11:55:55.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/A2Za0911235813c", "rel": "self", "method": "GET" } ] }, { "lossId": "A2Za0911235813d", "businessId": "XPIS12345678904", "typeOfLoss": "uk-property-non-fhl", "lossAmount": 4882.99, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-05T11:55:55.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/A2Za0911235813d", "rel": "self", "method": "GET" } ] }, { "lossId": "A2Za0911235813e", "businessId": "XFIS12345678905", "typeOfLoss": "foreign-property-fhl-eea", "lossAmount": 2985.99, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-06T11:55:55.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/A2Za0911235813e", "rel": "self", "method": "GET" } ] }, { "lossId": "A2Za0911235813f", "businessId": "XFIS12345678906", "typeOfLoss": "foreign-property", "lossAmount": 3553.99, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-07T11:55:55.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/A2Za0911235813f", "rel": "self", "method": "GET" } ] } ], "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses", "rel": "create-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses", "rel": "self", "method": "GET" } ] }
Name | Description |
---|---|
losses
array
required
|
Array of losses. An empty array will never be returned. In the instance that no losses exist for the supplied NINO, a MATCHING_RESOURCE_NOT_FOUND error will be returned. |
lossId
string
required
|
The unique identifier of the loss.
Must conform to the regular expression
For example: |
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
self-employment-class4
uk-property-fhl
uk-property-non-fhl
foreign-property-fhl-eea
foreign-property
|
lossAmount
number
required
|
Brought Forward Loss amount related to the type of loss specified. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
taxYearBroughtForwardFrom
string
required
|
The tax year to which the loss applies. The start year and end year must not span two tax years. No gaps are allowed, for example, 2020-22 is not valid. The minimum tax year is 2018-19. The tax year must have ended.
For example: |
lastModified
string
required
|
The timestamp when the entry was created or last modified.
Must conform to the regular expression
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
|
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: |
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
create-brought-forward-loss
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
Tax year range invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
The format of the supplied Business ID field is not valid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
The format of the supplied type of loss field is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_LOSS |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
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 success response with multiple business types. |
SELF_EMPLOYMENT |
Simulates success response with only self-employment. |
UK_PROPERTY |
Simulates success response with only UK property. |
FOREIGN_PROPERTY |
Simulates success response with only foreign property. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/brought-forward-losses
Create a Brought Forward Loss
POST
This endpoint allows the developer to create a new brought forward loss which can be submitted against self-employment, self-employment class 4, UK Furnished Holiday Let (FHL) property, UK other (Non-FHL) property, foreign property FHL in the European Economic Area (EEA) and foreign property for the tax year prior to joining MTD. A National Insurance number must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
Scenario: Self-Employment Request
{ "taxYearBroughtForwardFrom": "2020-21", "businessId": "XBIS12345678910", "typeOfLoss": "self-employment", "lossAmount": 5001.99 }
Scenario: UK FHL Property Request
{ "taxYearBroughtForwardFrom": "2020-21", "businessId": "XPIS12345678910", "typeOfLoss": "uk-property-fhl", "lossAmount": 500.99 }
Scenario: Foreign Property Request
{ "taxYearBroughtForwardFrom": "2020-21", "businessId": "XFIS12345678910", "typeOfLoss": "foreign-property", "lossAmount": 5000.99 }
Name | Description |
---|---|
taxYearBroughtForwardFrom
string
required
|
The tax year to which the loss applies. The start year and end year must not span two tax years. No gaps are allowed, for example, 2020-22 is not valid. The minimum tax year is 2018-19. The tax year must have ended.
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
self-employment-class4
uk-property-fhl
uk-property-non-fhl
foreign-property-fhl-eea
foreign-property
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
lossAmount
number
required
|
Brought Forward Loss amount related to the type of loss specified. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Responses
HTTP status 201 (Created)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "lossId": "AAZZ1234567890a", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a/change-loss-amount", "rel": "amend-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "delete-brought-forward-loss", "method": "DELETE" } ] }
Name | Description |
---|---|
lossId
string
required
|
The unique identifier of the loss.
Must conform to the regular expression
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
amend-brought-forward-loss
delete-brought-forward-loss
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
DELETE
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
Tax year range invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
The format of the supplied Business ID field is not valid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
The format of the supplied type of loss field is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_LOSS |
The submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
The remote endpoint has indicated that the submission already exists for this resource. |
403 (Forbidden) |
RULE_DUPLICATE_SUBMISSION |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
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 |
Simulates success response. |
NOT_FOUND |
Simulates the scenario where no data is found. |
DUPLICATE_SUBMISSION |
Simulates the scenario where a duplicated loss is found. |
Close Section
/individuals/losses/{nino}/brought-forward-losses/{lossId}
Retrieve a Brought Forward Loss
GET
This endpoint allows the developer to retrieve an existing brought forward loss amount. A National Insurance number and Loss ID must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
lossId
string
required
|
A unique identifier for loss.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Self-Employment Loss
{ "businessId": "XBIS12345678911", "typeOfLoss": "self-employment", "lossAmount": 300.11, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-11-05T11:56:27Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a/change-loss-amount", "rel": "amend-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "delete-brought-forward-loss", "method": "DELETE" } ] }
UK FHL Property Loss
{ "businessId": "XPIS12345678912", "typeOfLoss": "uk-property-fhl", "lossAmount": 423.32, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-02T12:56:58Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a/change-loss-amount", "rel": "amend-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "delete-brought-forward-loss", "method": "DELETE" } ] }
Foreign Property Loss
{ "businessId": "XFIS12345678913", "typeOfLoss": "foreign-property", "lossAmount": 553.32, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-12-02T11:55:55Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a/change-loss-amount", "rel": "amend-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "delete-brought-forward-loss", "method": "DELETE" } ] }
Name | Description |
---|---|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
self-employment-class4
uk-property-fhl
uk-property-non-fhl
foreign-property-fhl-eea
foreign-property
|
lossAmount
number
required
|
Brought Forward Loss amount related to the type of loss specified. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
taxYearBroughtForwardFrom
string
required
|
The tax year to which the loss applies. The start year and end year must not span two tax years. No gaps are allowed, for example, 2020-22 is not valid. The minimum tax year is 2018-19. The tax year must have ended.
For example: |
lastModified
string
required
|
The timestamp when the entry was created or last modified.
Must conform to the regular expression
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
amend-brought-forward-loss
delete-brought-forward-loss
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
DELETE
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied Loss ID is not valid. |
400 (Bad Request) |
FORMAT_LOSS_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
The remote endpoint has indicated that no data can be found for the given loss ID. |
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 success response where type of loss is Self-Employment. |
UK_PROPERTY |
Simulates the scenario where type of loss is UK Property FHL. |
FOREIGN_PROPERTY |
Simulates the scenario where type of loss is Foreign Property. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/brought-forward-losses/{lossId}
Delete a Brought Forward Loss
DELETE
This endpoint allows a developer to delete an existing brought forward loss. A National Insurance number and Loss ID must be provided. The user should be aware that where a loss has been used as part of a successful final declaration activity, deletion will be blocked and an error code will be returned. In such a case, the user can amend the loss amount to zero.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
lossId
string
required
|
A unique identifier for loss.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied Loss ID is not valid. |
400 (Bad Request) |
FORMAT_LOSS_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
The remote endpoint has indicated that the requested resource has been locked. |
403 (Forbidden) |
RULE_DELETE_AFTER_FINAL_DECLARATION |
The remote endpoint has indicated that no data can be found for the given loss ID. |
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 success response. |
DELETE_AFTER_FINAL_DECLARATION |
Simulates the error scenario where the user has already submitted a final declaration for this tax year. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/brought-forward-losses/{lossId}/change-loss-amount
Amend a Brought Forward Loss Amount
POST
This endpoint allows the developer to update an existing brought forward loss amount. A National Insurance number and Loss ID must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
lossId
string
required
|
A unique identifier for loss.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "lossAmount": 3456.78 }
Name | Description |
---|---|
lossAmount
number
required
|
Brought Forward Loss amount related to the type of loss specified. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Self-Employment Class 4 Loss
{ "businessId": "XBIS12345678910", "typeOfLoss": "self-employment-class4", "lossAmount": 3456.78, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-07-13T12:13:48.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a/change-loss-amount", "rel": "amend-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "delete-brought-forward-loss", "method": "DELETE" } ] }
UK Non-FHL Property Loss
{ "businessId": "XPIS12345678910", "typeOfLoss": "uk-property-non-fhl", "lossAmount": 3456.78, "taxYearBroughtForwardFrom": "2021-22", "lastModified": "2022-07-13T12:13:48.763Z", "links": [ { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a/change-loss-amount", "rel": "amend-brought-forward-loss", "method": "POST" }, { "href": "/individuals/losses/TC663795B/brought-forward-losses/AAZZ1234567890a", "rel": "delete-brought-forward-loss", "method": "DELETE" } ] }
Name | Description |
---|---|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
self-employment-class4
uk-property-fhl
uk-property-non-fhl
foreign-property-fhl-eea
foreign-property
|
lossAmount
number
required
|
Brought Forward Loss amount related to the type of loss specified. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
taxYearBroughtForwardFrom
string
required
|
The tax year to which the loss applies. The start year and end year must not span two tax years. The minimum tax year is 2018-19. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
lastModified
string
required
|
The timestamp when the entry was created or last modified.
Must conform to the regular expression
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
amend-brought-forward-loss
delete-brought-forward-loss
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
DELETE
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
The format of the supplied Loss ID is not valid. |
400 (Bad Request) |
FORMAT_LOSS_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
The type of claim is the same as a previous submission for this income source. |
403 (Forbidden) |
RULE_NO_CHANGE |
The remote endpoint has indicated that no data can be found for the given loss ID. |
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 success response where type of loss is Self-Employment. |
CLASS_4 |
Simulates the scenario where type of loss is Self-Employment Class 4. |
FOREIGN_PROPERTY |
Simulates the scenario where type of loss is Foreign Property. |
FOREIGN_PROPERTY_FHL_EEA |
Simulates the scenario where type of loss is Foreign Property FHL EEA. |
UK_PROPERTY_FHL |
Simulates the scenario where type of loss is UK Property FHL. |
UK_PROPERTY_NON_FHL |
Simulates the scenario where type of loss is UK Property Non-FHL. |
NOT_FOUND |
Simulates the scenario where no data is found. |
NO_CHANGE |
Simulates the scenario where the brought forward loss amount has not changed. |
Close Section
Loss Claims
Resources related to a customer’s financial data for their loss claims.
Loss Claims resources
/individuals/losses/{nino}/loss-claims
List Loss Claims
GET
This endpoint allows a developer to retrieve the existing loss claims information. A National Insurance Number must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Query parameters
Name | Description |
---|---|
taxYearClaimedFor
string
optional
|
The tax year to which the claim applies. The start year and end year must not span two tax years. The minimum tax year is 2019-20. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
businessId
string
optional
|
The unique identifier of the income source the claim relates to.
For example: |
typeOfLoss
string
optional
|
The type of business the loss applies to.
|
typeOfClaim
string
optional
|
The type of claim to be applied.
|
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Self-Employment Loss Claim
{ "claims": [ { "businessId": "XBIS12356589871", "typeOfLoss": "self-employment", "typeOfClaim": "carry-sideways", "taxYearClaimedFor": "2019-20", "claimId": "AAZZ0123456789a", "sequence": 1, "lastModified": "2020-07-13T12:13:48.763Z" } ], "links": [ { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "create-loss-claim", "method": "POST" }, { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "self", "method": "GET" } ] }
UK Property Loss Claim
{ "claims": [ { "businessId": "XPIS12356589871", "typeOfLoss": "uk-property-non-fhl", "typeOfClaim": "carry-sideways", "taxYearClaimedFor": "2019-20", "claimId": "AAZZ0123456789a", "sequence": 1, "lastModified": "2020-07-13T12:13:48.763Z" } ], "links": [ { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "create-loss-claim", "method": "POST" }, { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "self", "method": "GET" } ] }
Foreign Property Loss Claim
{ "claims": [ { "businessId": "XFIS12356589871", "typeOfLoss": "foreign-property", "typeOfClaim": "carry-sideways", "taxYearClaimedFor": "2019-20", "claimId": "AAZZ0123456789a", "sequence": 1, "lastModified": "2020-07-13T12:13:48.763Z" } ], "links": [ { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "create-loss-claim", "method": "POST" }, { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "self", "method": "GET" } ] }
Name | Description |
---|---|
claims
array
required
|
An array of loss claim objects. An empty array is not returned, if no loss claims exist for the supplied NINO, a MATCHING_RESOURCE_NOT_FOUND error is returned. |
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
uk-property-non-fhl
foreign-property
|
typeOfClaim
string
required
|
The type of claim to be applied. Permitted values for "self-employment": carry-forward, carry-sideways. Permitted values for "uk-property-non-fhl" and "foreign-property": carry-sideways, carry-sideways-fhl, carry-forward-to-carry-sideways. Limited to the following possible values: carry-forward
carry-sideways
carry-sideways-fhl
carry-forward-to-carry-sideways
|
taxYearClaimedFor
string
required
|
The tax year to which the claim applies. The start year and end year must not span two tax years. The minimum tax year is 2019-20. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
claimId
string
required
|
Unique identifier for the loss claim.
For example: |
sequence
number
optional
|
The order number in which this loss claim is to be used it must be an integer in the range 1 to 99. The sequence must start with 1 and have no gaps. |
lastModified
string
required
|
The timestamp when the entry was created or last modified.
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
href
string
required
|
The relative url of the endpoint
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be `self` where the action is retrieval of the same resource Limited to the following possible values: self
|
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: |
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
create-loss-claim
amend-loss-claim-order
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
POST
PUT
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
Tax year range invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
The format of the type of claim is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_CLAIM |
The format of the supplied type of loss field is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_LOSS |
The format of the supplied Business ID field is not valid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
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 successful self-employment response where typeOfClaim is "carry-forward". |
UK_PROPERTY |
Simulates successful uk-property-non-fhl response where typeOfClaim is "carry-sideways-fhl". |
FOREIGN_PROPERTY |
Simulates successful foreign property response where typeOfClaim is "carry-sideways". |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/loss-claims
Create a Loss Claim
POST
This endpoint allows a developer to create a Loss Claim against an income source for a specific tax year. Claims cannot be made until after the End of Period Statement. A National Insurance number must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
Scenario: Self-Employment Claim Request
{ "businessId": "XBIS12356589871", "typeOfLoss": "self-employment", "typeOfClaim": "carry-forward", "taxYearClaimedFor": "2019-20" }
Scenario: UK Property Claim Request
{ "businessId": "XPIS12356589871", "typeOfLoss": "uk-property-non-fhl", "typeOfClaim": "carry-sideways", "taxYearClaimedFor": "2019-20" }
Scenario: Foreign Property Claim Request
{ "businessId": "XFIS12356589871", "typeOfLoss": "foreign-property", "typeOfClaim": "carry-sideways", "taxYearClaimedFor": "2019-20" }
Name | Description |
---|---|
taxYearClaimedFor
string
required
|
The tax year to which the claim applies. The start year and end year must not span two tax years. The minimum tax year is 2019-20. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
uk-property-non-fhl
foreign-property
|
typeOfClaim
string
required
|
The type of claim to be applied. Permitted values for "self-employment": carry-forward, carry-sideways. Permitted values for "uk-property-non-fhl" and "foreign-property": carry-sideways, carry-sideways-fhl, carry-forward-to-carry-sideways. Limited to the following possible values: carry-forward
carry-sideways
carry-sideways-fhl
carry-forward-to-carry-sideways
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
Responses
HTTP status 201 (Created)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "claimId": "AAZZ1234567890A", "links": [ { "href": "/individuals/losses/TC663795B/loss-claims/AAZZ1234567890A", "rel": "self", "method": "GET" }, { "href": "/individuals/losses/TC663795B/loss-claims/AAZZ1234567890A/change-type-of-claim", "rel": "amend-loss-claim", "method": "POST" }, { "href": "/individuals/losses/TC663795B/loss-claims/AAZZ1234567890A", "rel": "delete-loss-claim", "method": "DELETE" } ] }
Name | Description |
---|---|
claimId
string
required
|
An identifier for the newly created loss claim.
Must conform to the regular expression
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
amend-loss-claim
delete-loss-claim
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
POST
DELETE
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied taxYearClaimedFor value is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
Tax year range invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
The format of the supplied type of loss field is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_LOSS |
The format of the type of claim is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_CLAIM |
The format of the supplied Business ID field is not valid. |
400 (Bad Request) |
FORMAT_BUSINESS_ID |
The type of claim supplied is not valid. |
400 (Bad Request) |
RULE_TYPE_OF_CLAIM_INVALID |
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
The type of claim is the same as a previous submission for this income source. |
403 (Forbidden) |
RULE_DUPLICATE_SUBMISSION |
The accounting period has not yet ended. |
403 (Forbidden) |
RULE_ACCOUNTING_PERIOD_NOT_ENDED |
There is no accounting period for the year of the claim. |
403 (Forbidden) |
RULE_NO_ACCOUNTING_PERIOD |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
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 |
Simulates success response. |
NOT_FOUND |
Simulates the scenario where no data is found. |
DUPLICATE |
Simulates the scenario where a duplicated value is found. |
ACCOUNTING_PERIOD_NOT_ENDED |
Simulates the scenario where the Loss claim has been made too soon. |
NO_ACCOUNTING_PERIOD |
Simulates the scenario where there is no accounting period for the year of the claim. |
Close Section
/individuals/losses/{nino}/loss-claims/{claimId}
Retrieve a Loss Claim
GET
This endpoint allows a developer to retrieve the detail of an existing loss claim. A National Insurance Number and Claim ID must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
claimId
string
required
|
Unique identifier for the loss claim. Must conform to the regular expression ^[A-Za-z0-9]{15}$
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Self-Employment Loss Claim
{ "taxYearClaimedFor": "2021-22", "typeOfLoss": "self-employment", "typeOfClaim": "carry-sideways", "businessId": "XBIS12356589871", "sequence": 1, "lastModified": "2022-07-13T12:13:48.763Z" }
UK Property Loss Claim
{ "taxYearClaimedFor": "2021-22", "typeOfLoss": "uk-property-non-fhl", "typeOfClaim": "carry-sideways", "businessId": "XPIS12356589871", "sequence": 1, "lastModified": "2022-07-13T12:13:48.763Z" }
Foreign Property Claim
{ "taxYearClaimedFor": "2021-22", "typeOfLoss": "foreign-property", "typeOfClaim": "carry-sideways", "businessId": "XFIS12356589871", "sequence": 1, "lastModified": "2022-07-13T12:13:48.763Z" }
Name | Description |
---|---|
taxYearClaimedFor
string
required
|
The tax year to which the claim applies. The start year and end year must not span two tax years. The minimum tax year is 2019-20. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment
uk-property-non-fhl
foreign-property
|
typeOfClaim
string
required
|
The type of claim to be applied. Permitted values for "self-employment": carry-forward, carry-sideways. Permitted values for "uk-property-non-fhl" and "foreign-property": carry-sideways, carry-sideways-fhl, carry-forward-to-carry-sideways. Limited to the following possible values: carry-forward
carry-sideways
carry-sideways-fhl
carry-forward-to-carry-sideways
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
sequence
number
optional
|
The order number in which this loss claim is to be used it must be an integer in the range 1 to 99. The sequence must start with 1 and have no gaps. |
lastModified
string
required
|
The timestamp when the entry was created or last modified.
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied Claim ID is not valid. |
400 (Bad Request) |
FORMAT_CLAIM_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
One or more loss claims not be found on this account. |
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 successful self-employment response where typeOfClaim is "carry-forward". |
UK_PROPERTY |
Simulates successful uk-property-non-fhl response where typeOfClaim is "carry-sideways-fhl". |
FOREIGN_PROPERTY |
Simulates successful foreign-property response where typeOfClaim is "carry-sideways". |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/loss-claims/{claimId}
Delete a Loss Claim
DELETE
This endpoint allows a developer to delete an existing Loss Claim. A National Insurance number and Claim ID must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
claimId
string
required
|
Unique identifier for the loss claim. Must conform to the regular expression ^[A-Za-z0-9]{15}$
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied Claim ID is not valid. |
400 (Bad Request) |
FORMAT_CLAIM_ID |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
One or more loss claims not be found on this account. |
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 success scenario |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/loss-claims/{claimId}/change-type-of-claim
Amend a Loss Claim Type
POST
This endpoint allows a developer to change the type of claim for an existing loss claim type. A National Insurance Number and Claim ID must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
claimId
string
required
|
Unique identifier for the loss claim. Must conform to the regular expression ^[A-Za-z0-9]{15}$
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "typeOfClaim": "carry-forward" }
Name | Description |
---|---|
typeOfClaim
string
required
|
The type of claim to be applied. Permitted values for "self-employment": carry-forward, carry-sideways. Permitted values for "uk-property-non-fhl" and "foreign-property": carry-sideways, carry-sideways-fhl, carry-forward-to-carry-sideways.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "typeOfLoss": "self-employment", "businessId": "X2IS12356589871", "typeOfClaim": "carry-forward", "taxYearClaimedFor": "2019-20", "sequence": 2, "lastModified": "2020-07-13T12:13:48.763Z" }
Name | Description |
---|---|
taxYearClaimedFor
string
required
|
The tax year to which the claim applies. The start year and end year must not span two tax years. The minimum tax year is 2019-20. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
typeOfLoss
string
required
|
The type of business the loss applies to. Limited to the following possible values: self-employment uk-property-non-fhl foreign-property Limited to the following possible values: self-employment
uk-property-non-fhl
foreign-property
|
typeOfClaim
string
required
|
The type of claim to be applied. Permitted values for "self-employment": carry-forward carry-sideways Permitted values for "uk-property-non-fhl" and "foreign-property": carry-sideways carry-sideways-fhl carry-forward-to-carry-sideways Limited to the following possible values: carry-forward
carry-sideways
carry-sideways-fhl
carry-forward-to-carry-sideways
|
businessId
string
required
|
An identifier for the business, unique to the customer.
Must conform to the regular expression
For example: |
sequence
number
optional
|
The order number in which this loss claim is to be used it must be an integer in the range 1 to 99. The sequence must start with 1 and have no gaps. |
lastModified
string
required
|
The timestamp when the entry was created or last modified.
For example: |
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint.
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied Claim ID is not valid. |
400 (Bad Request) |
FORMAT_CLAIM_ID |
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
The format of the type of claim is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_CLAIM |
The type of claim supplied is not valid. |
400 (Bad Request) |
RULE_TYPE_OF_CLAIM_INVALID |
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
The type of claim is the same as a previous submission for this income source. |
403 (Forbidden) |
RULE_NO_CHANGE |
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
One or more loss claims not be found on this account. |
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 success response. |
FP_FORWARD |
Simulates a Foreign Property carried forward scenario. |
FP_SIDEWAYS |
Simulates a Foreign Property carried sideways scenario. |
NONFHL_FORWARD |
Simulates a Non-FHL carried forward scenario. |
NONFHL_FORWARD_TO_SIDEWAYS |
Simulates a Non-FHL carried forward to sideways scenario. |
NONFHL_SIDEWAYS |
Simulates a Non-FHL carried sideways scenario. |
NONFHL_SIDEWAYS_FHL |
Simulates a FHL carried sideways scenario. |
SE_FORWARD |
Simulates a Self Employment carried forward scenario. |
SE_SIDEWAYS |
Simulates a Self Employment carried sideways scenario. |
NO_CHANGE |
Simulates the scenario where the relief type has not changed. |
TYPE_OF_CLAIM_INVALID |
Simulates the scenario where a claim type is invalid for the income source. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/losses/{nino}/loss-claims/order/{taxYearClaimedFor}
Amend Loss Claims Order
PUT
This endpoint allows the developer to change the sequence in which certain losses are used. A National Insurance Number must be provided.
Path parameters
Name | Description |
---|---|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
taxYearClaimedFor
string
required
|
The tax year to which the claim applies. The start year and end year must not span two tax years. The minimum tax year is 2019-20. No gaps are allowed, for example, 2022-24 is not valid.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.3.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "typeOfClaim": "carry-sideways", "listOfLossClaims": [ { "claimId": "1234567890ABCDE", "sequence": 2 }, { "claimId": "1234567890ABDE0", "sequence": 3 }, { "claimId": "1234567890ABEF1", "sequence": 1 } ] }
Name | Description |
---|---|
typeOfClaim
string
required
|
The type of loss claims whose order is to be amended. Limited to the following possible values: carry-sideways
|
listOfLossClaims
array
required
|
A list of the claims to be amended - all of the claims for a given type and tax year must be included in the submission. |
claimId
string
required
|
The unique identifier for the loss claim.
Must conform to the regular expression
For example: |
sequence
integer
required
|
The order number in which this loss claim is to be used. It must be an integer in the range 1 to 99. The sequence must start with 1 and have no gaps.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links": [ { "href": "/individuals/losses/TC663795B/loss-claims/order/2022-23", "rel": "self", "method": "PUT" }, { "href": "/individuals/losses/TC663795B/loss-claims", "rel": "list-loss-claims", "method": "GET" } ] }
Name | Description |
---|---|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource. |
href
string
required
|
The relative url of the endpoint
For example: |
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource. Limited to the following possible values: self
list-loss-claims
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
|
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
The format of the supplied Claim ID is not valid. |
400 (Bad Request) |
FORMAT_CLAIM_ID |
The format of the supplied claim type is not valid. |
400 (Bad Request) |
FORMAT_TYPE_OF_CLAIM |
The format of the supplied sequence number is not valid. |
400 (Bad Request) |
FORMAT_SEQUENCE |
The sequence does not begin with 1. |
400 (Bad Request) |
RULE_INVALID_SEQUENCE_START |
The sequence is not continuous. |
400 (Bad Request) |
RULE_SEQUENCE_ORDER_BROKEN |
Not all of the loss claims of this type for this tax year were included in the submission. |
400 (Bad Request) |
RULE_LOSS_CLAIMS_MISSING |
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
Tax year range invalid. A tax year 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 subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
One or more loss claims not be found on this account. |
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 success response. |
LOSS_CLAIMS_MISSING |
Simulates the scenario where one of more claims were not found. |
NOT_FOUND |
Simulates the scenario where not all claims of the given type and year were included. |
Close Section