HMRC recognised
The part of CIS everyone has to get right.
A contractor must verify every subcontractor with HMRC before paying them, and the answer decides whether 0%, 20% or 30% comes off their pay. Doing that yourself means building HMRC's verification submissions and getting them recognised. Here it is one request.
- Verify one subcontractor, or many in one bulk request
- The deduction rate comes back with the result
- Cancel a request that hasn't been sent
- Get notified by webhook when HMRC answers
How it works
How verification works.
Add the subcontractor
Create them as a contact with their name and UTR, plus company number or National Insurance number as it applies.
Request verification
Ask us to verify them with HMRC. We make the submission and track it until HMRC replies.
Read the rate
Fetch the verification, or let a webhook tell you, then apply the rate to the next payment.
Endpoints
The calls you need.
Every request is sent to https://api.cismanager.com with your API key in the x-api-key header. Each endpoint links to its full reference.
| Method | Endpoint | What it does |
|---|---|---|
| POST | /tenants/{tenant}/contacts/{code}/verification/hmrc-request | Request HMRC verification for one subcontractor |
| POST | /tenants/{tenant}/hmrc-verification-requests | Request verification for many subcontractors at once |
| GET | /tenants/{tenant}/contacts/{code}/verification | Get the verification result and deduction rate |
| DELETE | /tenants/{tenant}/contacts/{code}/verification/hmrc-request | Cancel a pending verification request |
Example
Verify a subcontractor, then read the answer.
# Ask us to verify the subcontractor with HMRC POST https://api.cismanager.com/tenants/{tenant}/contacts/{code}/verification/hmrc-request x-api-key: your-api-key # 202 Accepted: HMRC has been asked { "status": "NotVerified", "hmrcRequest": { "status": "Pending" } } # Later, read the result GET https://api.cismanager.com/tenants/{tenant}/contacts/{code}/verification { "status": "HmrcVerified", "number": "V1234567890", "taxStatus": "NetOfStandardDeduction" }
Responses are trimmed to the main fields. The API reference has every field and an OpenAPI spec to generate a client from.
Questions
Common questions.
Do I have to register with HMRC to use the CIS verification API?
You don't register as a software developer or go through HMRC's recognition process, because CIS Manager is the HMRC recognised software making the submission. The contractor being verified for does need their HMRC CIS details stored in CIS Manager, which you can set through the HMRC settings endpoints.
What does a verification return?
A status (NotVerified, Manual, HmrcVerified or HmrcFailed), the verification number and date, and the subcontractor's tax status: Gross for 0%, NetOfStandardDeduction for 20% or NetOfHigherDeduction for 30%.
Can I verify lots of subcontractors at once?
Yes. The bulk endpoint takes many contacts in one request and tells you which were sent and which were skipped, and why.
New to the scheme? CIS tax explained covers the 0%, 20% and 30% rates, and the CIS HMRC API overview shows how the API fits together.
More