This version is in beta - expect some breaking changes.

Individuals Income Received (MTD) API

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.

Warning You are required by law to submit header data for this API. This includes all associated APIs and endpoints.

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.

Skip to main content

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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 ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c
employerName string required	The name of the employer the employee worked for. Must conform to the regular expression ^\S.{0,73}$ For example: Employer Name Ltd.
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: 2021-04-06T09:37:17Z
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: /individuals/income-received/employments/AA123456A/2021-22 /4557ecb5-fd32-48cc-81f5-e6acd1099f3c
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 ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c
employerName string required	The name of the employer the employee worked for. Must conform to the regular expression ^\S.{0,73}$ For example: Employer Name Ltd.
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: /individuals/income-received/employments/AA123456A/2021-22 /4557ecb5-fd32-48cc-81f5-e6acd1099f3c
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: /individuals/income-received/employments/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: add-custom-employment self
method string required	The HTTP method type for the endpoint. Limited to the following possible values: POST GET

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "employerRef": "123/AB56797",
  "employerName": "Employer Name Ltd.",
  "startDate": "2019-01-01",
  "cessationDate": "2020-06-01",
  "payrollId": "YDIAHPcYFQbOXLCKQ",
  "occupationalPension": false
}

Name	Description
employerRef string optional	A unique identifier, the employer reference number. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB56797
employerName string required	The name of the employer the employee worked for. Must conform to the regular expression ^\S.{0,73}$ For example: Employer Name Ltd.
startDate string required	The date the employment began. It must be provided in the format YYYY-MM-DD For example: 2020-07-01
cessationDate string optional	The date the employment ended. It must be provided in the format YYYY-MM-DD For example: 2020-07-01
payrollId string optional	The unique identifier used by the employer to identify the employee. Must conform to the regular expression ^[A-Za-z0-9.,\-()/=!"%&*; <>'+:\?]{0,38}$ For example: YDIAHPcYFQbOXLCKQ
occupationalPension boolean required	A boolean indicating whether the employment is an occupational pension. The value must be true or false. For example: true

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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 ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c
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: /individuals/income-received/employments/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: list-employments self amend-custom-employment delete-custom-employment
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET PUT DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The employment is listed as starting after the tax year ended.	400 (Bad Request)	RULE_START_DATE_AFTER_TAX_YEAR_END
The employment is listed as ending before the tax year began.	400 (Bad Request)	RULE_CESSATION_DATE_BEFORE_TAX_YEAR_START
The cessation date is earlier than the start date.	400 (Bad Request)	RULE_END_DATE_BEFORE_START_DATE
The submission has been made before the tax year it relates to has ended.	400 (Bad Request)	RULE_TAX_YEAR_NOT_ENDED
The format of the supplied employer ref is not valid.	400 (Bad Request)	FORMAT_EMPLOYER_REF
The format of the employer name is not valid.	400 (Bad Request)	FORMAT_EMPLOYER_NAME
The format of the supplied start date field is not valid.	400 (Bad Request)	FORMAT_START_DATE
The format of the supplied cessation date is not valid.	400 (Bad Request)	FORMAT_CESSATION_DATE
The format of the supplied payroll ID field is not valid.	400 (Bad Request)	FORMAT_PAYROLL_ID
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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 ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB56797
employerName string required	The name of the employer the employee worked for. Must conform to the regular expression ^\S.{0,73}$ For example: Employer Name Ltd.
startDate string optional	The date the employment began. It must be provided in the format YYYY-MM-DD For example: 2020-07-01
cessationDate string optional	The date the employment ended. It must be provided in the format YYYY-MM-DD For example: 2020-07-01
payrollId string optional	The unique identifier used by the employer to identify the employee. Must conform to the regular expression ^[A-Za-z0-9.,\-()/=!"%&*; <>'+:\?]{0,38}$ For example: YDIAHPcYFQbOXLCKQ
occupationalPension boolean optional	A boolean indicating whether the employment is an occupational pension. The value must be true or false. For example: true
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: 2021-04-06T09:37:17Z
submittedOn string optional	The date the custom employment was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ For example: 2021-04-06T09:37:17Z
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: /individuals/income-received/employments/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: list-employments self amend-custom-employment delete-custom-employment ignore-employment unignore-employment
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET PUT POST DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The format of the supplied employment ID field is not valid.	400 (Bad Request)	FORMAT_EMPLOYMENT_ID
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response with custom employment.
HMRC_EMPLOYMENT	Simulates success response with HMRC employment.
HMRC_IGNORED	Simulates success response with ignored HMRC employment.
NOT_FOUND	Simulates the scenario where no data is found.

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "employerRef": "123/AZ12334",
  "employerName": "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 ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB56797
employerName string required	The name of the employer the employee worked for. Must conform to the regular expression ^\S.{0,73}$ For example: Employer Name Ltd.
startDate string required	The date the employment began. It must be provided in the format YYYY-MM-DD For example: 2020-07-01
cessationDate string optional	The date the employment ended. It must be provided in the format YYYY-MM-DD For example: 2020-07-01
payrollId string optional	The unique identifier used by the employer to identify the employee. Must conform to the regular expression ^[A-Za-z0-9.,\-()/=!"%&*; <>'+:\?]{0,38}$ For example: YDIAHPcYFQbOXLCKQ
occupationalPension boolean required	A boolean indicating whether the employment is an occupational pension. The value must be true or false. For example: true

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: /individuals/income-received/employments/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: list-employments self amend-custom-employment delete-custom-employment
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET PUT DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The employment is listed as starting after the tax year ended.	400 (Bad Request)	RULE_START_DATE_AFTER_TAX_YEAR_END
The employment is listed as ending before the tax year began.	400 (Bad Request)	RULE_CESSATION_DATE_BEFORE_TAX_YEAR_START
The cessation date is earlier than the start date.	400 (Bad Request)	RULE_END_DATE_BEFORE_START_DATE
The submission has been made before the tax year it relates to has ended.	400 (Bad Request)	RULE_TAX_YEAR_NOT_ENDED
The format of the supplied employment ID field is not valid.	400 (Bad Request)	FORMAT_EMPLOYMENT_ID
The format of the supplied employer ref is not valid.	400 (Bad Request)	FORMAT_EMPLOYER_REF
The format of the employer name is not valid.	400 (Bad Request)	FORMAT_EMPLOYER_NAME
The format of the supplied start date field is not valid.	400 (Bad Request)	FORMAT_START_DATE
The format of the supplied cessation date is not valid.	400 (Bad Request)	FORMAT_CESSATION_DATE
The format of the supplied payroll ID field is not valid.	400 (Bad Request)	FORMAT_PAYROLL_ID
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The update for an HMRC held employment is not permitted.	403 (Forbidden)	RULE_UPDATE_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.
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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
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 an Employment

POST

This endpoint allows the developer to ignore an HMRC provided employment from among the list of employments for this user. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: /individuals/income-received/employments/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: list-employments self
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The format of the supplied employment ID field is not valid.	400 (Bad Request)	FORMAT_EMPLOYMENT_ID
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The submission has been made before the tax year it relates to has ended.	400 (Bad Request)	RULE_TAX_YEAR_NOT_ENDED
The Employment ID provided is for a custom (user-provided) employment.	403 (Forbidden)	RULE_CUSTOM_EMPLOYMENT
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
CUSTOM_EMPLOYMENT	Simulates the scenario where a custom employment is submitted.
NOT_FOUND	Simulates the scenario where no data is found.

Close Section

/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/unignore

Unignore an Employment

POST

This endpoint allows a developer to unignore the HMRC provided employment from a list of employments for this user. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: /individuals/income-received/employments/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: list-employments self
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The format of the supplied employment ID field is not valid.	400 (Bad Request)	FORMAT_EMPLOYMENT_ID
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The submission has been made before the tax year it relates to has ended.	400 (Bad Request)	RULE_TAX_YEAR_NOT_ENDED
The Employment ID provided is for a custom (user-provided) employment.	403 (Forbidden)	RULE_CUSTOM_EMPLOYMENT
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
CUSTOM_EMPLOYMENT	Simulates the scenario where a custom employment is submitted.
NOT_FOUND	Simulates the scenario where no data is found.

Close Section

/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/financial-details

Retrieve an Employment and its Financial Details

GET

This endpoint allows a developer to retrieve employment information and associated financial data for a given tax year. A National Insurance number, Tax year and Employment ID must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

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: hmrcHeld user latest

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: 2020-07-06T09:37:23Z
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: 2020-07-06T09:37:23Z
dateIgnored string optional	The date the employment was ignored. Must conform to the format YYYY-MM-DDThh:mm:ssZ For example: 2020-07-06T09:37:23Z
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 ^[1-9][0-9]{0,9}$ For example: 1
payrollId string optional	A unique identifier used by the employer to identify the employee. Must conform to the regular expression ^[A-Za-z0-9.,\-()/=!"%&*;<>'+:\?]{0,38}$ For example: 124214112412
companyDirector boolean optional	Identifies the employee as a director when set to True. For example: false
closeCompany boolean optional	Identifies if the employer is a close company. For example: false
directorshipCeasedDate string optional	The date the directorship ended. Must conform to the format YYYY-MM-DD For example: 2020-07-01
startDate string optional	The date the employment began. Must conform to the format YYYY-MM-DD For example: 2020-07-01
cessationDate string optional	The date the employment ended. Must conform to the format YYYY-MM-DD For example: 2020-07-01
occupationalPension boolean optional	Indicates that the employee pays into an occupational pension when set to True. For example: false
disguisedRemuneration boolean optional	Indicates that the employee is declaring disguised remuneration when set to True. For example: false
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 ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB56797
employerName string required	The name of the employer the employee worked for. Must conform to the regular expression ^\S.{0,73}$ For example: Employer Name Ltd.
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: 1024.99
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: 1024.99
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: 2020-07-01
taxWeekNo number optional	The week count of the tax year. The value must be an integer between 1 and 56 For example: 32
taxMonthNo number optional	The month count of the tax year. The value must be an integer between 1 and 12 For example: 7
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: 1500.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: /individuals/income-received/employments/{nino}/{taxYear} /{employmentId}/financial-details
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: self create-and-amend-employment-financial-details delete-employment-financial-details
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET PUT DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The format of the supplied employment ID field is not valid.	400 (Bad Request)	FORMAT_EMPLOYMENT_ID
The format of the supplied source is not valid.	400 (Bad Request)	FORMAT_SOURCE
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. The tax year must not exceed current tax year minus 4.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT ?source=user	Requesting user source simulates success response with User provided financial details.
N/A - DEFAULT ?source=hmrcHeld	Requesting hmrcHeld source simulates success response with HMRC held financial details.
N/A - DEFAULT ?source=latest	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 allows a developer to submit or overwrite financial data for an individual employment. This endpoint can only be used after the tax year has ended. A National Insurance number, Tax year and Employment ID are required.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "employment": {
    "pay": {
      "taxablePayToDate": 1024.99,
      "totalTaxToDate": 1024.99
    },
    "deductions": {
      "studentLoans": {
        "uglDeductionAmount": 1024.99,
        "pglDeductionAmount": 1024.99
      }
    },
    "benefitsInKind": {
      "accommodation": 1024.99,
      "assets": 1024.99,
      "assetTransfer": 1024.99,
      "beneficialLoan": 1024.99,
      "car": 1024.99,
      "carFuel": 1024.99,
      "educationalServices": 1024.99,
      "entertaining": 1024.99,
      "expenses": 1024.99,
      "medicalInsurance": 1024.99,
      "telephone": 1024.99,
      "service": 1024.99,
      "taxableExpenses": 1024.99,
      "van": 1024.99,
      "vanFuel": 1024.99,
      "mileage": 1024.99,
      "nonQualifyingRelocationExpenses": 1024.99,
      "nurseryPlaces": 1024.99,
      "otherItems": 1024.99,
      "paymentsOnEmployeesBehalf": 1024.99,
      "personalIncidentalExpenses": 1024.99,
      "qualifyingRelocationExpenses": 1024.99,
      "employerProvidedProfessionalSubscriptions": 1024.99,
      "employerProvidedServices": 1024.99,
      "incomeTaxPaidByDirector": 1024.99,
      "travelAndSubsistence": 1024.99,
      "vouchersAndCreditCards": 1024.99,
      "nonCash": 1024.99
    }
  }
}

Name	Description
employment object required	Object containing the financial data relating to a single employment.
pay object required	Object containing pay details for a single employment.
taxablePayToDate number required	The gross pay for this employment. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99
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: 1024.99

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: /individuals/income-received/employments/{nino}/{taxYear} /{employmentId}/financial-details
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: self create-and-amend-employment-financial-details delete-employment-financial-details
method string required	The HTTP method type for the endpoint. Limited to the following possible values: GET PUT DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The format of the supplied employment ID field is not valid.	400 (Bad Request)	FORMAT_EMPLOYMENT_ID
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The submission has been made before the tax year it relates to has ended.	400 (Bad Request)	RULE_TAX_YEAR_NOT_ENDED
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_EMPTY_OR_INCORRECT_BODY_SUBMITTED
One or more values have been added with the incorrect format.	400 (Bad Request)	FORMAT_VALUE
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

Close Section

/individuals/income-received/employments/{nino}/{taxYear}/{employmentId}/financial-details

Delete Employment Financial Details

DELETE

This endpoint allows a developer to delete the previously entered financial data from the list of employments for this user. A National Insurance number, Tax year and Employment ID must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22
employmentId string required	The unique identifier for the employment. Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ For example: 4557ecb5-fd32-48cc-81f5-e6acd1099f3c

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

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: hmrcHeld user latest

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: 2020-07-06T09:37:17.542Z
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: 5000.99
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: 5000.99
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: /individuals/income-received/employments/non-paye/AA123456A/2021-22
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. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The format of the supplied 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 ?source=user	Requesting user source simulates success response with User provided Non-PAYE employment income.
N/A - DEFAULT ?source=hmrcHeld	Requesting hmrcHeld source simulates success response with HMRC held Non-PAYE employment income.
N/A - DEFAULT ?source=latest	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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "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: 1024.99

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: /individuals/income-received/employments/non-paye/AA123456A/2021-22
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. That is, the tax year specified is before the minimum 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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

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 allows the developer to retrieve other employment income: share options, shares awarded or received, disability, lump sums and foreign service income. A National Insurance number and tax year must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: 2021-04-06T09:37:17Z
shareOption array optional	Financial details about share options income.
employerName string required	The name of the employer. Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,105}$ For example: BPDTS Ltd.
employerRef string optional	A reference number given to every business that registers with HMRC as an employer. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB456
schemePlanType string required	The type of share scheme or plan the employer has: Equated Monthly Instalment (EMI), Company Share Option Plan (CSOP) or Save As You Earn (SAYE). Limited to the following possible values: EMI CSOP SAYE Other
dateOfOptionGrant string required	The date the option was granted in the format YYYY-MM-DD. For example: 2019-04-20
dateOfEvent string required	The date the event occurred in the format YYYY-MM-DD. For example: 2019-04-20
optionNotExercisedButConsiderationReceived boolean required	Boolean option not exercised but consideration received for lapse, release or assignment of the option. For example: true
amountOfConsiderationReceived number required	The amount of consideration received. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
noOfSharesAcquired number required	The number of shares acquired. The value must be 0 or more. For example: 500
classOfSharesAcquired string required	The class type of shares acquired. Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: Ordinary shares
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,105}$ For example: BPDTS Ltd.
employerRef string optional	A reference number given to every business that registers with HMRC as an employer. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB456
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: 2019-04-20
noOfShareSecuritiesAwarded number required	The number of shares awarded. The value must be 0 or more. For example: 500
classOfShareAwarded string required	The level of voting rights shareholders receive. Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: FIRST
dateSharesAwarded string required	The date the shares ceased in the format YYYY-MM-DD. For example: 2019-04-20
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: true
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: true
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: OTHEREmp123A
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: OTHEREmp123A
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,105}$ For example: BPDTS Ltd.
employerRef string required	A reference number given to every business that registers with HMRC as an employer. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB456
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: 5000.99
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: 5000.99
taxTakenOffInEmployment boolean required	A boolean indicating whether tax has been taken off in employment. For example: false
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: 5000.99
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: 5000.99
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: 5000.99
taxTakenOffInEmployment boolean required	A boolean indicating whether tax has been taken off in employment. For example: false
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: 5000.99
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: 5000.99
taxTakenOffInEmployment boolean required	A boolean indicating whether tax has been taken off in employment. For example: false
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: 5000.99
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: /individuals/income-received/employments/other/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: self create-and-amend-other-employment-income delete-other-employment-income
method string required	The HTTP method type for the endpoint. Limited to the following possible values: PUT GET DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Content-Type required	Specifies the format of the request body, which must be JSON. For example: application/json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "shareOption":[
    {
      "employerName":"Company Ltd",
      "employerRef":"123/AB456",
      "schemePlanType":"EMI",
      "dateOfOptionGrant":"2019-11-20",
      "dateOfEvent":"2019-11-20",
      "optionNotExercisedButConsiderationReceived":true,
      "amountOfConsiderationReceived":23122.22,
      "noOfSharesAcquired":1,
      "classOfSharesAcquired":"FIRST",
      "exercisePrice":12.22,
      "amountPaidForOption":123.22,
      "marketValueOfSharesOnExcise":1232.22,
      "profitOnOptionExercised":1232.33,
      "employersNicPaid":2312.22,
      "taxableAmount":2132.22
    }
  ],
  "sharesAwardedOrReceived":[
    {
      "employerName":"Company Ltd",
      "employerRef":"123/AB456",
      "schemePlanType":"SIP",
      "dateSharesCeasedToBeSubjectToPlan":"2019-11-10",
      "noOfShareSecuritiesAwarded":11,
      "classOfShareAwarded":"FIRST",
      "dateSharesAwarded":"2019-11-20",
      "sharesSubjectToRestrictions":true,
      "electionEnteredIgnoreRestrictions":false,
      "actualMarketValueOfSharesOnAward":2123.22,
      "unrestrictedMarketValueOfSharesOnAward":123.22,
      "amountPaidForSharesOnAward":123.22,
      "marketValueAfterRestrictionsLifted":1232.22,
      "taxableAmount":12321.22
    }
  ],
  "disability":{
    "customerReference":"EMP123A",
    "amountDeducted":1223.22
  },
  "foreignService":{
    "customerReference":"EMP123A",
    "amountDeducted":1223.22
  },
  "lumpSums": [
    {
      "employerName":"Company Ltd",
      "employerRef":"123/AB456",
      "taxableLumpSumsAndCertainIncome": {
        "amount": 5000.99,
        "taxPaid": 5000.99,
        "taxTakenOffInEmployment": false
      },
      "benefitFromEmployerFinancedRetirementScheme": {
        "amount": 5000.99,
        "exemptAmount": 5000.99,
        "taxPaid": 500.99,
        "taxTakenOffInEmployment": false
      },
      "redundancyCompensationPaymentsOverExemption": {
        "amount": 4000.99,
        "taxPaid": 400.99,
        "taxTakenOffInEmployment": false
      },
      "redundancyCompensationPaymentsUnderExemption": {
        "amount": 5000.99
      }
    }
  ]
}

