HMRC recognised
Monthly returns without the HMRC plumbing.
Contractors must send HMRC a CIS300 return by the 19th of every month. Building that submission yourself means HMRC's message formats, testing and recognition. With this API you create the return, submit it and read back what HMRC says.
- The return is built from the invoices and payments you recorded
- Review the full breakdown before anything is sent
- Re-open a return if you need to correct it
- Get notified by webhook when HMRC accepts a return
How it works
How a return is filed.
Create the return
Open the return for a tax month. It collects the payments and deductions you have recorded for that month.
Review it
Fetch the return and its breakdown to check every subcontractor and amount before you file.
Submit to HMRC
Submit the return. We send it to HMRC and keep the submission status for you to read.
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}/returns | Create the return for a month |
| GET | /tenants/{tenant}/returns/{year}/{month}/breakdown | Review the return line by line |
| POST | /tenants/{tenant}/returns/{year}/{month}/submission | Submit the return to HMRC |
| GET | /tenants/{tenant}/returns/{year}/{month}/submission | Read the submission status from HMRC |
| DELETE | /tenants/{tenant}/returns/{year}/{month}/submission | Re-open a return to correct it |
Example
Submit a return and read its status.
# Submit the return for a tax month POST https://api.cismanager.com/tenants/{tenant}/returns/2026/10/submission x-api-key: your-api-key # 202 Accepted: the return has gone to HMRC { "year": 2026, "month": 10, "status": "Submitted", "labour": 8250.00, "deductions": 1650.00 } # Check what HMRC has said GET https://api.cismanager.com/tenants/{tenant}/returns/2026/10/submission { "status": "Completed" }
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.
When is the CIS300 return due?
By the 19th of the month after the tax month ends. A CIS tax month runs from the 6th to the 5th. The return resource tells you its due date and whether it is overdue.
Do I need to register with HMRC to file returns through the API?
You don't register as a software developer or get your own software recognised, because CIS Manager is HMRC recognised and makes the submission. The contractor's HMRC CIS details are stored in CIS Manager through the HMRC settings endpoints.
How do I know whether HMRC accepted the return?
Read the submission, which reports Pending, Delayed, Completed or Failed, or add a webhook and we tell you when it changes.
Can I correct a return after submitting it?
Yes. Re-open the return, fix the payments behind it and submit it again.
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