{"openapi":"3.1.0","info":{"title":"UK Payroll Cost Calculator API","version":"0.1.0","description":"UK Payroll Cost Calculator turns the 2026-27 GOV.UK employer rates into exact numbers a small business can plan with. employer_ni and employee_ni compute Class 1 National Insurance for a weekly, monthly or annual pay period and show every band, including the zero-rate reliefs for apprentices under 25 (category H) and employees under 21 (category M). employment_allowance_offset applies the GBP...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://uk-payroll-costs.connectorbay.com/mcp.\n\nDisclaimer: General information only, not legal, tax, accounting or payment advice. UK Payroll Cost Calculator is an independent tool: it is not affiliated with, endorsed by or operated by any government body, central bank, standards body or scheme operator. Rates, thresholds and rules change; check the cited official source and confirm with a qualified professional before you rely on a result.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/uk-payroll-costs/docs"},"termsOfService":"https://connectorbay.com/uk-payroll-costs/terms"},"servers":[{"url":"https://uk-payroll-costs.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/uk-payroll-costs/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/employer_ni":{"post":{"operationId":"employer_ni","summary":"Employer Class 1 National Insurance on one pay period at 15% above the secondary threshold (0% up to the upper secondary","description":"Employer Class 1 National Insurance on one pay period at 15% above the secondary threshold (0% up to the upper secondary threshold for categories H and M). Use for \"What employer National Insurance do I pay on GBP 3,000 of monthly pay?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pay":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Plain decimal amount in GBP such as 3000.00 (digits and one '.'; no commas or currency symbols)","title":"Pay"},"period":{"description":"Earnings period: weekly, monthly or annual (the periods GOV.UK publishes thresholds for)","title":"Period","type":"string"},"category":{"default":"A","description":"NIC category letter: A (default), B, C, H (apprentice under 25), J or M (under 21)","title":"Category","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"required":["pay","period"],"title":"employer_niArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/employee_ni":{"post":{"operationId":"employee_ni","summary":"Employee Class 1 National Insurance on one pay period: 8% between the primary threshold and the upper earnings limit, 2%","description":"Employee Class 1 National Insurance on one pay period: 8% between the primary threshold and the upper earnings limit, 2% above (category A). Use for \"How much National Insurance is taken from an employee paid GBP 3,000 a month?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pay":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Plain decimal amount in GBP such as 3000.00 (digits and one '.'; no commas or currency symbols)","title":"Pay"},"period":{"description":"Earnings period: weekly, monthly or annual (the periods GOV.UK publishes thresholds for)","title":"Period","type":"string"},"category":{"default":"A","description":"NIC category letter: A (default), B, C, H (apprentice under 25), J or M (under 21)","title":"Category","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"required":["pay","period"],"title":"employee_niArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/employment_allowance_offset":{"post":{"operationId":"employment_allowance_offset","summary":"Apply the Employment Allowance (up to GBP 10,500 in the tax year) against an employer Class 1 NIC liability and show the","description":"Apply the Employment Allowance (up to GBP 10,500 in the tax year) against an employer Class 1 NIC liability and show the wording of the eligibility rules. Use for \"My employer NIC bill for the year is GBP 14,000: how much does the Employment Allowance take off?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"employer_nic_due":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Plain decimal amount in GBP such as 3000.00 (digits and one '.'; no commas or currency symbols)","title":"Employer Nic Due"},"allowance_already_used":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"default":"0","description":"Plain decimal amount in GBP such as 3000.00 (digits and one '.'; no commas or currency symbols)","title":"Allowance Already Used"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"required":["employer_nic_due"],"title":"employment_allowance_offsetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/ni_thresholds_for_period":{"post":{"operationId":"ni_thresholds_for_period","summary":"Class 1 National Insurance thresholds (lower earnings limit, primary, secondary, upper secondary, upper earnings limit) ","description":"Class 1 National Insurance thresholds (lower earnings limit, primary, secondary, upper secondary, upper earnings limit) and rates for a weekly, monthly or annual period. Use for \"What are the monthly National Insurance thresholds this tax year?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"period":{"default":"all","description":"weekly, monthly, annual or all (default all)","title":"Period","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"title":"ni_thresholds_for_periodArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/nmw_check":{"post":{"operationId":"nmw_check","summary":"Compare an hourly rate, or a salary and weekly hours, with the National Minimum or Living Wage for the worker's age and ","description":"Compare an hourly rate, or a salary and weekly hours, with the National Minimum or Living Wage for the worker's age and apprentice status on a date. Use for \"Is GBP 11.50 an hour enough for a 22 year old?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"age":{"description":"Worker's age in whole years on the date checked","maximum":120,"minimum":16,"title":"Age","type":"integer"},"hourly_rate":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"description":"Hourly pay in GBP as a plain decimal such as 11.50. Give this, or annual_salary with weekly_hours","title":"Hourly Rate"},"annual_salary":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"description":"Gross annual salary in GBP, used with weekly_hours when no hourly_rate is given","title":"Annual Salary"},"weekly_hours":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"description":"Basic hours worked each week (more than 0, at most 168), used with annual_salary","title":"Weekly Hours"},"apprentice":{"default":false,"description":"True if the worker is employed as an apprentice","title":"Apprentice","type":"boolean"},"apprenticeship_first_year":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"For an apprentice aged 19 or over: true in the first year of the apprenticeship, false after it (required in that case)","title":"Apprenticeship First Year"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"required":["age"],"title":"nmw_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/apprenticeship_levy":{"post":{"operationId":"apprenticeship_levy","summary":"Apprenticeship Levy: 0.5% of the annual pay bill less the GBP 15,000 annual allowance. Use for \"What apprenticeship levy","description":"Apprenticeship Levy: 0.5% of the annual pay bill less the GBP 15,000 annual allowance. Use for \"What apprenticeship levy applies to a GBP 4,000,000 annual pay bill?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"annual_pay_bill":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Plain decimal amount in GBP such as 3000.00 (digits and one '.'; no commas or currency symbols)","title":"Annual Pay Bill"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"required":["annual_pay_bill"],"title":"apprenticeship_levyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/employer_cost_of_hire":{"post":{"operationId":"employer_cost_of_hire","summary":"Annual cost of employing someone: salary plus employer National Insurance (less any Employment Allowance you have left) ","description":"Annual cost of employing someone: salary plus employer National Insurance (less any Employment Allowance you have left) plus the employer pension contribution on qualifying earnings. Use for \"What does a GBP 32,000 employee really cost me a year?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"annual_salary":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Plain decimal amount in GBP such as 3000.00 (digits and one '.'; no commas or currency symbols)","title":"Annual Salary"},"pay_frequency":{"default":"monthly","description":"monthly (default, salary divided by 12) or weekly (salary divided by 52): sets the NIC period used","title":"Pay Frequency","type":"string"},"category":{"default":"A","description":"NIC category letter: A (default), B, C, H (apprentice under 25), J or M (under 21)","title":"Category","type":"string"},"pension_applies":{"default":true,"description":"True if the worker is in a workplace pension with an employer contribution on qualifying earnings (default true)","title":"Pension Applies","type":"boolean"},"employer_pension_percent":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"default":"3","description":"Employer contribution as a percentage of qualifying earnings (default 3, the statutory minimum on that basis)","title":"Employer Pension Percent"},"employment_allowance_remaining":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"default":"0","description":"Employment Allowance still unused this tax year, netted off employer NIC (default 0)","title":"Employment Allowance Remaining"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"required":["annual_salary"],"title":"employer_cost_of_hireArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/rates_reference":{"post":{"operationId":"rates_reference","summary":"Every rate, threshold and allowance this connector uses, with source URL, tax year and verification level. Use for \"Whic","description":"Every rate, threshold and allowance this connector uses, with source URL, tax year and verification level. Use for \"Which sources and tax year do your payroll figures come from?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"default":"all","description":"all (default), ni, nmw, employment_allowance, apprenticeship_levy or pension_band","title":"Topic","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the rules apply on, YYYY-MM-DD (default today). Must fall inside the loaded tax year 2026-27 (6 April 2026 to 5 April 2027)","title":"On Date"}},"title":"rates_referenceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}