Name	Description
shareOption array optional	Financial details about share options income.
employerName string required	The name of the employer. Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,105}$ For example: BPDTS Ltd.
employerRef string optional	A reference number given to every business that registers with HMRC as an employer. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB456
schemePlanType string required	The type of share scheme or plan the employer has: Equated Monthly Instalment (EMI), Company Share Option Plan (CSOP) or Save As You Earn (SAYE). Limited to the following possible values: EMI CSOP SAYE Other
dateOfOptionGrant string required	The date the option was granted in the format YYYY-MM-DD. For example: 2019-04-20
dateOfEvent string required	The date the event occurred in the format YYYY-MM-DD. For example: 2019-04-20
optionNotExercisedButConsiderationReceived boolean required	Boolean option not exercised but consideration received for lapse, release or assignment of the option. For example: true
amountOfConsiderationReceived number required	The amount of consideration received. The value must be between 0 and 99999999999.99 up to 2 decimal places. For example: 5000.99
noOfSharesAcquired number required	The number of shares acquired. The value must be 0 or more. For example: 500
classOfSharesAcquired string required	The class type of shares acquired. Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: Ordinary shares
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,105}$ For example: BPDTS Ltd.
employerRef string optional	A reference number given to every business that registers with HMRC as an employer. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB456
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: 2019-04-20
noOfShareSecuritiesAwarded number required	The number of shares awarded. The value must be 0 or more. For example: 500
classOfShareAwarded string required	The level of voting rights shareholders receive. Must conform to the regular expression ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: FIRST
dateSharesAwarded string required	The date the shares ceased in the format YYYY-MM-DD. For example: 2019-04-20
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: true
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: true
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: OTHEREmp123A
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: OTHEREmp123A
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,105}$ For example: BPDTS Ltd.
employerRef string required	A reference number given to every business that registers with HMRC as an employer. Must conform to the regular expression ^[0-9]{3}\/[^ ].{0,9}$ For example: 123/AB456
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: 5000.99
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: 5000.99
taxTakenOffInEmployment boolean required	A boolean indicating whether tax has been taken off in employment. For example: false
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: 5000.99
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: 5000.99
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: 5000.99
taxTakenOffInEmployment boolean required	A boolean indicating whether tax has been taken off in employment. For example: false
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: 5000.99
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: 5000.99
taxTakenOffInEmployment boolean required	A boolean indicating whether tax has been taken off in employment. For example: false
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: 5000.99

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: /individuals/income-received/employments/other/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: self create-and-amend-other-employment-income delete-other-employment-income
method string required	The HTTP method type for the endpoint. Limited to the following possible values: PUT GET DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
Where lumpSums have been provided at least one child object is required.	400 (Bad Request)	RULE_LUMP_SUMS
One or more values have been added with the incorrect format.	400 (Bad Request)	FORMAT_VALUE
The format of the supplied customer reference is not valid.	400 (Bad Request)	FORMAT_CUSTOMER_REF
The format of the employer name is not valid.	400 (Bad Request)	FORMAT_EMPLOYER_NAME
The format of the supplied employer ref is not valid.	400 (Bad Request)	FORMAT_EMPLOYER_REF
The supplied date format is not valid.	400 (Bad Request)	FORMAT_DATE
The format of class of shares awarded is not valid.	400 (Bad Request)	FORMAT_CLASS_OF_SHARES_AWARDED
The format of class of shares acquired is not valid.	400 (Bad Request)	FORMAT_CLASS_OF_SHARES_ACQUIRED
The format or value of scheme plan type is not valid.	400 (Bad Request)	FORMAT_SCHEME_PLAN_TYPE
An empty or non-matching body was submitted.	400 (Bad Request)	RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.

