---
title: "Retrieve CIS Deductions for Subcontractor"
method: GET
path: "/individuals/deductions/cis/{nino}/current-position/{taxYear}/{source}"
---

# Retrieve CIS Deductions for Subcontractor

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

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/> &bull; fromDate <br/> &bull; toDate <br/> &bull; deductionFromDate <br/> &bull; deductionToDate <br/> &bull; submissionDate <br/> &bull; source |
| STATEFUL                                        | Performs a stateful retrieve.                                                                                               |

## Path parameters

- `nino` string, required
- `taxYear` string, required
- `source` 'all' | 'contractor' | 'customer', required

## Headers

- `Authorization` string, required
- `Accept` string, required
- `Gov-Test-Scenario` string

## Response `200`

Success

- object
  - `totalDeductionAmount` number — The total amount of tax deducted by CIS contractors. The value must be between 0 and 99999999999.99 up to 2 decimal places.
  - `totalCostOfMaterials` number — 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.
  - `totalGrossAmountPaid` number — The total gross amount paid by CIS contractors. The value must be between 0 and 99999999999.99 up to 2 decimal places.
  - `cisDeductions` object[], required — List of the components that make up the overall deductions.
    - `fromDate` string, date, required — CIS start date of a tax year. Must conform to the format `YYYY-MM-DD`
    - `toDate` string, date, required — CIS end date of a tax year. Must conform to the format `YYYY-MM-DD`
    - `contractorName` string — The name of the contractor the subcontractor worked for. Must not be empty or contain only whitespace.
    - `employerRef` string, required — A unique identifier, the contractor reference number.
    - `totalDeductionAmount` number — The total amount of tax deducted by a CIS contractor. The value must be between 0 and 99999999999.99 up to 2 decimal places.
    - `totalCostOfMaterials` number — The total cost of materials incurred under CIS by the subcontractor. This value must be between 0 and 99999999999.99 up to 2 decimal places.
    - `totalGrossAmountPaid` number — The total gross amount paid by a CIS contractor. The value must be between 0 and 99999999999.99 up to 2 decimal places.
    - `periodData` object[], required — List of deductions.
      - `deductionFromDate` string, date, required — The From date when the deduction was made within the CIS tax year period. Must conform to the format `YYYY-MM-DD`
      - `deductionToDate` string, date, required — The To date when the deduction was made within the CIS tax year period. Must conform to the format `YYYY-MM-DD`
      - `deductionAmount` number — The amount of tax deducted by the contractor. This value must be between 0 and 99999999999.99 up to 2 decimal places.
      - `costOfMaterials` number — The cost of materials incurred under CIS. This value must be between 0 and 99999999999.99 up to 2 decimal places.
      - `grossAmountPaid` number — The gross amount paid under CIS. This value must be between 0 and 99999999999.99 up to 2 decimal places.
      - `submissionDate` string, date-time, required — The date the deduction was submitted, in the format `YYYY-MM-DDThh:mm:ss.SSZ`
      - `submissionId` string, uuid — The unique identifier for the submission.
      - `source` 'customer' | 'contractor', required — The source of the data.

## Other responses

- `400` — Bad request
- `403` — Forbidden
- `404` — Not Found

---

[API](https://skmtc.net/hmrc/apis/cis-deductions-mtd.md) · [All operations](https://skmtc.net/hmrc/apis/cis-deductions-mtd/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hmrc/cis-deductions-mtd/revisions/77097460e998/schema)