v1

latestOpenAPI 3.0.32026-07-234697.5 KB

Create CIS Deductions for Subcontractor

This endpoint allows a developer to create a customer’s CIS deductions that have been previously populated. A National Insurance number must be provided. This endpoint can only be used after the tax year has ended.

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
DEDUCTIONS_DATE_RANGE_INVALID	Simulates the scenario where the deductions period does not align from the 6th of one month to the 5th of the following month.
UNALIGNED_DEDUCTIONS_PERIOD	Simulates the scenario where the deductions periods do not align with the tax year supplied.
TAX_YEAR_NOT_ENDED	Simulates the scenario where the submission is for a tax year that has not ended.
DUPLICATE_SUBMISSION	Simulates the scenario where CIS deductions already exists for this tax year.
DUPLICATE_PERIOD	Simulates the scenario where CIS deductions already exists for this period.
OUTSIDE_AMENDMENT_WINDOW	Simulates the scenario where request cannot be completed as it is outside the amendment window.
STATEFUL	Performs a stateful create.

post/individuals/deductions/cis/{nino}/amendments

Path parameters

ninostring required

Example:TC663795B

National Insurance number in the format AA999999A.

Headers

Authorizationstring required

Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the write:self-assessment scope.

Acceptstring required

Example:application/vnd.hmrc.3.0+json

Specifies the response format and the version of the API to be used.

Content-Typestring required

Example:application/json

Specifies the format of the request body, which must be JSON.

Gov-Test-Scenariostring

Example:-

Only in sandbox environment. See Test Data table for all header values.

Request body

fromDatestring date required

CIS tax year start date. The minimum tax year is 2020-21. The minimum tax year in Sandbox is 2019-20.

Must conform to the format YYYY-MM-DD

toDatestring date required

CIS tax year end date. The minimum tax year is 2020-21. The minimum tax year in Sandbox is 2019-20.

Must conform to the format YYYY-MM-DD

contractorNamestring required

The name of the contractor the subcontractor worked for. Must not be empty or contain only whitespace.

employerRefstring required

A unique identifier, the contractor reference number.

Example request

{
  "fromDate": "2020-04-06",
  "toDate": "2021-04-05",
  "contractorName": "Some Contractor",
  "employerRef": "123/AB56797",
  "periodData": [
    {
      "deductionAmount": 5000.99,
      "deductionFromDate": "2020-07-06",
      "deductionToDate": "2020-08-05",
      "costOfMaterials": 5000.99,
      "grossAmountPaid": 5000.99
    }
  ]
}

Response

Success

submissionIdstring required

A unique identifier for the customer provided CIS deduction amendment.

Example response

{
  "submissionId": "ab123aaa-65ab-488c-9120-f63abc14b9n1"
}