Verify subcontractor API

Verify a subcontractor with HMRC, through one API call.

Send us the subcontractor. We verify them with HMRC and give you the deduction rate to apply, as plain JSON. CIS Manager is HMRC recognised, so there is no HMRC integration for you to build.

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.

MethodEndpointWhat it does
POST/​tenants/​{tenant}/​contacts/​{code}/​verification/​hmrc-requestRequest HMRC verification for one subcontractor
POST/​tenants/​{tenant}/​hmrc-verification-requestsRequest verification for many subcontractors at once
GET/​tenants/​{tenant}/​contacts/​{code}/​verificationGet the verification result and deduction rate
DELETE/​tenants/​{tenant}/​contacts/​{code}/​verification/​hmrc-requestCancel a pending verification request

Getting started with the CIS Manager API →

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

Other CIS jobs the API does.

Build on a CIS API HMRC recognises.

Read the docs, then talk to the people who build it.