GOV.UK
This version is in beta - expect some breaking changes.
Individuals Income Received (MTD) API
| Available in Sandbox | Yes |
|---|---|
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Available in Production | No |
Overview
This suite of endpoints allows software packages to create, amend, retrieve and delete data relating to:
- employments
- other employment income
- dividends income
- foreign income
- insurance policies income
- pensions income
- other income
- savings income
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 field 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 individuals-income-received-api GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the individuals-income-received-api 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
Employments
Resources relating to an individual's employments
Employments resources
/individuals/income-received/employments/{nino}/{taxYear}
This endpoint allows a developer to list the employments for this user. A National Insurance number and Tax year must be provided.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"employments":[
{
"employmentId":"1557ecb5-fd32-48cc-81f5-e6acd1099f1c",
"employerName":"Employer Name Ltd.",
"dateIgnored":"2020-06-17T10:53:38Z",
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/1557ecb5-fd32-48cc-81f5-e6acd1099f1c",
"rel":"self",
"method":"GET"
}
]
}
],
"customEmployments":[
{
"employmentId":"2557ecb5-fd32-48cc-81f5-e6acd1099f2c",
"employerName":"Employer Name Ltd.",
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/2557ecb5-fd32-48cc-81f5-e6acd1099f2c",
"rel":"self",
"method":"GET"
}
]
}
],
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"add-custom-employment",
"method":"POST"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"self",
"method":"GET"
}
]
}
| Name | Description |
|---|---|
|
employments
array
optional
|
Array containing details of employments provided to HMRC by employers. |
|
employmentId
string
required
|
The unique identifier for the employment.
Must conform to the regular expression
For example: |
|
employerName
string
required
|
The name of the employer the employee worked for.
Must conform to the regular expression
For example: |
|
dateIgnored
string
optional
|
The date the HMRC provided employment instance was set to be ignored. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
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
|
|
customEmployments
array
optional
|
Array containing details of employments provided by the user. |
|
employmentId
string
required
|
The unique identifier for the employment.
Must conform to the regular expression
For example: |
|
employerName
string
required
|
The name of the employer the employee worked for.
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: add-custom-employment
self
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: POST
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 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 |
|
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. |
This endpoint allows the developer to add an employment missing from the list of employments for this user. This endpoint can only be used after the tax year has ended. Employments that are added via this method are not rolled over into the next tax year. A National Insurance number, tax year, employer name and start date are required.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
{
"employerRef": "123/AB56797",
"employerName": "Employer Name Ltd.",
"startDate": "2019-01-01",
"cessationDate": "2020-06-01",
"payrollId": "124214112412"
}
| Name | Description |
|---|---|
|
employerRef
string
optional
|
A unique identifier, the employer reference number.
Must conform to the regular expression
For example: |
|
employerName
string
required
|
The name of the employer the employee worked for.
Must conform to the regular expression
For example: |
|
startDate
string
required
|
The date the employment began. It must be provided in the format YYYY-MM-DD
For example: |
|
cessationDate
string
optional
|
The date the employment ended. It must be provided in the format YYYY-MM-DD
For example: |
|
payrollId
string
optional
|
The unique identifier used by the employer to identify the employee.
Must conform to the regular expression
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"employmentId": "4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"list-employments",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"amend-custom-employment",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"delete-custom-employment",
"method":"DELETE"
}
]
}
| Name | Description |
|---|---|
|
employmentId
string
required
|
The unique identifier for the employment.
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: list-employments
self
amend-custom-employment
delete-custom-employment
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
PUT
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 |
|
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 employment is listed as starting after the tax year ended. |
400 (Bad Request) |
RULE_START_DATE_AFTER_TAX_YEAR_END |
|
The employment is listed as ending before the tax year began. |
400 (Bad Request) |
RULE_CESSATION_DATE_BEFORE_TAX_YEAR_START |
|
The cessation date is earlier than the start date. |
400 (Bad Request) |
RULE_END_DATE_BEFORE_START_DATE |
|
The submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
|
The format of the supplied employer ref is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYER_REF |
|
The format of the employer name is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYER_NAME |
|
The format of the supplied start date field is not valid. |
400 (Bad Request) |
FORMAT_START_DATE |
|
The format of the supplied cessation date is not valid. |
400 (Bad Request) |
FORMAT_CESSATION_DATE |
|
The format of the supplied payroll ID field is not valid. |
400 (Bad Request) |
FORMAT_PAYROLL_ID |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED |
|
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. |
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}
This endpoint allows the developer to retrieve details of an employment for this user. A National Insurance number, Tax year and Employment ID are required.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"employerRef": "123/AZ12334",
"employerName": "Employer Name Ltd.",
"startDate": "2020-06-17",
"cessationDate": "2020-06-17",
"payrollId": "123345657",
"dateIgnored": "2020-06-17T10:53:38Z",
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"list-employments",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/unignore",
"rel":"unignore-employment",
"method":"POST"
}
]
}
{
"employerRef": "123/AZ12334",
"employerName": "Employer Name Ltd.",
"startDate": "2020-06-17",
"cessationDate": "2020-06-17",
"payrollId": "123345657",
"submittedOn": "2021-04-06T09:37:17Z",
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"list-employments",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"amend-custom-employment",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"delete-custom-employment",
"method":"DELETE"
}
]
}
| Name | Description |
|---|---|
|
employerRef
string
optional
|
A unique identifier, the employer reference number.
Must conform to the regular expression
For example: |
|
employerName
string
required
|
The name of the employer the employee worked for.
Must conform to the regular expression
For example: |
|
startDate
string
required
|
The date the employment began. It must be provided in the format YYYY-MM-DD
For example: |
|
cessationDate
string
optional
|
The date the employment ended. It must be provided in the format YYYY-MM-DD
For example: |
|
payrollId
string
optional
|
The unique identifier used by the employer to identify the employee.
Must conform to the regular expression
For example: |
|
dateIgnored
string
optional
|
The date the HMRC provided employment instance was set to be ignored. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
submittedOn
string
optional
|
The date the custom employment was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
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: list-employments
self
amend-custom-employment
delete-custom-employment
ignore-employment
unignore-employment
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
PUT
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 |
|
The format of the supplied employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
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 |
|
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 with custom employment. |
HMRC_EMPLOYMENT |
Simulates success response with HMRC employment. |
HMRC_IGNORED |
Simulates success response with ignored HMRC employment. |
NOT_FOUND |
Simulates the scenario where no data is found. |
This endpoint allows the developer to provide or update a custom employment from the list of employments for this user. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID are required.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
{
"employerRef": "123/AZ12334",
"employerName": "Employer Name Ltd.",
"startDate": "2019-01-01",
"cessationDate": "2020-06-01",
"payrollId": "124214112412"
}
| Name | Description |
|---|---|
|
employerRef
string
optional
|
A unique identifier, the employer reference number.
Must conform to the regular expression
For example: |
|
employerName
string
required
|
The name of the employer the employee worked for.
Must conform to the regular expression
For example: |
|
startDate
string
required
|
The date the employment began. It must be provided in the format YYYY-MM-DD
For example: |
|
cessationDate
string
optional
|
The date the employment ended. It must be provided in the format YYYY-MM-DD
For example: |
|
payrollId
string
optional
|
The unique identifier used by the employer to identify the employee.
Must conform to the regular expression
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"list-employments",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"amend-custom-employment",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"delete-custom-employment",
"method":"DELETE"
}
]
}
| 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: list-employments
self
amend-custom-employment
delete-custom-employment
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
PUT
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 |
|
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 employment is listed as starting after the tax year ended. |
400 (Bad Request) |
RULE_START_DATE_AFTER_TAX_YEAR_END |
|
The employment is listed as ending before the tax year began. |
400 (Bad Request) |
RULE_CESSATION_DATE_BEFORE_TAX_YEAR_START |
|
The cessation date is earlier than the start date. |
400 (Bad Request) |
RULE_END_DATE_BEFORE_START_DATE |
|
The submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
|
The format of the supplied employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
The format of the supplied employer ref is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYER_REF |
|
The format of the employer name is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYER_NAME |
|
The format of the supplied start date field is not valid. |
400 (Bad Request) |
FORMAT_START_DATE |
|
The format of the supplied cessation date is not valid. |
400 (Bad Request) |
FORMAT_CESSATION_DATE |
|
The format of the supplied payroll ID field is not valid. |
400 (Bad Request) |
FORMAT_PAYROLL_ID |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED |
|
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. |
This endpoint allows the developer to delete a custom employment from the list of employments for this user. A National Insurance number, Tax year and Employment ID are required.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 204 (No Content)
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 employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
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 |
|
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. |
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/ignore
This endpoint allows the developer to ignore an HMRC provided employment from among the list of employments for this user. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID are required.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"list-employments",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"self",
"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: list-employments
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 tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
|
The format of the supplied employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
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 submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
|
The Employment ID provided is for a custom (user-provided) employment. |
403 (Forbidden) |
RULE_CUSTOM_EMPLOYMENT |
|
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. |
CUSTOM_EMPLOYMENT |
Simulates the scenario where a custom employment is submitted. |
NOT_FOUND |
Simulates the scenario where no data is found. |
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/unignore
This endpoint allows a developer to unignore the HMRC provided employment from a list of employments for this user. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links":[
{
"href":"/individuals/income-received/employments/TC663795B/2021-22",
"rel":"list-employments",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
"rel":"self",
"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: list-employments
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 tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
|
The format of the supplied employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
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 submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
|
The Employment ID provided is for a custom (user-provided) employment. |
403 (Forbidden) |
RULE_CUSTOM_EMPLOYMENT |
|
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. |
CUSTOM_EMPLOYMENT |
Simulates the scenario where a custom employment is submitted. |
NOT_FOUND |
Simulates the scenario where no data is found. |
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/financial-details
This endpoint allows a developer to retrieve employment information and associated financial data for a given tax year. A National Insurance number, Tax year and Employment ID must be provided.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Query parameters
| Name | Description |
|---|---|
|
source
string
optional
|
Specifies the source of data to be returned. If source is not provided, the latest submitted values will be returned. Limited to the following possible values:
|
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"submittedOn": "2020-01-04T05:01:01Z",
"customerAdded": "2020-04-04T01:01:01Z",
"employment": {
"employer": {
"employerRef": "223/AB12399",
"employerName": "Employer Name Ltd."
},
"pay": {
"taxablePayToDate": 34234.15,
"totalTaxToDate": 6782.92
},
"deductions": {
"studentLoans": {
"uglDeductionAmount": 13343.45,
"pglDeductionAmount": 24242.56
}
},
"benefitsInKind": {
"accommodation": 455.67,
"assets": 435.54,
"assetTransfer": 24.58,
"beneficialLoan": 33.89,
"car": 3434.78,
"carFuel": 34.56,
"educationalServices": 445.67,
"entertaining": 434.45,
"expenses": 3444.32,
"medicalInsurance": 4542.47,
"telephone": 243.43,
"service": 45.67,
"taxableExpenses": 24.56,
"van": 56.29,
"vanFuel": 14.56,
"mileage": 34.23,
"nonQualifyingRelocationExpenses": 54.62,
"nurseryPlaces": 84.29,
"otherItems": 67.67,
"paymentsOnEmployeesBehalf": 67.23,
"personalIncidentalExpenses": 74.29,
"qualifyingRelocationExpenses": 78.24,
"employerProvidedProfessionalSubscriptions": 84.56,
"employerProvidedServices": 56.34,
"incomeTaxPaidByDirector": 67.34,
"travelAndSubsistence": 56.89,
"vouchersAndCreditCards": 34.90,
"nonCash": 23.89
}
},
"links": [
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"create-and-amend-employment-financial-details",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"delete-employment-financial-details",
"method":"DELETE"
}
]
}
{
"submittedOn": "2020-01-04T05:01:01Z",
"dateIgnored": "2020-03-05T05:01:01Z",
"employment": {
"employmentSequenceNumber": "1002",
"payrollId": "123456789999",
"companyDirector": false,
"closeCompany": true,
"directorshipCeasedDate": "2020-02-12",
"startDate": "2019-04-21",
"cessationDate": "2020-03-11",
"occupationalPension": false,
"disguisedRemuneration": false,
"employer": {
"employerRef": "223/AB12399",
"employerName": "Employer Name Ltd."
},
"pay": {
"taxablePayToDate": 34234.15,
"totalTaxToDate": 6782.92,
"payFrequency": "CALENDAR MONTHLY",
"paymentDate": "2020-04-23",
"taxWeekNo": 32,
"taxMonthNo": 8
},
"customerEstimatedPay": {
"amount": 1500.99
},
"deductions": {
"studentLoans": {
"uglDeductionAmount": 13343.45,
"pglDeductionAmount": 24242.56
}
},
"benefitsInKind": {
"accommodation": 455.67,
"assets": 435.54,
"assetTransfer": 24.58,
"beneficialLoan": 33.89,
"car": 3434.78,
"carFuel": 34.56,
"educationalServices": 445.67,
"entertaining": 434.45,
"expenses": 3444.32,
"medicalInsurance": 4542.47,
"telephone": 243.43,
"service": 45.67,
"taxableExpenses": 24.56,
"van": 56.29,
"vanFuel": 14.56,
"mileage": 34.23,
"nonQualifyingRelocationExpenses": 54.62,
"nurseryPlaces": 84.29,
"otherItems": 67.67,
"paymentsOnEmployeesBehalf": 67.23,
"personalIncidentalExpenses": 74.29,
"qualifyingRelocationExpenses": 78.24,
"employerProvidedProfessionalSubscriptions": 84.56,
"employerProvidedServices": 56.34,
"incomeTaxPaidByDirector": 67.34,
"travelAndSubsistence": 56.89,
"vouchersAndCreditCards": 34.90,
"nonCash": 23.89
}
},
"links": [
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"create-and-amend-employment-financial-details",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"delete-employment-financial-details",
"method":"DELETE"
}
]
}
| Name | Description |
|---|---|
|
submittedOn
string
required
|
The date the Employment data was added. Must conform to the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
source
string
optional
|
Specifies the source of data to be returned. If source is not provided, the latest submitted values will be returned. Limited to the following possible values: hmrcHeld
user
latest
|
|
customerAdded
string
optional
|
The date the employment data was added by the customer. Must conform to the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
dateIgnored
string
optional
|
The date the employment was ignored. Must conform to the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
employment
object
required
|
Object containing the financial data relating to a single employment. |
|
employmentSequenceNumber
string
optional
|
A number that identifies the position of the employment in a sequence of employments for a given tax year.
Must conform to the regular expression
For example: |
|
payrollId
string
optional
|
A unique identifier used by the employer to identify the employee.
Must conform to the regular expression
For example: |
|
companyDirector
boolean
optional
|
Identifies the employee as a director when set to True.
For example: |
|
closeCompany
boolean
optional
|
Identifies if the employer is a close company.
For example: |
|
directorshipCeasedDate
string
optional
|
The date the directorship ended. Must conform to the format YYYY-MM-DD
For example: |
|
startDate
string
optional
|
The date the employment began. Must conform to the format YYYY-MM-DD
For example: |
|
cessationDate
string
optional
|
The date the employment ended. Must conform to the format YYYY-MM-DD
For example: |
|
occupationalPension
boolean
optional
|
Indicates that the employee pays into an occupational pension when set to True.
For example: |
|
disguisedRemuneration
boolean
optional
|
Indicates that the employee is declaring disguised remuneration when set to True.
For example: |
|
employer
object
required
|
Object containing pay details for a single employment. |
|
employerRef
string
optional
|
A unique identifier, the employer reference number.
Must conform to the regular expression
For example: |
|
employerName
string
required
|
The name of the employer the employee worked for.
Must conform to the regular expression
For example: |
|
pay
object
optional
|
Object containing pay details for a single employment. |
|
taxablePayToDate
number
required
|
The gross pay for this employment. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalTaxToDate
number
required
|
The amount of tax deducted for this employment. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
|
payFrequency
string
optional
|
The payment frequency Limited to the following possible values: WEEKLY
FORTNIGHTLY
FOUR WEEKLY
CALENDAR MONTHLY
QUARTERLY
BI-ANNUALLY
ONE-OFF
IRREGULAR
ANNUALLY
|
|
paymentDate
string
optional
|
The date of the latest payment. Must conform to the format YYYY-MM-DD
For example: |
|
taxWeekNo
number
optional
|
The week count of the tax year. The value must be an integer between 1 and 56
For example: |
|
taxMonthNo
number
optional
|
The month count of the tax year. The value must be an integer between 1 and 12
For example: |
|
customerEstimatedPay
object
optional
|
Object containing estimated pay details for a single employment. |
|
amount
number
optional
|
The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
deductions
object
optional
|
Object containing details of deductions for a single employment. |
|
studentLoans
object
optional
|
Object containing details of deductions against student loans. |
|
uglDeductionAmount
number
optional
|
The amount deducted for an undergraduate student loan. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
pglDeductionAmount
number
optional
|
The amount deducted for a postgraduate student loan. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
benefitsInKind
object
optional
|
Object containing amount values of benefits received from a single employment. |
|
accommodation
number
optional
|
The value of accommodation costs provided by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
assets
number
optional
|
The value of any goods provided by the employer not exclusively used for work. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
assetsTransfer
number
optional
|
The value of any company assets signed over by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
beneficialLoan
number
optional
|
The amount of interest free or low interest loans given by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
car
number
optional
|
The cash equivalent of any cars made available by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
carFuel
number
optional
|
The amount paid for fuel when using company cars. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
educationalServices
number
optional
|
Scholarships or school fees paid by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
entertaining
number
optional
|
Entertainment costs paid by the employer either directly or reimbursed to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
expenses
number
optional
|
Expenses reimbursed by the employer to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
medicalInsurance
number
optional
|
The sum of insurance premiums paid by the employer for medical or dental insurance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
telephone
number
optional
|
Telephone costs paid by the employer that are not exempt. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
service
number
optional
|
Services used by an employee and paid for by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxableExpenses
number
optional
|
Taxable expenses reimbursed by the employer to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
van
number
optional
|
The cash equivalent of any vans made available by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
vanFuel
number
optional
|
The amount paid by the employer for fuel costs when using company vans. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
mileage
number
optional
|
The mileage amount paid over HMRC's approved rate by the employer for use of employee's own car for work. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nonQualifyingRelocationExpenses
number
optional
|
Other costs involved in relocation paid for directly by the employer or reimbursed to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nurseryPlaces
number
optional
|
Childcare costs paid by the employer or voucher or commercial childcare costs above the exempt limit. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
otherItems
number
optional
|
The value of any other benefits. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
paymentsOnEmployeesBehalf
number
optional
|
Other costs incurred by the employee paid for by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
personalIncidentalExpenses
number
optional
|
Incidental (non-business) expenses incurred by an employee while travelling on business. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
qualifyingRelocationExpenses
number
optional
|
Employer paid costs associated with employee relocation including bridging loans. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
employerProvidedProfessionalSubscriptions
number
optional
|
Professional fees and subscriptions paid for by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
employerProvidedServices
number
optional
|
The value of services provided by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
incomeTaxPaidByDirector
number
optional
|
Non PAYE Income Tax for directors deducted from the employer by HMRC. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
travelAndSubsistence
number
optional
|
The cost of any travel and subsistence (accommodation, meals and so on) paid for by the employer, that is not exempt. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
vouchersAndCreditCards
number
optional
|
The value of vouchers given by the employer and the expenditure of any employer provided credit cards. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nonCash
number
optional
|
The value of any other non-cash benefits paid to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
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
create-and-amend-employment-financial-details
delete-employment-financial-details
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
PUT
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 |
|
The format of the supplied employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
The format of the supplied source is not valid. |
400 (Bad Request) |
FORMAT_SOURCE |
|
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. The tax year must not exceed current tax year minus 4. |
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 |
|
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 |
Requesting user source simulates success response with User provided financial details. |
N/A - DEFAULT |
Requesting hmrcHeld source simulates success response with HMRC held financial details. |
N/A - DEFAULT |
Requesting latest source simulates success response with Latest financial details submitted. |
NOT_FOUND |
Simulates the scenario where no data is found. |
This endpoint allows a developer to submit or overwrite financial data for an individual employment. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID are required.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
{
"employment": {
"pay": {
"taxablePayToDate": 1024.99,
"totalTaxToDate": 1024.99
},
"deductions": {
"studentLoans": {
"uglDeductionAmount": 1024.99,
"pglDeductionAmount": 1024.99
}
},
"benefitsInKind": {
"accommodation": 1024.99,
"assets": 1024.99,
"assetTransfer": 1024.99,
"beneficialLoan": 1024.99,
"car": 1024.99,
"carFuel": 1024.99,
"educationalServices": 1024.99,
"entertaining": 1024.99,
"expenses": 1024.99,
"medicalInsurance": 1024.99,
"telephone": 1024.99,
"service": 1024.99,
"taxableExpenses": 1024.99,
"van": 1024.99,
"vanFuel": 1024.99,
"mileage": 1024.99,
"nonQualifyingRelocationExpenses": 1024.99,
"nurseryPlaces": 1024.99,
"otherItems": 1024.99,
"paymentsOnEmployeesBehalf": 1024.99,
"personalIncidentalExpenses": 1024.99,
"qualifyingRelocationExpenses": 1024.99,
"employerProvidedProfessionalSubscriptions": 1024.99,
"employerProvidedServices": 1024.99,
"incomeTaxPaidByDirector": 1024.99,
"travelAndSubsistence": 1024.99,
"vouchersAndCreditCards": 1024.99,
"nonCash": 1024.99
}
}
}
| Name | Description |
|---|---|
|
employment
object
required
|
Object containing the financial data relating to a single employment. |
|
pay
object
required
|
Object containing pay details for a single employment. |
|
taxablePayToDate
number
required
|
The gross pay for this employment. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalTaxToDate
number
required
|
The amount of tax deducted for this employment. The value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
|
deductions
object
optional
|
Object containing details of deductions for a single employment. |
|
studentLoans
object
optional
|
Object containing details of deductions against student loans. |
|
uglDeductionAmount
number
optional
|
The amount deducted for an undergraduate student loan. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
pglDeductionAmount
number
optional
|
The amount deducted for a postgraduate student loan. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
benefitsInKind
object
optional
|
Object containing amount values of benefits received from a single employment. |
|
accommodation
number
optional
|
The value of accommodation costs provided by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
assets
number
optional
|
The value of any goods provided by the employer not exclusively used for work. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
assetsTransfer
number
optional
|
The value of any company assets signed over by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
beneficialLoan
number
optional
|
The amount of interest free or low interest loans given by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
car
number
optional
|
The cash equivalent of any cars made available by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
carFuel
number
optional
|
The amount paid for fuel when using company cars. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
educationalServices
number
optional
|
Scholarships or school fees paid by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
entertaining
number
optional
|
Entertainment costs paid by the employer either directly or reimbursed to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
expenses
number
optional
|
Expenses reimbursed by the employer to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
medicalInsurance
number
optional
|
The sum of insurance premiums paid by the employer for medical or dental insurance. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
telephone
number
optional
|
Telephone costs paid by the employer that are not exempt. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
service
number
optional
|
Services used by an employee and paid for by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxableExpenses
number
optional
|
Taxable expenses reimbursed by the employer to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
van
number
optional
|
The cash equivalent of any vans made available by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
vanFuel
number
optional
|
The amount paid by the employer for fuel costs when using company vans. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
mileage
number
optional
|
The mileage amount paid over HMRC's approved rate by the employer for use of employee's own car for work. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nonQualifyingRelocationExpenses
number
optional
|
Other costs involved in relocation paid for directly by the employer or reimbursed to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nurseryPlaces
number
optional
|
Childcare costs paid by the employer or voucher or commercial childcare costs above the exempt limit. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
otherItems
number
optional
|
The value of any other benefits. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
paymentsOnEmployeesBehalf
number
optional
|
Other costs incurred by the employee paid for by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
personalIncidentalExpenses
number
optional
|
Incidental (non-business) expenses incurred by an employee while travelling on business. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
qualifyingRelocationExpenses
number
optional
|
Employer paid costs associated with employee relocation including bridging loans. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
employerProvidedProfessionalSubscriptions
number
optional
|
Professional fees and subscriptions paid for by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
employerProvidedServices
number
optional
|
The value of services provided by the employer. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
incomeTaxPaidByDirector
number
optional
|
Non PAYE Income Tax for directors deducted from the employer by HMRC. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
travelAndSubsistence
number
optional
|
The cost of any travel and subsistence (accommodation, meals and so on) paid for by the employer, that is not exempt. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
vouchersAndCreditCards
number
optional
|
The value of vouchers given by the employer and the expenditure of any employer provided credit cards. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nonCash
number
optional
|
The value of any other non-cash benefits paid to the employee. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links": [
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"create-and-amend-employment-financial-details",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
"rel":"delete-employment-financial-details",
"method":"DELETE"
}
]
}
| 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
create-and-amend-employment-financial-details
delete-employment-financial-details
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: GET
PUT
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 |
|
The format of the supplied employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
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 submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
|
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED |
|
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
|
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. |
This endpoint allows a developer to delete the previously entered financial data from the list of employments for this user. A National Insurance number, Tax year and Employment ID must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
|
employmentId
string
required
|
The unique identifier for the employment. Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 204 (No Content)
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 employment ID field is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYMENT_ID |
|
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 |
|
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. |
Other Employment Income
Resources relating to an individual's other employment income
Other Employment Income resources
/individuals/income-received/employments/other/{nino}/{taxYear}
This endpoint allows the developer to retrieve other employment income: share options, shares awarded or received, disability, lump sums and foreign service income. A National Insurance number and tax year must be provided.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"submittedOn": "2021-04-06T09:37:17Z",
"shareOption":[
{
"employerName":"Company Ltd",
"employerRef":"123/AB456",
"schemePlanType":"EMI",
"dateOfOptionGrant":"2019-11-20",
"dateOfEvent":"2019-11-20",
"optionNotExercisedButConsiderationReceived":true,
"amountOfConsiderationReceived":23122.22,
"noOfSharesAcquired":1,
"classOfSharesAcquired":"FIRST",
"exercisePrice":12.22,
"amountPaidForOption":123.22,
"marketValueOfSharesOnExcise":1232.22,
"profitOnOptionExercised":1232.33,
"employersNicPaid":2312.22,
"taxableAmount":2132.22
}
],
"sharesAwardedOrReceived":[
{
"employerName":"Company Ltd",
"employerRef":"123/AB456",
"schemePlanType":"SIP",
"dateSharesCeasedToBeSubjectToPlan":"2019-11-10",
"noOfShareSecuritiesAwarded":11,
"classOfShareAwarded":"FIRST",
"dateSharesAwarded":"2019-11-20",
"sharesSubjectToRestrictions":true,
"electionEnteredIgnoreRestrictions":false,
"actualMarketValueOfSharesOnAward":2123.22,
"unrestrictedMarketValueOfSharesOnAward":123.22,
"amountPaidForSharesOnAward":123.22,
"marketValueAfterRestrictionsLifted":1232.22,
"taxableAmount":12321.22
}
],
"disability":{
"customerReference":"EMP123A",
"amountDeducted":1223.22
},
"foreignService":{
"customerReference":"EMP123A",
"amountDeducted":1223.22
},
"lumpSums": [
{
"employerName":"Company Ltd",
"employerRef":"123/AB456",
"taxableLumpSumsAndCertainIncome": {
"amount": 5000.99,
"taxPaid": 5000.99,
"taxTakenOffInEmployment": false
},
"benefitFromEmployerFinancedRetirementScheme": {
"amount": 5000.99,
"exemptAmount": 5000.99,
"taxPaid": 500.99,
"taxTakenOffInEmployment": false
},
"redundancyCompensationPaymentsOverExemption": {
"amount": 4000.99,
"taxPaid": 400.99,
"taxTakenOffInEmployment": false
},
"redundancyCompensationPaymentsUnderExemption": {
"amount": 5000.99
}
}
],
"links":[
{
"href":"/individuals/income-received/employments/other/TC663795B/2021-22",
"rel":"create-and-amend-other-employment-income",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/other/TC663795B/2021-22",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/other/TC663795B/2021-22",
"rel":"delete-other-employment-income",
"method":"DELETE"
}
]
}
| Name | Description |
|---|---|
|
submittedOn
string
required
|
The date the other employment income was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
shareOption
array
optional
|
Financial details about share options income. |
|
employerName
string
required
|
The name of the employer. The length must be between 1 and 105 characters.
For example: |
|
employerRef
string
optional
|
A reference number given to every business that registers with HMRC as an employer.
Must conform to the regular expression
For example: |
|
schemePlanType
string
required
|
The type of share scheme or plan the employer has: Equated Monthly Instalment (EMI), Company Share Option Plan (CSOP) or Save As You Earn (SAYE). Limited to the following possible values: EMI
CSOP
SAYE
Other
|
|
dateOfOptionGrant
string
required
|
The date the option was granted in the format YYYY-MM-DD.
For example: |
|
dateOfEvent
string
required
|
The date the event occurred in the format YYYY-MM-DD.
For example: |
|
optionNotExercisedButConsiderationReceived
boolean
required
|
Boolean option not exercised but consideration received for lapse, release or assignment of the option.
For example: |
|
amountOfConsiderationReceived
number
required
|
The amount of consideration received. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
noOfSharesAcquired
number
required
|
The number of shares acquired. The value must be 0 or more.
For example: |
|
classOfSharesAcquired
string
required
|
The class type of shares acquired.
Must conform to the regular expression
For example: |
|
exercisePrice
number
required
|
The price per share at which the owner of a traded option is entitled to buy or sell. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
amountPaidForOption
number
required
|
The amount that an investor paid for an option contract. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
marketValueOfSharesOnExcise
number
required
|
The price that a stock can be readily bought or sold in the current market place. The 'going price' of a share of stock. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
profitOnOptionExercised
number
required
|
The sum that an investor earns by buying a call option or selling a put option at maturity. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
employersNicPaid
number
required
|
The amount of National Insurance contributions the employers paid on an option. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxableAmount
number
required
|
The taxable amount not subject to PAYE. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
sharesAwardedOrReceived
array
optional
|
Financial details about shares awarded or received income |
|
employerName
string
required
|
The name of the employer. The length must be between 1 and 105 characters.
For example: |
|
employerRef
string
optional
|
A reference number given to every business that registers with HMRC as an employer.
Must conform to the regular expression
For example: |
|
schemePlanType
string
required
|
The type of share scheme or plan the employer has. Limited to the following possible values: SIP
Other
|
|
dateSharesCeasedToBeSubjectToPlan
string
required
|
The date the shares ceased in the format YYYY-MM-DD.
For example: |
|
noOfShareSecuritiesAwarded
number
required
|
The number of shares awarded. The value must be 0 or more.
For example: |
|
classOfShareAwarded
string
required
|
The level of voting rights shareholders receive.
Must conform to the regular expression
For example: |
|
dateSharesAwarded
string
required
|
The date the shares ceased in the format YYYY-MM-DD.
For example: |
|
sharesSubjectToRestrictions
boolean
required
|
The shares of a company are not fully transferable from the issuing company to the person receiving them until certain conditions have been met.
For example: |
|
electionEnteredIgnoreRestrictions
boolean
required
|
A boolean indicating that the election has been made to ignore one or more restrictions, but leaving one or more restrictions to be taken into account.
For example: |
|
actualMarketValueOfSharesOnAward
number
required
|
The market value of the shares awarded. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
unrestrictedMarketValueOfSharesOnAward
number
required
|
The unrestricted market value of the shares awarded. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
amountPaidForSharesOnAward
number
required
|
The amount paid for the shares awarded. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
marketValueAfterRestrictionsLifted
number
required
|
The market value of the shares after restrictions lifted. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxableAmount
number
required
|
The taxable amount not subject to PAYE. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
disability
object
optional
|
An object that holds the key value for disability deductions. |
|
customerReference
string
optional
|
An optional user supplied reference.
Must conform to the regular expression
For example: |
|
amountDeducted
number
required
|
The claim for an exemption for specific payments received for physical or mental impairment, when the employment ended or terms changed. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
foreignService
object
optional
|
An object that holds the key value for foreign service deductions. |
|
customerReference
string
optional
|
A reference the user supplies to identify the foreign income.
Must conform to the regular expression
For example: |
|
amountDeducted
number
required
|
The claim for an exemption for specific payments received for physical or mental impairment, when the employment ended or terms changed. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
lumpSums
array
optional
|
An array that holds details of lump sum income |
|
employerName
string
required
|
The name of the employer. The length must be between 1 and 105 characters.
For example: |
|
employerRef
string
required
|
A reference number given to every business that registers with HMRC as an employer.
Must conform to the regular expression
For example: |
|
taxableLumpSumsAndCertainIncome
object
optional
|
An object that holds the key value for taxable lump sums and certain income |
|
amount
number
required
|
The amount of the taxable lump sum. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
number
optional
|
The amount of tax paid on the lump sum. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOffInEmployment
boolean
required
|
A boolean indicating whether tax has been taken off in employment.
For example: |
|
benefitFromEmployerFinancedRetirementScheme
object
optional
|
An object that holds the key value for benefits from employer financed retirement scheme |
|
amount
number
required
|
The amount of the benefit received. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
exemptAmount
number
optional
|
The amount of benefit exempt from tax. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
number
optional
|
The amount of tax paid on the benefit. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOffInEmployment
boolean
required
|
A boolean indicating whether tax has been taken off in employment.
For example: |
|
redundancyCompensationPaymentsOverExemption
object
optional
|
An object that holds the key value for redundancy compensation payments over exemption |
|
amount
number
required
|
The amount of the redundancy compensation payment over exemption. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
number
optional
|
The amount of tax paid on the redundancy compensation payments. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOffInEmployment
boolean
required
|
A boolean indicating whether tax has been taken off in employment.
For example: |
|
redundancyCompensationPaymentsUnderExemption
object
optional
|
An object that holds the key value for redundancy compensation payments under exemption |
|
amount
number
required
|
The amount of the redundancy compensation payments under exemption. The value must be between 0 and 99999999999.99 up to 2 decimal places.
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
create-and-amend-other-employment-income
delete-other-employment-income
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
DELETE
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO 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 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. |
This endpoint allows a developer to create and amend other employment income: share options, shares awarded or received, disability, lump sums and foreign service income. A National Insurance number and tax year must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
{
"shareOption":[
{
"employerName":"Company Ltd",
"employerRef":"123/AB456",
"schemePlanType":"EMI",
"dateOfOptionGrant":"2019-11-20",
"dateOfEvent":"2019-11-20",
"optionNotExercisedButConsiderationReceived":true,
"amountOfConsiderationReceived":23122.22,
"noOfSharesAcquired":1,
"classOfSharesAcquired":"FIRST",
"exercisePrice":12.22,
"amountPaidForOption":123.22,
"marketValueOfSharesOnExcise":1232.22,
"profitOnOptionExercised":1232.33,
"employersNicPaid":2312.22,
"taxableAmount":2132.22
}
],
"sharesAwardedOrReceived":[
{
"employerName":"Company Ltd",
"employerRef":"123/AB456",
"schemePlanType":"SIP",
"dateSharesCeasedToBeSubjectToPlan":"2019-11-10",
"noOfShareSecuritiesAwarded":11,
"classOfShareAwarded":"FIRST",
"dateSharesAwarded":"2019-11-20",
"sharesSubjectToRestrictions":true,
"electionEnteredIgnoreRestrictions":false,
"actualMarketValueOfSharesOnAward":2123.22,
"unrestrictedMarketValueOfSharesOnAward":123.22,
"amountPaidForSharesOnAward":123.22,
"marketValueAfterRestrictionsLifted":1232.22,
"taxableAmount":12321.22
}
],
"disability":{
"customerReference":"EMP123A",
"amountDeducted":1223.22
},
"foreignService":{
"customerReference":"EMP123A",
"amountDeducted":1223.22
},
"lumpSums": [
{
"employerName":"Company Ltd",
"employerRef":"123/AB456",
"taxableLumpSumsAndCertainIncome": {
"amount": 5000.99,
"taxPaid": 5000.99,
"taxTakenOffInEmployment": false
},
"benefitFromEmployerFinancedRetirementScheme": {
"amount": 5000.99,
"exemptAmount": 5000.99,
"taxPaid": 500.99,
"taxTakenOffInEmployment": false
},
"redundancyCompensationPaymentsOverExemption": {
"amount": 4000.99,
"taxPaid": 400.99,
"taxTakenOffInEmployment": false
},
"redundancyCompensationPaymentsUnderExemption": {
"amount": 5000.99
}
}
]
}
| Name | Description |
|---|---|
|
shareOption
array
optional
|
Financial details about share options income. |
|
employerName
string
required
|
The name of the employer. The length must be between 1 and 105 characters.
For example: |
|
employerRef
string
optional
|
A reference number given to every business that registers with HMRC as an employer.
Must conform to the regular expression
For example: |
|
schemePlanType
string
required
|
The type of share scheme or plan the employer has: Equated Monthly Instalment (EMI), Company Share Option Plan (CSOP) or Save As You Earn (SAYE). Limited to the following possible values: EMI
CSOP
SAYE
Other
|
|
dateOfOptionGrant
string
required
|
The date the option was granted in the format YYYY-MM-DD.
For example: |
|
dateOfEvent
string
required
|
The date the event occurred in the format YYYY-MM-DD.
For example: |
|
optionNotExercisedButConsiderationReceived
boolean
required
|
Boolean option not exercised but consideration received for lapse, release or assignment of the option.
For example: |
|
amountOfConsiderationReceived
number
required
|
The amount of consideration received. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
noOfSharesAcquired
number
required
|
The number of shares acquired. The value must be 0 or more.
For example: |
|
classOfSharesAcquired
string
required
|
The class type of shares acquired.
Must conform to the regular expression
For example: |
|
exercisePrice
number
required
|
The price per share at which the owner of a traded option is entitled to buy or sell. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
amountPaidForOption
number
required
|
The amount that an investor paid for an option contract. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
marketValueOfSharesOnExcise
number
required
|
The price that a stock can be readily bought or sold in the current market place. The 'going price' of a share of stock. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
profitOnOptionExercised
number
required
|
The sum that an investor earns by buying a call option or selling a put option at maturity. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
employersNicPaid
number
required
|
The amount of National Insurance contributions the employers paid on an option. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxableAmount
number
required
|
The taxable amount not subject to PAYE. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
sharesAwardedOrReceived
array
optional
|
Financial details about shares awarded or received income |
|
employerName
string
required
|
The name of the employer. The length must be between 1 and 105 characters.
For example: |
|
employerRef
string
optional
|
A reference number given to every business that registers with HMRC as an employer.
Must conform to the regular expression
For example: |
|
schemePlanType
string
required
|
The type of share scheme or plan the employer has. Limited to the following possible values: SIP
Other
|
|
dateSharesCeasedToBeSubjectToPlan
string
required
|
The date the shares ceased in the format YYYY-MM-DD.
For example: |
|
noOfShareSecuritiesAwarded
number
required
|
The number of shares awarded. The value must be 0 or more.
For example: |
|
classOfShareAwarded
string
required
|
The level of voting rights shareholders receive.
Must conform to the regular expression
For example: |
|
dateSharesAwarded
string
required
|
The date the shares ceased in the format YYYY-MM-DD.
For example: |
|
sharesSubjectToRestrictions
boolean
required
|
The shares of a company are not fully transferable from the issuing company to the person receiving them until certain conditions have been met.
For example: |
|
electionEnteredIgnoreRestrictions
boolean
required
|
A boolean indicating that the election has been made to ignore one or more restrictions, but leaving one or more restrictions to be taken into account.
For example: |
|
actualMarketValueOfSharesOnAward
number
required
|
The market value of the shares awarded. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
unrestrictedMarketValueOfSharesOnAward
number
required
|
The unrestricted market value of the shares awarded. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
amountPaidForSharesOnAward
number
required
|
The amount paid for the shares awarded. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
marketValueAfterRestrictionsLifted
number
required
|
The market value of the shares after restrictions lifted. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxableAmount
number
required
|
The taxable amount not subject to PAYE. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
disability
object
optional
|
An object that holds the key value for disability deductions. |
|
customerReference
string
optional
|
An optional user supplied reference.
Must conform to the regular expression
For example: |
|
amountDeducted
number
required
|
The claim for an exemption for specific payments received for physical or mental impairment, when the employment ended or terms changed. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
foreignService
object
optional
|
An object that holds the key value for foreign service deductions. |
|
customerReference
string
optional
|
A reference the user supplies to identify the foreign income.
Must conform to the regular expression
For example: |
|
amountDeducted
number
required
|
The claim for an exemption for specific payments received for physical or mental impairment, when the employment ended or terms changed. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
lumpSums
array
optional
|
An array that holds details of lump sum income |
|
employerName
string
required
|
The name of the employer. The length must be between 1 and 105 characters.
For example: |
|
employerRef
string
required
|
A reference number given to every business that registers with HMRC as an employer.
Must conform to the regular expression
For example: |
|
taxableLumpSumsAndCertainIncome
object
optional
|
An object that holds the key value for taxable lump sums and certain income |
|
amount
number
required
|
The amount of the taxable lump sum. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
number
optional
|
The amount of tax paid on the lump sum. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOffInEmployment
boolean
required
|
A boolean indicating whether tax has been taken off in employment.
For example: |
|
benefitFromEmployerFinancedRetirementScheme
object
optional
|
An object that holds the key value for benefits from employer financed retirement scheme |
|
amount
number
required
|
The amount of the benefit received. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
exemptAmount
number
optional
|
The amount of benefit exempt from tax. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
number
optional
|
The amount of tax paid on the benefit. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOffInEmployment
boolean
required
|
A boolean indicating whether tax has been taken off in employment.
For example: |
|
redundancyCompensationPaymentsOverExemption
object
optional
|
An object that holds the key value for redundancy compensation payments over exemption |
|
amount
number
required
|
The amount of the redundancy compensation payment over exemption. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
number
optional
|
The amount of tax paid on the redundancy compensation payments. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOffInEmployment
boolean
required
|
A boolean indicating whether tax has been taken off in employment.
For example: |
|
redundancyCompensationPaymentsUnderExemption
object
optional
|
An object that holds the key value for redundancy compensation payments under exemption |
|
amount
number
required
|
The amount of the redundancy compensation payments under exemption. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links":[
{
"href":"/individuals/income-received/employments/other/TC663795B/2021-22",
"rel":"create-and-amend-other-employment-income",
"method":"PUT"
},
{
"href":"/individuals/income-received/employments/other/TC663795B/2021-22",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/employments/other/TC663795B/2021-22",
"rel":"delete-other-employment-income",
"method":"DELETE"
}
]
}
| 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
create-and-amend-other-employment-income
delete-other-employment-income
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
DELETE
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO 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 |
|
Where lumpSums have been provided at least one child object is required. |
400 (Bad Request) |
RULE_LUMP_SUMS |
|
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
|
The format of the supplied customer reference is not valid. |
400 (Bad Request) |
FORMAT_CUSTOMER_REF |
|
The format of the employer name is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYER_NAME |
|
The format of the supplied employer ref is not valid. |
400 (Bad Request) |
FORMAT_EMPLOYER_REF |
|
The supplied date format is not valid. |
400 (Bad Request) |
FORMAT_DATE |
|
The format of class of shares awarded is not valid. |
400 (Bad Request) |
FORMAT_CLASS_OF_SHARES_AWARDED |
|
The format of class of shares acquired is not valid. |
400 (Bad Request) |
FORMAT_CLASS_OF_SHARES_ACQUIRED |
|
The format or value of scheme plan type is not valid. |
400 (Bad Request) |
FORMAT_SCHEME_PLAN_TYPE |
|
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 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 |
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. |
This endpoint allows the developer to delete other employment income: share options, shares awarded or received, disability, lump sums and foreign service income. A National Insurance number and tax year must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 204 (No Content)
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 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. |
Dividends Income
Resources relating to an individual's dividends income
Dividends Income resources
/individuals/income-received/dividends/{nino}/{taxYear}
This endpoint allows the developer to retrieve dividends income: foreign dividend, dividend income received whilst abroad, stock dividend, redeemable shares, bonus issues of securities and close company loans written off. A National Insurance number and tax year must be provided.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"submittedOn": "2021-04-06T09:37:17Z",
"foreignDividend":[
{
"countryCode":"FRA",
"amountBeforeTax":1999.99,
"taxTakenOff":1999.99,
"specialWithholdingTax":5000.99,
"foreignTaxCreditRelief":false,
"taxableAmount":5000.99
}
],
"dividendIncomeReceivedWhilstAbroad":[
{
"countryCode":"FRA",
"amountBeforeTax":1999.99,
"taxTakenOff":1999.99,
"specialWithholdingTax":5000.99,
"foreignTaxCreditRelief":false,
"taxableAmount":5000.99
}
],
"stockDividend": {
"customerReference":"Stock dividend income",
"grossAmount":5000.99
},
"redeemableShares": {
"customerReference":"Redeemable shares income",
"grossAmount":5000.99
},
"bonusIssuesOfSecurities": {
"customerReference":"Bonus Securities",
"grossAmount":5000.99
},
"closeCompanyLoansWrittenOff": {
"customerReference":"Write off",
"grossAmount":5000.99
},
"links":[
{
"href":"/individuals/income-received/dividends/TC663795B/2021-22",
"rel":"create-and-amend-dividends-income",
"method":"PUT"
},
{
"href":"/individuals/income-received/dividends/TC663795B/2021-22",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/dividends/TC663795B/2021-22",
"rel":"delete-dividends-income",
"method":"DELETE"
}
]
}
| Name | Description |
|---|---|
|
submittedOn
string
required
|
The date the dividends income was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
foreignDividend
array
optional
|
Financial details about foreign dividend income. |
|
countryCode
string
required
|
A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.
For example: |
|
amountBeforeTax
number
optional
|
The total amount of income (in UK pounds) before taking off any foreign tax. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOff
number
optional
|
The total amount of foreign tax taken off income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
specialWithholdingTax
number
optional
|
The total amount of income (in UK pounds) before taking off any Special Withholding Tax (SWT). The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
foreignTaxCreditRelief
boolean
required
|
Boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed.
For example: |
|
taxableAmount
number
required
|
The total taxable amount on dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
dividendIncomeReceivedWhilstAbroad
array
optional
|
Financial details about foreign dividend income received whilst abroad. |
|
countryCode
string
required
|
A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.
For example: |
|
amountBeforeTax
number
optional
|
The total amount of income (in UK pounds) before taking off any foreign tax. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOff
number
optional
|
The total amount of foreign tax taken off income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
specialWithholdingTax
number
optional
|
The total amount of income (in UK pounds) before taking off any Special Withholding Tax (SWT). The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
foreignTaxCreditRelief
boolean
required
|
Boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed.
For example: |
|
taxableAmount
number
required
|
The total taxable amount on dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
stockDividend
object
optional
|
Object that holds the key value for stock dividends income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the stock dividends income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
redeemableShares
object
optional
|
Object that holds the key value for redeemable shares income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the redeemable shares income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
bonusIssuesOfSecurities
object
optional
|
Object that holds the key value for bonus issues of securities income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the bonus securities income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
closeCompanyLoansWrittenOff
object
optional
|
Container that holds the key value for close company loans written off income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the close company loans written off income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
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
create-and-amend-dividends-income
delete-dividends-income
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
DELETE
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO 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 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. |
This endpoint allows the developer to create and amend dividends income: foreign dividend, dividend income received whilst abroad, stock dividend, redeemable shares, bonus issues of securities and close company loans written off. A National Insurance number and tax year must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
{
"foreignDividend":[
{
"countryCode":"FRA",
"amountBeforeTax":1999.99,
"taxTakenOff":1999.99,
"specialWithholdingTax":5000.99,
"foreignTaxCreditRelief":false,
"taxableAmount":5000.99
}
],
"dividendIncomeReceivedWhilstAbroad":[
{
"countryCode":"FRA",
"amountBeforeTax":1999.99,
"taxTakenOff":1999.99,
"specialWithholdingTax":5000.99,
"foreignTaxCreditRelief":false,
"taxableAmount":5000.99
}
],
"stockDividend": {
"customerReference":"Stock dividend income",
"grossAmount":5000.99
},
"redeemableShares": {
"customerReference":"Redeemable shares income",
"grossAmount":5000.99
},
"bonusIssuesOfSecurities": {
"customerReference":"Bonus Securities",
"grossAmount":5000.99
},
"closeCompanyLoansWrittenOff": {
"customerReference":"Written off",
"grossAmount":5000.99
}
}
| Name | Description |
|---|---|
|
foreignDividend
array
optional
|
Financial details about foreign dividend income. |
|
countryCode
string
required
|
A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.
For example: |
|
amountBeforeTax
number
optional
|
The total amount of income (in UK pounds) before taking off any foreign tax. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOff
number
optional
|
The total amount of foreign tax taken off income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
specialWithholdingTax
number
optional
|
The total amount of income (in UK pounds) before taking off any Special Withholding Tax (SWT). The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
foreignTaxCreditRelief
boolean
required
|
Boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed.
For example: |
|
taxableAmount
number
required
|
The total taxable amount on dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
dividendIncomeReceivedWhilstAbroad
array
optional
|
Financial details about foreign dividend income received whilst abroad. |
|
countryCode
string
required
|
A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.
For example: |
|
amountBeforeTax
number
optional
|
The total amount of income (in UK pounds) before taking off any foreign tax. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxTakenOff
number
optional
|
The total amount of foreign tax taken off income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
specialWithholdingTax
number
optional
|
The total amount of income (in UK pounds) before taking off any Special Withholding Tax (SWT). The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
foreignTaxCreditRelief
boolean
required
|
Boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed.
For example: |
|
taxableAmount
number
required
|
The total taxable amount on dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
stockDividend
object
optional
|
Object that holds the key value for stock dividends income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the stock dividends income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
redeemableShares
object
optional
|
Object that holds the key value for redeemable shares income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the redeemable shares income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
bonusIssuesOfSecurities
object
optional
|
Object that holds the key value for bonus issues of securities income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the bonus securities income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
closeCompanyLoansWrittenOff
object
optional
|
Container that holds the key value for close company loans written off income. |
|
customerReference
string
optional
|
A reference the user supplies to identify the close company loans written off income.
Must conform to the regular expression
For example: |
|
grossAmount
number
required
|
The gross amount of the dividends. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links":[
{
"href":"/individuals/income-received/dividends/TC663795B/2021-22",
"rel":"create-and-amend-dividends-income",
"method":"PUT"
},
{
"href":"/individuals/income-received/dividends/TC663795B/2021-22",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/dividends/TC663795B/2021-22",
"rel":"delete-dividends-income",
"method":"DELETE"
}
]
}
| 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
create-and-amend-dividends-income
delete-dividends-income
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
DELETE
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO 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 |
|
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
|
The format of the supplied country code is not valid. |
400 (Bad Request) |
FORMAT_COUNTRY_CODE |
|
Not a valid ISO 3166-1 alpha-3 country code. |
400 (Bad Request) |
RULE_COUNTRY_CODE |
|
The format of the supplied customer reference is not valid. |
400 (Bad Request) |
FORMAT_CUSTOMER_REF |
|
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 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 |
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. |
This endpoint allows a developer to delete dividends income: foreign dividend, dividend income received whilst abroad, stock dividend, redeemable shares, bonus issues of securities and close company loans written off. A National Insurance number and tax year must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 204 (No Content)
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 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. |
Foreign Income
Resources relating to an individual's foreign income
Foreign Income resources
/individuals/income-received/foreign/{nino}/{taxYear}
This endpoint allows the developer to retrieve foreign income: foreign earnings and unremittable foreign income.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"submittedOn": "2021-04-06T09:37:17Z",
"foreignEarnings":{
"customerReference":"FOREIGNINCME123A",
"earningsNotTaxableUK":1999.99
},
"unremittableForeignIncome":[
{
"countryCode":"FRA",
"amountInForeignCurrency":1999.99,
"amountTaxPaid":1999.99
},
{
"countryCode":"IND",
"amountInForeignCurrency":2999.99,
"amountTaxPaid":2999.99
}
],
"links":[
{
"href":"/individuals/income-received/foreign/TC663795B/2021-22",
"rel":"create-and-amend-foreign-income",
"method":"PUT"
},
{
"href":"/individuals/income-received/foreign/TC663795B/2021-22",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/foreign/TC663795B/2021-22",
"rel":"delete-foreign-income",
"method":"DELETE"
}
]
}
| Name | Description |
|---|---|
|
submittedOn
string
required
|
The date the foreign income was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
foreignEarnings
object
optional
|
The container that holds the key value for foreign earnings |
|
customerReference
string
optional
|
A reference the user supplies to identify the foreign income. Must be between 1 and 90 characters in length.
Must conform to the regular expression
For example: |
|
earningsNotTaxableUK
number
required
|
The income received in a foreign country that could not be transferred to UK because of exchange controls. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
unremittableForeignIncome
array
optional
|
Financial details about unremittable foreign income |
|
countryCode
string
required
|
A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.
For example: |
|
amountInForeignCurrency
number
required
|
The total amount of foreign currency. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
amountTaxPaid
number
optional
|
The amount of tax paid on foreign income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
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
create-and-amend-foreign-income
delete-foreign-income
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
DELETE
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO 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 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. |
This endpoint allows the developer to create and amend foreign income: foreign earnings and unremittable foreign income. A National Insurance number and tax year must be provided.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
{
"foreignEarnings":{
"customerReference":"FOREIGNINCME123A",
"earningsNotTaxableUK":1999.99
},
"unremittableForeignIncome":[
{
"countryCode":"FRA",
"amountInForeignCurrency":1999.99,
"amountTaxPaid":1999.99
},
{
"countryCode":"IND",
"amountInForeignCurrency":2999.99,
"amountTaxPaid":2999.99
}
]
}
| Name | Description |
|---|---|
|
foreignEarnings
object
optional
|
The container that holds the key value for foreign earnings |
|
customerReference
string
optional
|
A reference the user supplies to identify the foreign income. Must be between 1 and 90 characters in length.
Must conform to the regular expression
For example: |
|
earningsNotTaxableUK
number
required
|
The income received in a foreign country that could not be transferred to UK because of exchange controls. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
unremittableForeignIncome
array
optional
|
Financial details about unremittable foreign income |
|
countryCode
string
required
|
A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.
For example: |
|
amountInForeignCurrency
number
required
|
The total amount of foreign currency. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
amountTaxPaid
number
optional
|
The amount of tax paid on foreign income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"links":[
{
"href":"/individuals/income-received/foreign/TC663795B/2021-22",
"rel":"create-and-amend-foreign-income",
"method":"PUT"
},
{
"href":"/individuals/income-received/foreign/TC663795B/2021-22",
"rel":"self",
"method":"GET"
},
{
"href":"/individuals/income-received/foreign/TC663795B/2021-22",
"rel":"delete-foreign-income",
"method":"DELETE"
}
]
}
| 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
create-and-amend-foreign-income
delete-foreign-income
|
|
method
string
required
|
The HTTP method type for the endpoint. Limited to the following possible values: PUT
GET
DELETE
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO 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 supplied customer reference is not valid. |
400 (Bad Request) |
FORMAT_CUSTOMER_REF |
|
The format of the supplied country code is not valid. |
400 (Bad Request) |
FORMAT_COUNTRY_CODE |
|
Not a valid ISO 3166-1 alpha-3 country code. |
400 (Bad Request) |
RULE_COUNTRY_CODE |
|
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 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. |
This endpoint allows the developer to delete foreign income: foreign earnings and unremittable foreign income.
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
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Response
HTTP status: 204 (No Content)
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 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. |
Insurance Policies Income
Resources relating to an individual's insurance policies income
Insurance Policies Income resources
/individuals/income-received/insurance-policies/{nino}/{taxYear}
This endpoint allows a developer to retrieve insurance policies and income for less common types of income: Life Insurance Policies, Life Annuity Contracts, Capital Redemption Policies, Voided ISAs, Foreign Policies. A National Insurance number and tax year must be provided.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
taxYear
string
required
|
The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)
For example: |
Request headers
| 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
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Response
HTTP status: 200 (OK)
{
"submittedOn": "2021-04-06T09:37:17Z",
"lifeInsurance": [
{
"customerReference": "INPOLY123A",
"event": "Policy matured",
"gainAmount": 1000.23,
"taxPaid": true,
"yearsHeld": 10,
"yearsHeldSinceLastGain": 1,
"deficiencyRelief": 100.23
}
],
"capitalRedemption": [
{
"customerReference": "INPOLY123B",
"event": "Policy matured",
"gainAmount": 1000.23,
"taxPaid": true,
"yearsHeld": 10,
"yearsHeldSinceLastGain": 1,
"deficiencyRelief": 100.23
}
],
"lifeAnnuity": [
{
"customerReference": "INPOLY123C",
"event": "Policy matured",
"gainAmount": 1000.23,
"taxPaid": true,
"yearsHeld": 10,
"yearsHeldSinceLastGain": 1,
"deficiencyRelief": 100.23
}
],
"voidedIsa": [
{
"customerReference": "INPOLY123D",
"event": "Policy matured",
"gainAmount": 1000.23,
"taxPaidAmount": 100.23,
"yearsHeld": 10,
"yearsHeldSinceLastGain": 1
}
],
"foreign": [
{
"customerReference": "INPOLY123E",
"gainAmount": 1000.23,
"taxPaidAmount": 100.23,
"yearsHeld": 10
}
],
"links": [
{
"href": "/individuals/income-received/insurance-policies/TC663795B/2021-22",
"rel": "create-and-amend-insurance-policies-income",
"method": "PUT"
},
{
"href": "/individuals/income-received/insurance-policies/TC663795B/2021-22",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/income-received/insurance-policies/TC663795B/2021-22",
"rel": "delete-insurance-policies-income",
"method": "DELETE"
}
]
}
| Name | Description |
|---|---|
|
submittedOn
string
required
|
The date the Insurance policy information was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ
For example: |
|
lifeInsurance
array
optional
|
Financial details about life insurance income. |
|
customerReference
string
optional
|
A user supplied reference to identify the insurance policy. Must be between 1 and 90 characters in length.
Must conform to the regular expression
For example: |
|
event
string
optional
|
Details of each individual policy event. Must be between 1 and 90 characters in length.
Must conform to the regular expression
For example: |
|
gainAmount
number
required
|
The amount of the gain. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxPaid
boolean
required
|
A boolean indicating whether tax has been paid.
For example: |
|
yearsHeld
number
optional
|
The number of years the policy has been held. The value must be between 0 and 99 no decimals.
For example: |
|
yearsHeldSinceLastGain
number
option |