Close Section

/individuals/income-received/employments/other/{nino}/{taxYear}

Delete Other Employment Income

DELETE

This endpoint allows the developer to delete other employment income: share options, shares awarded or received, disability, lump sums and foreign service income. A National Insurance number and tax year must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the write:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 204 (No Content)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

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 allows the developer to retrieve dividends income: foreign dividend, dividend income received whilst abroad, stock dividend, redeemable shares, bonus issues of securities and close company loans written off. A National Insurance number and tax year must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B
taxYear string required	The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.) For example: 2021-22

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
Gov-Test-Scenario optional	Only in sandbox environment. See Test Data table for all header values. For example: -
Authorization required	An OAuth 2.0 Bearer Token with the read:self-assessment scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Response headers

Name	Description
X-CorrelationId required	Unique ID for operation tracking String, 36 characters. For example: 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: 2021-04-06T09:37:17Z
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: FRA
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: 1999.99
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: 1999.99
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: 5000.99
foreignTaxCreditRelief boolean required	Boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed. For example: false
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: 5000.99
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: FRA
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: 1999.99
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: 1999.99
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: 5000.99
foreignTaxCreditRelief boolean required	Boolean indicating whether Foreign Tax Credit Relief (FTCR) has been claimed. For example: false
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: Stock dividend income
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: Redeemable shares income
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: Bonus Securities
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: 5000.99
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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,90}$ For example: Write off
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: 5000.99
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: /individuals/income-received/dividends/AA123456A/2021-22
rel string required	A label for the endpoint, which describes how it is related to the current resource. The ‘rel’ will be ‘self’ where the action is retrieval of the same resource. Limited to the following possible values: self create-and-amend-dividends-income delete-dividends-income
method string required	The HTTP method type for the endpoint. Limited to the following possible values: PUT GET DELETE

Error scenarios

Scenario	HTTP status	Code
The format of the supplied NINO field is not valid.	400 (Bad Request)	FORMAT_NINO
The format of the supplied tax year field is not valid.	400 (Bad Request)	FORMAT_TAX_YEAR
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.	400 (Bad Request)	RULE_TAX_YEAR_NOT_SUPPORTED
Tax year range invalid. A tax year range of one year is required.	400 (Bad Request)	RULE_TAX_YEAR_RANGE_INVALID
The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.	403 (Forbidden)	CLIENT_OR_AGENT_NOT_AUTHORISED
The supplied income source could not be found.	404 (Not Found)	MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

Close Section

/individuals/income-received/dividends/{nino}/{taxYear}

Create and Amend Dividends Income

PUT

This endpoint allows the developer to create and amend dividends income: foreign dividend, dividend income received whilst abroad, stock dividend, redeemable shares, bonus issues of securities and close company loans written off. A National Insurance number and tax year must be provided.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Name	Description
nino string required	National Insurance number, in the format AA999999A. For example: TC663795B