{"openapi":"3.1.0","info":{"title":"South Africa Payroll Deadline Calendar API","version":"0.1.0","description":"South Africa Payroll Deadline Calendar tells an employer what is owed to SARS and when, built for a Monday-morning what-is-due check. next_emp201_due applies the SARS rule (EMP201 paid within seven days after the end of the month of deduction, moved to the last business day before a weekend or public holiday) to a deduction month or finds the next one due. due_in_next_days lists every EMP201 date...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://za-emp201-calendar.connectorbay.com/mcp.\n\nDisclaimer: General information only, not legal, tax, accounting or payment advice. South Africa Payroll Deadline Calendar 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/za-emp201-calendar/docs"},"termsOfService":"https://connectorbay.com/za-emp201-calendar/terms"},"servers":[{"url":"https://za-emp201-calendar.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/za-emp201-calendar/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/next_emp201_due":{"post":{"operationId":"next_emp201_due","summary":"Return the EMP201 declaration and payment date (seven days after month end, moved to the last business day before a week","description":"Return the EMP201 declaration and payment date (seven days after month end, moved to the last business day before a weekend or public holiday) for a month, or the next one due. Use for \"When is my EMP201 for September 2026 due?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the question is asked from, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"},"deduction_month":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Month in which the PAYE, UIF and SDL were deducted, YYYY-MM. Leave out to get the next due date on or after on_date.","title":"Deduction Month"},"extra_holidays":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Optional one-off public holidays proclaimed for the period (for example an election day), each YYYY-MM-DD; treated like the statutory holidays.","title":"Extra Holidays"}},"title":"next_emp201_dueArguments","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/emp501_windows":{"post":{"operationId":"emp501_windows","summary":"Return the EMP501 interim and annual reconciliation submission windows for a reconciliation year with their status on th","description":"Return the EMP501 interim and annual reconciliation submission windows for a reconciliation year with their status on the date asked. Use for \"When does the interim EMP501 reconciliation window open and close, and is it open today?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tax_year":{"default":2027,"description":"Reconciliation year as SARS labels it: the calendar year in which it ends (2027 = 1 March 2026 to 28 February 2027). Only 2026 and 2027 are loaded. Default 2027.","maximum":2027,"minimum":2026,"title":"Tax Year","type":"integer"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the question is asked from, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"}},"title":"emp501_windowsArguments","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/emp501_penalty_estimate":{"post":{"operationId":"emp501_penalty_estimate","summary":"Estimate the late-EMP501 administrative penalty: 1% of annual PAYE liability, plus 1% for every month outstanding, cappe","description":"Estimate the late-EMP501 administrative penalty: 1% of annual PAYE liability, plus 1% for every month outstanding, capped at 10%, with the full ladder. Use for \"My annual PAYE liability is R240,000 and the EMP501 is two months late: what penalty does the SARS rule give?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"annual_paye_liability":{"description":"The employer's annual PAYE liability in rand as a plain decimal string such as 240000.00.","title":"Annual Paye Liability","type":"string"},"months_late":{"default":0,"description":"Whole months the EMP501 has been outstanding after its due date; 0 = submitted late within the first month. Default 0.","maximum":120,"minimum":0,"title":"Months Late","type":"integer"}},"required":["annual_paye_liability"],"title":"emp501_penalty_estimateArguments","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/due_in_next_days":{"post":{"operationId":"due_in_next_days","summary":"List every employer payroll deadline falling from the date asked up to N days ahead: EMP201 dates and the opening and cl","description":"List every employer payroll deadline falling from the date asked up to N days ahead: EMP201 dates and the opening and closing days of the EMP501 windows. Use for \"What payroll deadlines fall in the next 14 days?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"days":{"default":14,"description":"Look-ahead in days, 1 to 366. Default 14.","maximum":366,"minimum":1,"title":"Days","type":"integer"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the question is asked from, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"},"extra_holidays":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Optional one-off public holidays proclaimed for the period (for example an election day), each YYYY-MM-DD; treated like the statutory holidays.","title":"Extra Holidays"}},"title":"due_in_next_daysArguments","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/sdl_liability_check":{"post":{"operationId":"sdl_liability_check","summary":"Check whether expected payroll is more than R500,000 over the next 12 months (the SDL liability test) and return the 1% ","description":"Check whether expected payroll is more than R500,000 over the next 12 months (the SDL liability test) and return the 1% Skills Development Levy amount. Use for \"I expect to pay R620,000 in salaries over the next 12 months: do I have to pay SDL and how much per month?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"expected_annual_leviable_payroll":{"description":"Total salaries the employer expects to pay over the next 12 months in rand (wages, overtime, leave pay, bonuses, fees, commissions, lump sums), as a plain decimal string.","title":"Expected Annual Leviable Payroll","type":"string"},"monthly_leviable_remuneration":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional leviable remuneration paid in the month in rand; the 1% amount for the month is returned when the employer is liable.","title":"Monthly Leviable Remuneration"}},"required":["expected_annual_leviable_payroll"],"title":"sdl_liability_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/public_holiday_adjust":{"post":{"operationId":"public_holiday_adjust","summary":"Move a due date to the last business day on or before it, skipping weekends and South African public holidays, and say w","description":"Move a due date to the last business day on or before it, skipping weekends and South African public holidays, and say which days were skipped and why. Use for \"7 November 2026 is a Saturday: which day counts as the last business day before it?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"due_date":{"description":"A due date, YYYY-MM-DD (for example the 7th of the month).","title":"Due Date","type":"string"},"extra_holidays":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Optional one-off public holidays proclaimed for the period (for example an election day), each YYYY-MM-DD; treated like the statutory holidays.","title":"Extra Holidays"}},"required":["due_date"],"title":"public_holiday_adjustArguments","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/sa_public_holidays":{"post":{"operationId":"sa_public_holidays","summary":"List the South African public holidays of a year: fixed dates, Good Friday and Family Day from Easter, and the Monday ob","description":"List the South African public holidays of a year: fixed dates, Good Friday and Family Day from Easter, and the Monday observed when a holiday falls on a Sunday. Use for \"Which South African public holidays fall in 2026 and on which weekdays?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"description":"Calendar year, 2015 to 2100.","maximum":2100,"minimum":2015,"title":"Year","type":"integer"},"extra_holidays":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Optional one-off public holidays proclaimed for the period (for example an election day), each YYYY-MM-DD; treated like the statutory holidays.","title":"Extra Holidays"}},"required":["year"],"title":"sa_public_holidaysArguments","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}}}}