{"openapi":"3.1.0","info":{"title":"PayrollMath API","version":"0.1.0","description":"US employer-side payroll-tax calculators: the employer FICA match, FUTA at the real standard/effective rate, an honest SUTA placeholder, and a combined employer payroll-cost summary — the employer-cost counterpart to the paycheckmath connector's employee-side withholding.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://payrollmath.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/payrollmath/docs"},"termsOfService":"https://connectorbay.com/payrollmath/terms"},"servers":[{"url":"https://payrollmath.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/payrollmath/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_fica_match":{"post":{"operationId":"employer_fica_match","summary":"Employer's matching Social Security (6.2% up to the annual wage base) and Medicare (1.45%, uncapped)","description":"Employer's matching Social Security (6.2% up to the annual wage base) and Medicare (1.45%, uncapped)\n    contribution for one paycheck, correctly stopping Social Security once the wage base is reached mid-year.\n    No employer match of the employee-only 0.9% Additional Medicare Tax. Use for \"employer FICA match on a\n    $3,000 paycheck\", \"what's the employer's Social Security cost once an employee crosses the wage base\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"gross_pay":{"description":"This paycheck's gross pay (FICA wages).","minimum":0,"title":"Gross Pay","type":"number"},"ytd_fica_wages_before_this_check":{"default":0.0,"description":"This employee's FICA wages already paid this calendar year, BEFORE this check.","minimum":0,"title":"Ytd Fica Wages Before This Check","type":"number"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"}},"required":["gross_pay"],"title":"employer_fica_matchArguments","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/futa_calculator":{"post":{"operationId":"futa_calculator","summary":"FUTA at the standard 6.0% rate on the first $7,000 of each employee's wages per year, reduced to the","description":"FUTA at the standard 6.0% rate on the first $7,000 of each employee's wages per year, reduced to the\n    effective 0.6% rate by the standard 5.4% credit (or a higher effective rate under a flagged state credit\n    reduction) — wage-base-aware for the $7,000 ceiling. Use for \"FUTA on a new employee's first paycheck\",\n    \"what's the effective FUTA rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"this_period_gross_pay":{"description":"This paycheck's gross pay (FUTA wages).","minimum":0,"title":"This Period Gross Pay","type":"number"},"ytd_futa_taxable_wages_before_this_check":{"default":0.0,"description":"This employee's FUTA-taxable wages already paid this calendar year, BEFORE this check.","minimum":0,"title":"Ytd Futa Taxable Wages Before This Check","type":"number"},"state_has_credit_reduction":{"default":false,"description":"True if your state is under a FUTA credit reduction for the year.","title":"State Has Credit Reduction","type":"boolean"},"additional_credit_reduction_pct":{"default":0.0,"description":"The state's additional credit-reduction percentage, if state_has_credit_reduction is True (from Form 940 Schedule A).","minimum":0,"title":"Additional Credit Reduction Pct","type":"number"}},"required":["this_period_gross_pay"],"title":"futa_calculatorArguments","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/suta_placeholder":{"post":{"operationId":"suta_placeholder","summary":"An HONEST placeholder for State Unemployment Insurance (SUTA) — explains why it cannot be computed","description":"An HONEST placeholder for State Unemployment Insurance (SUTA) — explains why it cannot be computed\n    generically (state-specific wage base and rate, plus the employer's own experience rating) and points you\n    to your state's actual rate notice. Use for \"how much is SUTA\", \"what's my state unemployment rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A US state name, if you want the reminder to name it back — this tool does not have state-specific SUTA rate tables loaded.","title":"State"}},"title":"suta_placeholderArguments","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_payroll_cost_summary":{"post":{"operationId":"employer_payroll_cost_summary","summary":"Combines the employer FICA match and FUTA into one per-paycheck employer-cost figure on top of gross","description":"Combines the employer FICA match and FUTA into one per-paycheck employer-cost figure on top of gross\n    pay (SUTA flagged, not included — call suta_placeholder separately). Use for \"what does an employer\n    actually pay on top of a $60,000 salary\", \"total employer payroll tax cost per paycheck\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"gross_pay":{"description":"This paycheck's gross pay.","minimum":0,"title":"Gross Pay","type":"number"},"ytd_fica_wages_before_this_check":{"default":0.0,"minimum":0,"title":"Ytd Fica Wages Before This Check","type":"number"},"ytd_futa_taxable_wages_before_this_check":{"default":0.0,"minimum":0,"title":"Ytd Futa Taxable Wages Before This Check","type":"number"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"},"state_has_credit_reduction":{"default":false,"title":"State Has Credit Reduction","type":"boolean"},"additional_credit_reduction_pct":{"default":0.0,"minimum":0,"title":"Additional Credit Reduction Pct","type":"number"}},"required":["gross_pay"],"title":"employer_payroll_cost_summaryArguments","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/payroll_glossary":{"post":{"operationId":"payroll_glossary","summary":"Definitions of employer-side payroll-tax terms (employer FICA match, FUTA, SUTA, wage base, experience","description":"Definitions of employer-side payroll-tax terms (employer FICA match, FUTA, SUTA, wage base, experience\n    rating, new employer rate, credit reduction state, Form 940, Form 941, EFTPS, labor burden rate, ...). Use\n    for \"what's a credit reduction state\", \"what's a labor burden rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"payroll_glossaryArguments","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}}}}