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

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

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.

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.

Response

HTTP status: 200 (OK)

{
  "employments":[
    {
      "employmentId":"1557ecb5-fd32-48cc-81f5-e6acd1099f1c",
      "employerName":"Employer Name Ltd.",
      "dateIgnored":"2020-06-17T10:53:38Z",
      "links":[
        {
          "href":"/individuals/income-received/employments/TC663795B/2021-22/1557ecb5-fd32-48cc-81f5-e6acd1099f1c",
          "rel":"self",
          "method":"GET"
        }
      ]
    }
  ],
  "customEmployments":[
    {
      "employmentId":"2557ecb5-fd32-48cc-81f5-e6acd1099f2c",
      "employerName":"Employer Name Ltd.",
      "links":[
        {
          "href":"/individuals/income-received/employments/TC663795B/2021-22/2557ecb5-fd32-48cc-81f5-e6acd1099f2c",
          "rel":"self",
          "method":"GET"
        }
      ]
    }
  ],
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"add-custom-employment",
      "method":"POST"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"self",
      "method":"GET"
    }
  ]
}

Name Description
employments
array
optional

Array containing details of employments provided to HMRC by employers.
employmentId
string
required

The unique identifier for the employment.

Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-4[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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,74}$

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}-4[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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,74}$

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": "124214112412"
}

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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,74}$

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: 124214112412

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.

Response

HTTP status: 200 (OK)

{
  "employmentId": "4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"list-employments",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"amend-custom-employment",
      "method":"PUT"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"delete-custom-employment",
      "method":"DELETE"
    }
  ]
}

Name Description
employmentId
string
required

The unique identifier for the employment.

Must conform to the regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-4[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}-4[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.

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.

Response

HTTP status: 200 (OK)

HMRC Employment 

{
  "employerRef": "123/AZ12334",
  "employerName": "Employer Name Ltd.",
  "startDate": "2020-06-17",
  "cessationDate": "2020-06-17",
  "payrollId": "123345657",
  "dateIgnored": "2020-06-17T10:53:38Z",
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"list-employments",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/unignore",
      "rel":"unignore-employment",
      "method":"POST"
    }
  ]
}

Custom Employment 

{
  "employerRef": "123/AZ12334",
  "employerName": "Employer Name Ltd.",
  "startDate": "2020-06-17",
  "cessationDate": "2020-06-17",
  "payrollId": "123345657",
  "submittedOn": "2021-04-06T09:37:17Z",
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"list-employments",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"amend-custom-employment",
      "method":"PUT"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"delete-custom-employment",
      "method":"DELETE"
    }
  ]
}

Name Description
employerRef
string
optional

A unique identifier, the employer reference number.

Must conform to the regular expression ^[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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,74}$

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: 124214112412

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}-4[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": "Employer Name Ltd.",
  "startDate": "2019-01-01",
  "cessationDate": "2020-06-01",
  "payrollId": "124214112412"
}

Name Description
employerRef
string
optional

A unique identifier, the employer reference number.

Must conform to the regular expression ^[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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,74}$

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: 124214112412

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.

Response

HTTP status: 200 (OK)

{
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"list-employments",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"amend-custom-employment",
      "method":"PUT"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"delete-custom-employment",
      "method":"DELETE"
    }
  ]
}

Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.
href
string
required

The relative URL of the endpoint.

For example: /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 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

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}-4[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.

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.

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of the supplied employment ID field is not valid.

400 (Bad Request)

FORMAT_EMPLOYMENT_ID

The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.

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}-4[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.

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.

Response

HTTP status: 200 (OK)

{
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"list-employments",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"self",
      "method":"GET"
    }
  ]
}

Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.
href
string
required

The relative URL of the endpoint.

For example: /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}-4[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.

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.

Response

HTTP status: 200 (OK)

{
  "links":[
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22",
      "rel":"list-employments",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c",
      "rel":"self",
      "method":"GET"
    }
  ]
}

Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.
href
string
required

The relative URL of the endpoint.

