Individuals Income Received (MTD) API
Date | Amount |
---|---|
Version and status | |
Available in Sandbox | Yes |
Sandbox base URL | https://test-api.service.hmrc.gov.uk |
Available in Production | Yes |
Production base URL | https://api.service.hmrc.gov.uk |
Overview
This API allows developers to retrieve, create, amend or delete data relating to:
- employment income (this includes income from occupational pensions)
- other employment income
- Non-PAYE employment income
- Capital Gains on residential property disposal
- other Capital Gains and disposals
- dividends income
- foreign income
- insurance policies income
- pensions income
- savings income
- other income
For information on how to connect to this API see the Income Tax MTD end-to-end service guide.
Send fraud prevention data
HMRC monitors transactions to help protect your customers' confidential data from criminals and fraudsters.
Check the data you need to send. You can also use the Test API during initial development and as part of your quality assurance checks.
Versioning
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
Errors
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
Single errors will be returned in the following format:
{
"code": "FORMAT_FIELD_NAME",
"message": "The provided FieldName is invalid"
}
Where possible, multiple errors will be returned with INVALID_REQUEST
in the following format:
{
"code": "INVALID_REQUEST",
"message": "Invalid request",
"errors": [
{
"code": "RULE_FIELD_NAME",
"message": "The provided FieldName is not allowed"
},
{
"code": "FORMAT_FIELD_NAME",
"message": "The provided FieldName is invalid"
}
]
}
Where it is possible for the same error to be returned multiple times, message
will describe the expected format and paths
will show the fields which are invalid.
Where arrays are submitted a number indicates the object in the array sequence, for example, /arrayName/1/fieldName
An example with single error:
{
"code": "FORMAT_STRING_NAME",
"message": "The provided field is not valid",
"paths": [ "/arrayName/0/fieldName" ]
}
An example with multiple errors:
{
"code": "INVALID_REQUEST",
"message": "Invalid request",
"errors": [
{
"code": "FORMAT_VALUE",
"message": "The value should be between 0 and 99999999999.99",
"paths": [ "/objectName/fieldName1", "/arrayName/0/fieldName2" ]
},
{
"code": "FORMAT_STRING_NAME",
"message": "The provided field is not valid",
"paths": [ "/arrayName/0/fieldName3", "/arrayName/1/fieldName3" ]
}
]
}
Changelog
You can find the changelog in the income-tax-mtd-changelog GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the income-tax-mtd-changelog GitHub page.
Testing
You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.
It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.
If you have a specific testing need that is not supported in the sandbox, contact our support team.
Some APIs may be marked [test only]. This means that they are not available for use in production and may change.
Endpoints
Employments
Resources relating to an individual's employments (please note, an occupational pension is classed as employment income and is identified by the occupationalPension property)
Employments resources
/individuals/income-received/employments/{nino}/{taxYear}
List Employments
GET
This endpoint allows a developer to list the employments for this user. A National Insurance number and Tax year must be provided.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
{ "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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}
Add a Custom Employment
POST
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.
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. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "employerRef": "123/AB56797", "employerName": "Employer Name Ltd.", "startDate": "2019-01-01", "cessationDate": "2020-06-01", "payrollId": "YDIAHPcYFQbOXLCKQ", "occupationalPension": false }
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: |
occupationalPension
boolean
required
|
A boolean indicating whether the employment is an occupational pension. The value must be true or false.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}
Retrieve an Employment
GET
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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
HMRC Employment
{ "employerRef": "123/AZ12334", "employerName": "Employer Name Ltd.", "startDate": "2020-06-17", "cessationDate": "2020-06-17", "payrollId": "YDIAHPcYFQbOXLCKQ", "occupationalPension": false, "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" } ] }
Custom Employment
{ "employerRef": "123/AZ12334", "employerName": "Employer Name Ltd.", "startDate": "2020-06-17", "cessationDate": "2020-06-17", "payrollId": "YDIAHPcYFQbOXLCKQ", "occupationalPension": false, "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
optional
|
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: |
occupationalPension
boolean
optional
|
A boolean indicating whether the employment is an occupational pension. The value must be true or false.
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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}
Amend a Custom Employment
PUT
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.
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. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "employerRef": "123/AZ12334", "employerName": "J Ltd.", "startDate": "2019-01-01", "cessationDate": "2020-06-01", "payrollId": "A1234567", "occupationalPension": false }
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: |
occupationalPension
boolean
required
|
A boolean indicating whether the employment is an occupational pension. The value must be true or false.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links":[ { "href":"/individuals/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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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 update for an HMRC held employment is not permitted. |
400 (Bad Request) |
RULE_UPDATE_FORBIDDEN |
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. |
HMRC_HELD |
Simulates the scenario in which an update of an HMRC held employment is not permitted. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}
Delete a Custom Employment
DELETE
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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied 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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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 |
A deletion for an HMRC held employment is not permitted. |
403 (Forbidden) |
RULE_DELETE_FORBIDDEN |
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. |
NOT_FOUND |
Simulates the scenario where no data is found. |
DELETE_FORBIDDEN |
Simulates the scenario where the deletion is not permitted. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/ignore
Ignore Employment
POST
This endpoint enables you to ignore an HMRC-provided employment from a list of employments. This endpoint can only be used after the tax year has ended. A National Insurance number, tax year and Employment ID must be provided.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links":[ { "href":"/individuals/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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
400 (Bad Request) |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/unignore
Unignore Employment
POST
This endpoint enables you 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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links":[ { "href":"/individuals/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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
400 (Bad Request) |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/financial-details
Retrieve an Employment and its Financial Details
GET
This endpoint enables you 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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
User provided financial details
{ "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" } ] }
HMRC held financial details
{ "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: |
offPayrollWorker
boolean
optional
|
[test only] Indicates the employee's off-payroll working status for employment. Only present for tax year 2023-24 or later.
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
optional
|
The gross pay for this employment. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
totalTaxToDate
number
optional
|
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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/financial-details
Create and Amend Employment Financial Details
PUT
This endpoint enables you to submit or overwrite financial data for an individual employment. A National Insurance number, tax year and Employment ID are required.
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. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "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 }, "offPayrollWorker": true } }
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: |
offPayrollWorker
boolean
optional
|
[test only] Indicates the employee's off-payroll working status for employment. Required for tax year 2023-4 or later. Not supported for earlier tax years.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links": [ { "href":"/individuals/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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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 offPayrollWorker field was not provided; it must be provided for tax year 2023-24 or later. |
400 (Bad Request) |
MISSING_OFF_PAYROLL_WORKER |
The offPayrollWorker field is not allowed for tax years prior to 2023-24. |
400 (Bad Request) |
NOT_ALLOWED_OFF_PAYROLL_WORKER |
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. |
Close Section
/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/financial-details
Delete Employment Financial Details
DELETE
This endpoint enables you to delete the previously entered financial data for an employment. This endpoint can only be used after the tax year has ended. A National Insurance number, tax year and Employment ID must be provided.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied 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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
Non-PAYE Employment Income
These endpoints allow a user to create, amend, retrieve and delete Non-PAYE employment income and tips
Resources relating to an individual's Non-PAYE employment income
Non-PAYE Employment Income resources
/individuals/income-received/employments/non-paye/{nino}/{taxYear}
Retrieve Non-PAYE employment income
GET
This endpoint allows a developer to retrieve Non-PAYE employment income. A National Insurance number and tax year must be provided.
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: |
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
User provided Non-PAYE employment income
{ "submittedOn": "2020-07-06T09:37:17.542Z", "source": "user", "totalNonPayeIncome": 876.45, "nonPayeIncome": { "tips": 876.45 }, "links": [ { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"PUT", "rel":"create-and-amend-non-paye-employment-income" }, { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"GET", "rel":"self" }, { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"DELETE", "rel":"delete-non-paye-employment-income" } ] }
HMRC held Non-PAYE employment income
{ "submittedOn": "2020-07-06T09:37:17.542Z", "source": "hmrcHeld", "totalNonPayeIncome": 876.45, "nonPayeIncome": { "tips": 876.45 }, "links": [ { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"PUT", "rel":"create-and-amend-non-paye-employment-income" }, { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"GET", "rel":"self" }, { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"DELETE", "rel":"delete-non-paye-employment-income" } ] }
Latest Non-PAYE employment income
{ "submittedOn": "2020-07-06T09:37:17.542Z", "source": "latest", "totalNonPayeIncome": 876.45, "nonPayeIncome": { "tips": 876.45 }, "links": [ { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"PUT", "rel":"create-and-amend-non-paye-employment-income" }, { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"GET", "rel":"self" }, { "href":"/individuals/income-received/employments/non-paye/{nino}/{taxYear}", "method":"DELETE", "rel":"delete-non-paye-employment-income" } ] }
Name | Description |
---|---|
submittedOn
string
required
|
The date the non-PAYE employment income was submitted. It must be provided in the format YYYY-MM-DDThh:mm:ss.SSSZ.
For example: |
source
string
required
|
Specifies the source of data. Limited to the following possible values: hmrcHeld
user
latest
|
totalNonPayeIncome
number
optional
|
The total amount of non PAYE income. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
nonPayeIncome
object
optional
|
Details of non PAYE income. |
tips
number
optional
|
The total amount of tips received. 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-non-paye-employment-income
delete-non-paye-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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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 source is not valid. |
400 (Bad Request) |
FORMAT_SOURCE |
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 Non-PAYE employment income. |
N/A - DEFAULT |
Requesting hmrcHeld source simulates success response with HMRC held Non-PAYE employment income. |
N/A - DEFAULT |
Requesting latest source simulates success response with Latest Non-PAYE employment income submitted. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/income-received/employments/non-paye/{nino}/{taxYear}
Create and Amend Non-PAYE employment income
PUT
This endpoint allows a developer to create and amend Non-PAYE employment income. A National Insurance number and tax year must be provided. This endpoint can only be used after the tax year has ended.
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. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "tips": 99.99 }
Name | Description |
---|---|
tips
number
optional
|
The total amount of tips received. The value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links":[ { "href":"/individuals/income-received/employments/non-paye/AA123456A/2021-22", "rel":"create-and-amend-non-paye-employment-income", "method":"PUT" }, { "href":"/individuals/income-received/employments/non-paye/AA123456A/2021-22", "rel":"self", "method":"GET" }, { "href":"/individuals/income-received/employments/non-paye/AA123456A/2021-22", "rel":"delete-non-paye-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: create-and-amend-non-paye-employment-income
self
delete-non-paye-employment-income
|
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 |
One or more values have been added with the incorrect format. |
400 (Bad Request) |
FORMAT_VALUE |
The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
The submission has been made before the tax year it relates to has ended. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_ENDED |
Tax year range invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
An empty or non-matching body was submitted. |
400 (Bad Request) |
RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED |
The supplied income source could not be found. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
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. |
NOT_FOUND |
Simulates the scenario where no data is found. |
Close Section
/individuals/income-received/employments/non-paye/{nino}/{taxYear}
Delete Non-PAYE employment income
DELETE
This endpoint allows a developer to delete Non-PAYE employment income. A National Insurance number and tax year must be provided.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
Other Employment Income
Resources relating to an individual's other employment income
Other Employment Income resources
/individuals/income-received/employments/other/{nino}/{taxYear}
Retrieve Other Employment Income
GET
This endpoint enables you 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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
{ "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.
Must conform to the regular expression
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: Enterprise Management Incentive (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.
Must conform to the regular expression
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.
Must conform to the regular expression
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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
/individuals/income-received/employments/other/{nino}/{taxYear}
Create and Amend Other Employment Income
PUT
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.
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. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "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.
Must conform to the regular expression
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: Enterprise Management Incentive (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.
Must conform to the regular expression
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.
Must conform to the regular expression
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: |
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
{ "links":[ { "href":"/individuals/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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
/individuals/income-received/employments/other/{nino}/{taxYear}
Delete Other Employment Income
DELETE
This endpoint enables you 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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 204 (No Content)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The format of the supplied NINO field is not valid. |
400 (Bad Request) |
FORMAT_NINO |
The format of the supplied tax year field is not valid. |
400 (Bad Request) |
FORMAT_TAX_YEAR |
The specified tax year is not supported. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section
Dividends Income
Resources relating to an individual's dividends income
Dividends Income resources
/individuals/income-received/dividends/{nino}/{taxYear}
Retrieve Dividends Income
GET
This endpoint enables you 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.
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. application/vnd.hmrc.1.0+json
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. -
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
Response headers
Name | Description |
---|---|
X-CorrelationId
required
|
Unique ID for operation tracking a1e8057e-fbbc-47a8-a8b4-78d9f015c253
|
See also fraud prevention.
{ "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. Either the tax year specified is before the minimum tax year value, or it is after the maximum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
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. |
Close Section