v1

latestOpenAPI 3.0.32026-07-134697.4 KB

Retrieve CIS Deductions for Subcontractor

This endpoint allows a developer to retrieve a customer's latest CIS deductions data and whether it was submitted by a contractor or user. A National Insurance number, tax year and source must be provided.

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 with customer and contractor deductions.
N/A - DEFAULT <br> using source all	Simulates success response with customer and contractor deductions
N/A - DEFAULT <br> using source contractor	Simulates success response with contractor deductions.
N/A - DEFAULT <br> using source customer	Simulates success response with customer deductions.
TAX_YEAR_RANGE_INVALID	Simulates the scenario where specified tax year is outside the allowable tax years (the current tax year minus four years).
TAX_YEAR_NOT_SUPPORTED	Simulates the scenario where the tax year is not supported.
NOT_FOUND	Simulates the scenario where no data is found.
DYNAMIC	The following response values will change to correspond to the values submitted in the request: <br/> • fromDate <br/> • toDate <br/> • deductionFromDate <br/> • deductionToDate <br/> • submissionDate <br/> • source
STATEFUL	Performs a stateful retrieve.

get/individuals/deductions/cis/{nino}/current-position/{taxYear}/{source}

Path parameters

ninostring required

Example:TC663795B

National Insurance number in the format AA999999A.

taxYearstring required

Example:2021-22

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years.

source'all' | 'contractor' | 'customer' required

Example:all

The source of amended data. Defaults to all.

Headers

Authorizationstring required

Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the read: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.

Gov-Test-Scenariostring

Example:-

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

Response

Success

totalDeductionAmountnumber

The total amount of tax deducted by CIS contractors. The value must be between 0 and 99999999999.99 up to 2 decimal places.

totalCostOfMaterialsnumber

The total cost of materials incurred under CIS by the subcontractor across all of the CIS contractors that they worked for. This value must be between 0 and 99999999999.99 up to 2 decimal places.

totalGrossAmountPaidnumber

The total gross amount paid by CIS contractors. The value must be between 0 and 99999999999.99 up to 2 decimal places.

Example response

{
  "totalDeductionAmount": 5000.99,
  "totalCostOfMaterials": 5000.99,
  "totalGrossAmountPaid": 5000.99,
  "cisDeductions": [
    {
      "fromDate": "2020-04-06",
      "toDate": "2021-04-05",
      "contractorName": "Some Contractor",
      "employerRef": "123/AC80213",
      "totalDeductionAmount": 5000.99,
      "totalCostOfMaterials": 5000.99,
      "totalGrossAmountPaid": 5000.99,
      "periodData": [
        {
          "deductionFromDate": "2020-07-06",
          "deductionToDate": "2020-08-05",
          "deductionAmount": 5000.99,
          "costOfMaterials": 50,
          "grossAmountPaid": 5000.99,
          "submissionDate": "2020-05-11T16:38:57Z",
          "submissionId": "4557ecb5-fd32-48cc-81f5-e6acd1099f3c"
        }
      ]
    }
  ]
}

All 4 operations