For example: /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}-4[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.

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.

Response

HTTP status: 200 (OK)

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 ^[0-9a-zA-Z{À-˿’}\- _&`():.'^]{1,74}$

For example: Employer Name Ltd.

pay
object
optional

Object containing pay details for a single employment.
taxablePayToDate
number
required

The gross pay for this employment. The value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 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

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}-4[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

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.

Response

HTTP status: 200 (OK)

{
  "links": [
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
      "rel":"create-and-amend-employment-financial-details",
      "method":"PUT"
    },
    {
      "href":"/individuals/income-received/employments/TC663795B/2021-22/4557ecb5-fd32-48cc-81f5-e6acd1099f3c/financial-details",
      "rel":"delete-employment-financial-details",
      "method":"DELETE"
    }
  ]
}

Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.
href
string
required

The relative URL of the endpoint.

For example: /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

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}-4[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.

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.

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The format of the supplied employment ID field is not valid.

400 (Bad Request)

FORMAT_EMPLOYMENT_ID

The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.

Close Section

Non-PAYE Employment Income

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.

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.

Response

HTTP status: 200 (OK)

User provided Non-PAYE employment income 

{
  "submittedOn": "2020-07-06T09:37:17Z",
  "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:17Z",
  "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"
    }
  ]
}

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

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

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

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.

Response

HTTP status: 200 (OK)

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

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.

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.

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.

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.

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.

Response

HTTP status: 200 (OK)

{
  "submittedOn": "2021-04-06T09:37:17Z",
  "shareOption":[
    {
      "employerName":"Company Ltd",
      "employerRef":"123/AB456",
      "schemePlanType":"EMI",
      "dateOfOptionGrant":"2019-11-20",
      "dateOfEvent":"2019-11-20",
      "optionNotExercisedButConsiderationReceived":true,
      "amountOfConsiderationReceived":23122.22,
      "noOfSharesAcquired":1,
      "classOfSharesAcquired":"FIRST",
      "exercisePrice":12.22,
      "amountPaidForOption":123.22,
      "marketValueOfSharesOnExcise":1232.22,
      "profitOnOptionExercised":1232.33,
      "employersNicPaid":2312.22,
      "taxableAmount":2132.22
    }
  ],
  "sharesAwardedOrReceived":[
    {
      "employerName":"Company Ltd",
      "employerRef":"123/AB456",
      "schemePlanType":"SIP",
      "dateSharesCeasedToBeSubjectToPlan":"2019-11-10",
      "noOfShareSecuritiesAwarded":11,
      "classOfShareAwarded":"FIRST",
      "dateSharesAwarded":"2019-11-20",
      "sharesSubjectToRestrictions":true,
      "electionEnteredIgnoreRestrictions":false,
      "actualMarketValueOfSharesOnAward":2123.22,
      "unrestrictedMarketValueOfSharesOnAward":123.22,
      "amountPaidForSharesOnAward":123.22,
      "marketValueAfterRestrictionsLifted":1232.22,
      "taxableAmount":12321.22
    }
  ],
  "disability":{
    "customerReference":"EMP123A",
    "amountDeducted":1223.22
  },
  "foreignService":{
    "customerReference":"EMP123A",
    "amountDeducted":1223.22
  },
  "lumpSums": [
    {
      "employerName":"Company Ltd",
      "employerRef":"123/AB456",
      "taxableLumpSumsAndCertainIncome": {
        "amount": 5000.99,
        "taxPaid": 5000.99,
        "taxTakenOffInEmployment": false
      },
      "benefitFromEmployerFinancedRetirementScheme": {
        "amount": 5000.99,
        "exemptAmount": 5000.99,
        "taxPaid": 500.99,
        "taxTakenOffInEmployment": false
      },
      "redundancyCompensationPaymentsOverExemption": {
        "amount": 4000.99,
        "taxPaid": 400.99,
        "taxTakenOffInEmployment": false
      },
      "redundancyCompensationPaymentsUnderExemption": {
        "amount": 5000.99
      }
    }
  ],
  "links":[
    {
      "href":"/individuals/income-received/employments/other/TC663795B/2021-22",
      "rel":"create-and-amend-other-employment-income",
      "method":"PUT"
    },
    {
      "href":"/individuals/income-received/employments/other/TC663795B/2021-22",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/employments/other/TC663795B/2021-22",
      "rel":"delete-other-employment-income",
      "method":"DELETE"
    }
  ]
}

Name Description
submittedOn
string
required

The date the other employment income was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ

For example: 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

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.

Response

HTTP status: 200 (OK)

{
   "links":[
      {
         "href":"/individuals/income-received/employments/other/TC663795B/2021-22",
         "rel":"create-and-amend-other-employment-income",
         "method":"PUT"
      },
      {
         "href":"/individuals/income-received/employments/other/TC663795B/2021-22",
         "rel":"self",
         "method":"GET"
      },
      {
         "href":"/individuals/income-received/employments/other/TC663795B/2021-22",
         "rel":"delete-other-employment-income",
         "method":"DELETE"
      }
   ]
}

Name Description
links
array
optional

A list of endpoint links that indicate possible actions related to the current resource.
href
string
required

The relative URL of the endpoint.

For example: /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

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.

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.

Response

HTTP status: 204 (No Content)

Error scenarios

Scenario HTTP status Code

The format of the supplied NINO field is not valid.

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid.

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

The supplied income source could not be found.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates success response.

NOT_FOUND

Simulates the scenario where no data is found.

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.

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.

Response

HTTP status: 200 (OK)

{
  "submittedOn": "2021-04-06T09:37:17Z",
  "foreignDividend":[
    {
      "countryCode":"FRA",
      "amountBeforeTax":1999.99,
      "taxTakenOff":1999.99,
      "specialWithholdingTax":5000.99,
      "foreignTaxCreditRelief":false,
      "taxableAmount":5000.99
    }
  ],
  "dividendIncomeReceivedWhilstAbroad":[
    {
      "countryCode":"FRA",
      "amountBeforeTax":1999.99,
      "taxTakenOff":1999.99,
      "specialWithholdingTax":5000.99,
      "foreignTaxCreditRelief":false,
      "taxableAmount":5000.99
    }
  ],
  "stockDividend": {
      "customerReference":"Stock dividend income",
      "grossAmount":5000.99
    },
  "redeemableShares": {
    "customerReference":"Redeemable shares income",
    "grossAmount":5000.99
  },
  "bonusIssuesOfSecurities": {
    "customerReference":"Bonus Securities",
    "grossAmount":5000.99
  },
  "closeCompanyLoansWrittenOff": {
    "customerReference":"Write off",
    "grossAmount":5000.99
  },
  "links":[
    {
      "href":"/individuals/income-received/dividends/TC663795B/2021-22",
      "rel":"create-and-amend-dividends-income",
      "method":"PUT"
    },
    {
      "href":"/individuals/income-received/dividends/TC663795B/2021-22",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"/individuals/income-received/dividends/TC663795B/2021-22",
      "rel":"delete-dividends-income",
      "method":"DELETE"
    }
  ]
}

Name Description
submittedOn
string
required

The date the dividends income was added. It must be provided in the format YYYY-MM-DDThh:mm:ssZ

For example: 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

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

Scenario: Full Dividend Income Amendment 

{
  "foreignDividend":[
    {
      "countryCode":"FRA",
      "amountBeforeTax":1999.99,
      "taxTakenOff":1999.99,
      "specialWithholdingTax":5000.99,
      "foreignTaxCreditRelief":false,
      "taxableAmount":5000.99
    }
  ],
  "dividendIncomeReceivedWhilstAbroad":[
    {
      "countryCode":"FRA",
      "amountBeforeTax":1999.99,
      "taxTakenOff":1999.99,
      "specialWithholdingTax":5000.99,
      "foreignTaxCreditRelief":false,
      "taxableAmount":5000.99
    }
  ],
  "stockDividend": {
      "customerReference":"Stock dividend income",
      "grossAmount":5000.99
    },
  "redeemableShares": {
    "customerReference":"Redeemable shares income",
    "grossAmount":5000.99
  },
  "bonusIssuesOfSecurities": {
    "customerReference":"Bonus Securities",
    "grossAmount":5000.99
  },
  "closeCompanyLoansWrittenOff": {
    "customerReference":"Written off",
    "grossAmount":5000.99
  }
}

Name Description
foreignDividend
array
optional

Financial details about foreign dividend income.
countryCode
string
required

A three-letter code that represents a country name. The value must in a ISO 3166-1 Alpha-3 format.

For example: 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.