{"openapi":"3.1.0","info":{"title":"0s and 1s CIS API","version":"1.0.0","description":"Free, read-only calculators for the UK Construction Industry Scheme (CIS): deductions, gross up, tax months and deadlines, late filing penalties, the gross payment status turnover test, verification and nil returns. No key and no sign-in. Up to 60 requests a minute from one address. The same tools are served over MCP at https://0sand1s.co.uk/mcp. Answers are worked out from the rules as published; they are not tax advice and do not come from HMRC.","contact":{"url":"https://0sand1s.co.uk/developers"}},"servers":[{"url":"https://0sand1s.co.uk"}],"externalDocs":{"url":"https://0sand1s.co.uk/developers","description":"How to use the API and the MCP server"},"paths":{"/api/v1/deduction":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_deduction_get","summary":"CIS deduction, gross to net","description":"Works out the CIS deduction on a payment to a subcontractor, from the gross bill to the net payment. Takes the gross including VAT, the VAT, the subcontractor's materials and the rate (0, 20 or 30). VAT is never taxed under CIS and materials come off before the rate applies; the deduction is rounded down to the penny. Returns each step of the working, money in pence and pounds. Does not cover retentions, or decide which rate applies (verify the subcontractor with HMRC for that).","parameters":[{"name":"gross","in":"query","required":true,"description":"The amount being paid, including any VAT, before the CIS deduction. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"1,200.00"},{"name":"vat","in":"query","required":false,"description":"The VAT within the gross. Leave out or 0 under the domestic reverse charge. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"200.00"},{"name":"materials","in":"query","required":false,"description":"What the subcontractor paid for materials, plant hire, consumables and fuel (not travel) on the job. Without VAT if the subcontractor is VAT registered, with it if not. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"300.00"},{"name":"rate","in":"query","required":true,"description":"The subcontractor's CIS rate in per cent: 20 if registered, 30 if not registered or unmatched when verified, 0 for gross payment status","schema":{"type":"integer","enum":[0,20,30]},"example":"20"}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_deduction_post","summary":"CIS deduction, gross to net","description":"Works out the CIS deduction on a payment to a subcontractor, from the gross bill to the net payment. Takes the gross including VAT, the VAT, the subcontractor's materials and the rate (0, 20 or 30). VAT is never taxed under CIS and materials come off before the rate applies; the deduction is rounded down to the penny. Returns each step of the working, money in pence and pounds. Does not cover retentions, or decide which rate applies (verify the subcontractor with HMRC for that). The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gross":{"description":"The amount being paid, including any VAT, before the CIS deduction. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"},"vat":{"description":"The VAT within the gross. Leave out or 0 under the domestic reverse charge. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"},"materials":{"description":"What the subcontractor paid for materials, plant hire, consumables and fuel (not travel) on the job. Without VAT if the subcontractor is VAT registered, with it if not. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"},"rate":{"type":"integer","enum":[0,20,30],"description":"The subcontractor's CIS rate in per cent: 20 if registered, 30 if not registered or unmatched when verified, 0 for gross payment status"}},"required":["gross","rate"]},"example":{"gross":"1,200.00","vat":"200.00","materials":"300.00","rate":20}}}}}},"/api/v1/gross-up":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_gross_up_get","summary":"CIS gross up, net to gross","description":"Finds the gross amount (excluding VAT) that leaves a given net payment after the CIS deduction, for a subcontractor quoted a take-home figure. Takes the net, the subcontractor's materials and the rate (0, 20 or 30). Where rounding lets two grosses give the same net, the larger is returned so CIS is never under-deducted. Returns the forward working on that gross, money in pence and pounds. VAT is not included; add it on top if the subcontractor charges it.","parameters":[{"name":"net","in":"query","required":true,"description":"The payment the subcontractor should receive after the CIS deduction, excluding VAT. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"860.00"},{"name":"materials","in":"query","required":false,"description":"The subcontractor's materials within the payment, as for cis_deduction. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"300.00"},{"name":"rate","in":"query","required":true,"description":"The subcontractor's CIS rate in per cent: 20 if registered, 30 if not registered or unmatched when verified, 0 for gross payment status","schema":{"type":"integer","enum":[0,20,30]},"example":"20"}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_gross_up_post","summary":"CIS gross up, net to gross","description":"Finds the gross amount (excluding VAT) that leaves a given net payment after the CIS deduction, for a subcontractor quoted a take-home figure. Takes the net, the subcontractor's materials and the rate (0, 20 or 30). Where rounding lets two grosses give the same net, the larger is returned so CIS is never under-deducted. Returns the forward working on that gross, money in pence and pounds. VAT is not included; add it on top if the subcontractor charges it. The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"net":{"description":"The payment the subcontractor should receive after the CIS deduction, excluding VAT. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"},"materials":{"description":"The subcontractor's materials within the payment, as for cis_deduction. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"},"rate":{"type":"integer","enum":[0,20,30],"description":"The subcontractor's CIS rate in per cent: 20 if registered, 30 if not registered or unmatched when verified, 0 for gross payment status"}},"required":["net","rate"]},"example":{"net":"860.00","materials":"300.00","rate":20}}}}}},"/api/v1/tax-month":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_tax_month_get","summary":"CIS tax month and deadlines","description":"For a date, gives the CIS tax month it falls in (the 6th to the 5th), the tax year, the date the monthly return (CIS300) is due (the 19th, also the date for paying HMRC by any means other than electronically), and the date for paying HMRC electronically (the 22nd, moved back to the banking day before when the 22nd is a weekend or an England and Wales bank holiday). Bank holidays are known to bank_holidays_known_until; after that only weekends move the date.","parameters":[{"name":"date","in":"query","required":true,"description":"Any date, such as a payment date or today, YYYY-MM-DD","schema":{"type":"string"},"example":"2026-10-18"}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_tax_month_post","summary":"CIS tax month and deadlines","description":"For a date, gives the CIS tax month it falls in (the 6th to the 5th), the tax year, the date the monthly return (CIS300) is due (the 19th, also the date for paying HMRC by any means other than electronically), and the date for paying HMRC electronically (the 22nd, moved back to the banking day before when the 22nd is a weekend or an England and Wales bank holiday). Bank holidays are known to bank_holidays_known_until; after that only weekends move the date. The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","description":"Any date, such as a payment date or today, YYYY-MM-DD"}},"required":["date"]},"example":{"date":"2026-10-18"}}}}}},"/api/v1/late-penalties":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_late_penalties_get","summary":"CIS late filing penalties","description":"Works out the late filing penalties on one monthly CIS return under Finance Act 2009 Schedule 55: £100 the day after the 19th, £200 at 2 months, then the greater of £300 and 5% of the deductions at 6 and at 12 months (5% alone for a first return). Takes the tax year and month, the filing date or none, today's date, the deductions and whether a return had been filed before. Returns each penalty with its date and whether it is charged, avoided or still to come. Does not cover deliberate withholding, interest on late payment, or appeals.","parameters":[{"name":"tax_year","in":"query","required":true,"description":"The tax year, by the calendar year it starts in: 2026 for 6 April 2026 to 5 April 2027","schema":{"type":"integer"},"example":"2026"},{"name":"tax_month","in":"query","required":true,"description":"The tax month, 1 to 12: 1 is 6 April to 5 May, 12 is 6 March to 5 April","schema":{"type":"integer"},"example":"3"},{"name":"filed_on","in":"query","required":false,"description":"The day the return was filed. Leave out or null if it has not been filed, YYYY-MM-DD","schema":{"type":"string"},"example":"2026-09-24"},{"name":"as_at","in":"query","required":true,"description":"Today's date. Penalties on a return not yet filed run to this date, YYYY-MM-DD","schema":{"type":"string"},"example":"2026-10-18"},{"name":"deductions","in":"query","required":false,"description":"The CIS deductions the return shows, or would show. Leave out or 0 for a nil return. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"2,400.00"},{"name":"filed_before","in":"query","required":false,"description":"true if the contractor had already filed a CIS return before this one was due (the usual case). false for the first return, which has no £300 minimum","schema":{"type":"boolean"},"example":"true"}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_late_penalties_post","summary":"CIS late filing penalties","description":"Works out the late filing penalties on one monthly CIS return under Finance Act 2009 Schedule 55: £100 the day after the 19th, £200 at 2 months, then the greater of £300 and 5% of the deductions at 6 and at 12 months (5% alone for a first return). Takes the tax year and month, the filing date or none, today's date, the deductions and whether a return had been filed before. Returns each penalty with its date and whether it is charged, avoided or still to come. Does not cover deliberate withholding, interest on late payment, or appeals. The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"description":"The tax year, by the calendar year it starts in: 2026 for 6 April 2026 to 5 April 2027","type":"integer"},"tax_month":{"description":"The tax month, 1 to 12: 1 is 6 April to 5 May, 12 is 6 March to 5 April","type":"integer"},"filed_on":{"description":"The day the return was filed. Leave out or null if it has not been filed, YYYY-MM-DD","type":"string"},"as_at":{"type":"string","description":"Today's date. Penalties on a return not yet filed run to this date, YYYY-MM-DD"},"deductions":{"description":"The CIS deductions the return shows, or would show. Leave out or 0 for a nil return. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"},"filed_before":{"type":"boolean","description":"true if the contractor had already filed a CIS return before this one was due (the usual case). false for the first return, which has no £300 minimum"}},"required":["tax_year","tax_month","as_at"]},"example":{"tax_year":2026,"tax_month":3,"filed_on":"2026-09-24","as_at":"2026-10-18","deductions":"2,400.00","filed_before":true}}}}}},"/api/v1/gross-payment-turnover-test":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_gross_payment_turnover_test_get","summary":"CIS gross payment status turnover test","description":"Checks the turnover test for CIS gross payment status (Finance Act 2004 Schedule 11, SI 2005/2045 reg 28): £30,000 net construction turnover for a sole trader; for a partnership or company, the lower of £30,000 for each partner or relevant person and £100,000. In a close company, shareholders count as well as directors. Returns the figure needed by each route, which one applies, and how far short. Covers the turnover test only, not the business test or the compliance test.","parameters":[{"name":"business_type","in":"query","required":true,"description":"The subcontractor's business: sole-trader, partnership or company","schema":{"type":"string","enum":["sole-trader","partnership","company"]},"example":"company"},{"name":"partners","in":"query","required":false,"description":"Partnership only: the number of partners, the highest at any one time in the 12 months","schema":{"type":"integer"}},{"name":"directors","in":"query","required":false,"description":"Company only: the number of directors, the highest at any one time in the 12 months","schema":{"type":"integer"},"example":"2"},{"name":"close_company","in":"query","required":false,"description":"Company only: true if it is a close company (controlled by 5 or fewer people, or by its directors)","schema":{"type":"boolean"},"example":"true"},{"name":"shareholders","in":"query","required":false,"description":"Close company only: shareholders who are not also directors, each counted once","schema":{"type":"integer"},"example":"1"},{"name":"net_turnover","in":"query","required":true,"description":"Construction turnover for the last 12 months, less VAT and the cost of materials. Pounds, as a string like \"1,200.00\" or a number like 1200.","schema":{"type":"string"},"example":"95,000.00"}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_gross_payment_turnover_test_post","summary":"CIS gross payment status turnover test","description":"Checks the turnover test for CIS gross payment status (Finance Act 2004 Schedule 11, SI 2005/2045 reg 28): £30,000 net construction turnover for a sole trader; for a partnership or company, the lower of £30,000 for each partner or relevant person and £100,000. In a close company, shareholders count as well as directors. Returns the figure needed by each route, which one applies, and how far short. Covers the turnover test only, not the business test or the compliance test. The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_type":{"type":"string","enum":["sole-trader","partnership","company"],"description":"The subcontractor's business: sole-trader, partnership or company"},"partners":{"description":"Partnership only: the number of partners, the highest at any one time in the 12 months","type":"integer"},"directors":{"description":"Company only: the number of directors, the highest at any one time in the 12 months","type":"integer"},"close_company":{"type":"boolean","description":"Company only: true if it is a close company (controlled by 5 or fewer people, or by its directors)"},"shareholders":{"description":"Close company only: shareholders who are not also directors, each counted once","type":"integer"},"net_turnover":{"description":"Construction turnover for the last 12 months, less VAT and the cost of materials. Pounds, as a string like \"1,200.00\" or a number like 1200.","type":"string"}},"required":["business_type","net_turnover"]},"example":{"business_type":"company","directors":2,"close_company":true,"shareholders":1,"net_turnover":"95,000.00"}}}}}},"/api/v1/needs-verification":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_needs_verification_get","summary":"Does a CIS subcontractor need verifying?","description":"Says whether a contractor must verify a subcontractor with HMRC before paying them (SI 2005/2045 reg 6): not needed if the subcontractor was on one of this contractor's CIS returns, or was verified by this contractor, in the tax year of the payment or the two before. Takes the payment date, the tax years the subcontractor was on a return and the last verification date, all supplied by the caller. Does not contact HMRC or verify anyone, and does not cover group companies or business transfers.","parameters":[{"name":"payment_date","in":"query","required":true,"description":"The date of the payment about to be made, YYYY-MM-DD","schema":{"type":"string"},"example":"2026-10-18"},{"name":"included_on_return_in_tax_years","in":"query","required":false,"description":"Tax years (by the year each starts in) in which this contractor included the subcontractor on a CIS return. An array, or comma-separated like \"2025,2026\"","schema":{"type":"array","items":{"type":"integer"}},"example":"2023"},{"name":"last_verified_on","in":"query","required":false,"description":"The date this contractor last verified the subcontractor with HMRC, if ever, YYYY-MM-DD","schema":{"type":"string"}}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_needs_verification_post","summary":"Does a CIS subcontractor need verifying?","description":"Says whether a contractor must verify a subcontractor with HMRC before paying them (SI 2005/2045 reg 6): not needed if the subcontractor was on one of this contractor's CIS returns, or was verified by this contractor, in the tax year of the payment or the two before. Takes the payment date, the tax years the subcontractor was on a return and the last verification date, all supplied by the caller. Does not contact HMRC or verify anyone, and does not cover group companies or business transfers. The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_date":{"type":"string","description":"The date of the payment about to be made, YYYY-MM-DD"},"included_on_return_in_tax_years":{"type":"array","items":{"type":"integer"},"description":"Tax years (by the year each starts in) in which this contractor included the subcontractor on a CIS return. An array, or comma-separated like \"2025,2026\""},"last_verified_on":{"description":"The date this contractor last verified the subcontractor with HMRC, if ever, YYYY-MM-DD","type":"string"}},"required":["payment_date"]},"example":{"payment_date":"2026-10-18","included_on_return_in_tax_years":[2023],"last_verified_on":null}}}}}},"/api/v1/nil-return-check":{"get":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_nil_return_check_get","summary":"Is a CIS nil return due?","description":"Says whether a contractor must file a CIS nil return for a tax month (SI 2005/2045 reg 4(9A) and (9B), inserted by SI 2026/289 from 6 April 2026): due when a mainstream contractor that has paid subcontractors before pays none that month, unless it told HMRC no later than 14 days before the month started. Takes the tax year and month and yes or no answers. Returns whether a nil return is due, why, and the date it is due. Does not file anything.","parameters":[{"name":"tax_year","in":"query","required":true,"description":"The tax year, by the calendar year it starts in: 2026 for 6 April 2026 to 5 April 2027","schema":{"type":"integer"},"example":"2026"},{"name":"tax_month","in":"query","required":true,"description":"The tax month, 1 to 12: 1 is 6 April to 5 May, 12 is 6 March to 5 April","schema":{"type":"integer"},"example":"6"},{"name":"paid_subcontractors_in_month","in":"query","required":true,"description":"true if any subcontractor was paid in that tax month, gross payments included","schema":{"type":"boolean"},"example":"false"},{"name":"paid_subcontractors_before","in":"query","required":true,"description":"true if the contractor had paid any subcontractor before that tax month started","schema":{"type":"boolean"},"example":"true"},{"name":"mainstream_contractor","in":"query","required":false,"description":"true for a mainstream contractor (a construction business). false for a deemed contractor, which is outside the nil return rule","schema":{"type":"boolean"}},{"name":"told_hmrc_no_payments_on","in":"query","required":false,"description":"If the contractor told HMRC in advance that no payments would be made in that month, the date it did so. Leave out if not, YYYY-MM-DD","schema":{"type":"string"}}]},"post":{"tags":["CIS"],"responses":{"200":{"description":"The answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResponse"}}}},"400":{"description":"Input that could not be used, with a message per field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one address","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cis_nil_return_check_post","summary":"Is a CIS nil return due?","description":"Says whether a contractor must file a CIS nil return for a tax month (SI 2005/2045 reg 4(9A) and (9B), inserted by SI 2026/289 from 6 April 2026): due when a mainstream contractor that has paid subcontractors before pays none that month, unless it told HMRC no later than 14 days before the month started. Takes the tax year and month and yes or no answers. Returns whether a nil return is due, why, and the date it is due. Does not file anything. The same as the GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"description":"The tax year, by the calendar year it starts in: 2026 for 6 April 2026 to 5 April 2027","type":"integer"},"tax_month":{"description":"The tax month, 1 to 12: 1 is 6 April to 5 May, 12 is 6 March to 5 April","type":"integer"},"paid_subcontractors_in_month":{"type":"boolean","description":"true if any subcontractor was paid in that tax month, gross payments included"},"paid_subcontractors_before":{"type":"boolean","description":"true if the contractor had paid any subcontractor before that tax month started"},"mainstream_contractor":{"type":"boolean","description":"true for a mainstream contractor (a construction business). false for a deemed contractor, which is outside the nil return rule"},"told_hmrc_no_payments_on":{"description":"If the contractor told HMRC in advance that no payments would be made in that month, the date it did so. Leave out if not, YYYY-MM-DD","type":"string"}},"required":["tax_year","tax_month","paid_subcontractors_in_month","paid_subcontractors_before"]},"example":{"tax_year":2026,"tax_month":6,"paid_subcontractors_in_month":false,"paid_subcontractors_before":true}}}}}}},"components":{"schemas":{"ToolResponse":{"type":"object","properties":{"tool":{"type":"string"},"result":{"type":"object","description":"The answer. Amounts are { pence, pounds } objects; dates are YYYY-MM-DD."},"summary":{"type":"string","description":"The answer in one line"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"see_also":{"type":"string","format":"uri","description":"The page on 0sand1s.co.uk that does the same sum or explains the rule"}},"required":["tool","result","summary","sources","see_also"]},"Error":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_input","unknown_tool","rate_limited"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"One message per input field that could not be used"}},"required":["error","message"]},"Money":{"type":"object","properties":{"pence":{"type":"integer"},"pounds":{"type":"string","examples":["£1,200.00"]}},"required":["pence","pounds"]}}}}