A client's employment income for a tax year under MTD Income Tax: the employments themselves, the financial details held against each, and the income belonging to no single employment (non-PAYE tips, share schemes, lump sums, deductions). Employments come from two places and what can be done to them differs: one HMRC hold from the employer's RTI submissions cannot be edited or deleted, only ignored, while a custom employment added here can be amended and deleted but never ignored.

Add Custom Employment

POST /tenants/{tenant}/clients/{client}/mtd/employments/{taxYear}

Adds an employment HMRC do not already hold from the employer's own submissions, and returns the identifier HMRC issue. Only for employments HMRC are missing — adding one that duplicates an HMRC-held employment double-counts the income. To take an HMRC-held employment out of the calculation, ignore it rather than replacing it.

Parameters

Name	Type	Description
tenant*	path string	The Tenant.Code
The Tenant.Code
client*	path string
taxYear*	path string

Request Body*

AddMtdCustomEmploymentRequest

{
  "employerRef": "string",
  "employerName": "string",
  "startDate": "2024-01-01",
  "cessationDate": "2024-01-01",
  "payrollId": "string",
  "occupationalPension": false
}

Responses

200 OK

MtdEmploymentCreatedDto

400 Bad Request

401 Unauthorized – Invalid or missing API key

404 Not Found