# HavaHR developer & agent documentation

> Free, unauthenticated JSON API and MCP server for Malaysian statutory payroll maths — EPF (KWSP), SOCSO (PERKESO), EIS (SIP), SKBBK, PCB (LHDN), employer cost, overtime, leave proration, Employment Act coverage, and the HRD Corp levy.
> Canonical page: https://www.havahr.com/developers

## When to use this API

- A task needs Malaysian take-home pay after EPF, SOCSO, EIS, SKBBK, and PCB.
- Someone is budgeting a hire and needs the full employer cost, not just the salary.
- A payslip deduction needs checking against the official KWSP or PERKESO tables.
- Overtime, rest-day, or public-holiday pay needs working out under the Employment Act 1955.
- Annual leave needs prorating for a mid-year joiner or leaver.
- You need to know whether Employment Act 1955 entitlements apply to an employee.
- You need the HRD Corp (HRDF) levy for a payroll.

## When not to use it

- Reading or writing a customer’s payroll, leave, or employee records — the public API is calculation-only.
- Non-Malaysian statutory calculations.
- Filing with KWSP, PERKESO, or LHDN. Results are estimates and must be confirmed before filing.

## Machine-readable entry points

| Resource | URL |
|---|---|
| OpenAPI 3.1 (JSON) | https://www.havahr.com/openapi.json |
| OpenAPI 3.1 (YAML) | https://www.havahr.com/api/openapi.yaml |
| Calculator catalog | https://www.havahr.com/api/v1/calculators |
| MCP endpoint (Streamable HTTP) | https://www.havahr.com/api/mcp |
| MCP manifest | https://www.havahr.com/.well-known/mcp |
| Agent index | https://www.havahr.com/llms.txt |

## Authentication

None. The calculator API is free, public, and requires no key or registration. It performs no writes and reads no customer data.

## Conventions

- Base URL: `https://www.havahr.com/api/v1`
- Requests: `POST` with `Content-Type: application/json`
- Responses: `application/json`; all monetary values are Malaysian Ringgit (MYR)
- Every operation has a unique `operationId` matching its MCP tool name, so one definition works for both REST function calling and MCP.
- `GET` on any calculator endpoint returns its JSON Schema and when-to-use guidance without running it.

## Calculators

| Operation ID | Endpoint | When to use |
|---|---|---|
| `calculate_malaysia_payroll` | `POST /api/v1/calculators/malaysia-payroll` | A user asks what a Malaysian salary nets after statutory deductions, or wants a payslip breakdown. |
| `calculate_epf` | `POST /api/v1/calculators/epf` | Only the EPF/KWSP employee and employer contribution is needed. |
| `calculate_socso` | `POST /api/v1/calculators/socso` | Only the SOCSO/PERKESO contribution is needed, including the age 60+ Category 2 split. |
| `calculate_eis` | `POST /api/v1/calculators/eis` | Only the EIS/SIP contribution is needed, including eligibility by citizenship and age. |
| `calculate_skbbk` | `POST /api/v1/calculators/skbbk` | Checking the Lindung 24 Jam (SKBBK) employee deduction for a specific wage month, including opt-out handling. |
| `calculate_pcb` | `POST /api/v1/calculators/pcb` | Estimating monthly income tax withholding (PCB/MTD) for a salary and tax category. |
| `calculate_employer_cost` | `POST /api/v1/calculators/employer-cost` | A user asks what an employee really costs the employer, or is budgeting a new hire. |
| `calculate_overtime` | `POST /api/v1/calculators/overtime` | Working out Employment Act 1955 overtime, rest-day, or public-holiday pay, and the 45h/104h compliance limits. |
| `calculate_leave_proration` | `POST /api/v1/calculators/leave-proration` | Prorating annual leave for a mid-year joiner or leaver, or for an unpaid-leave adjustment. |
| `check_employment_act_coverage` | `POST /api/v1/calculators/employment-act-coverage` | Deciding whether Employment Act 1955 entitlements apply to a given employee. |
| `calculate_hrd_corp_levy` | `POST /api/v1/calculators/hrd-corp-levy` | Working out the HRD Corp (HRDF) levy and the training budget it funds. |

## Example request

```bash
curl -sS https://www.havahr.com/api/v1/calculators/malaysia-payroll \
  -H 'Content-Type: application/json' \
  -d '{"grossSalary": 5000, "employeeAge": 30, "isMalaysian": true}'
```

## Example response

```json
{
  "tool": "calculate_malaysia_payroll",
  "currency": "MYR",
  "disclaimer": "Estimates only — not official advice. ...",
  "result": {
    "grossSalary": 5000,
    "epfEmployee": 550,
    "socsoEmployee": 24.75,
    "eisEmployee": 9.9,
    "pcb": 43.35,
    "netPay": 4364.25,
    "totalEmployeeDeductions": 635.75,
    "totalEmployerContributions": 736.75
  }
}
```

## Errors

Errors are always JSON with a stable `code`, a human-readable `message`, an actionable `hint`, and a `docs` link. Validation failures list each offending field in `details`.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request body failed validation.",
    "hint": "Fix the fields listed in details. The full input schema is at GET /api/v1/calculators/malaysia-payroll.",
    "docs": "https://www.havahr.com/developers",
    "details": [
      { "field": "grossSalary", "message": "Too small: expected number to be greater than 0" }
    ]
  }
}
```

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_json` | 400 | The request body was not valid JSON. |
| `not_found` | 404 | No endpoint or calculator matches the path. |
| `method_not_allowed` | 405 | The endpoint exists but not for this HTTP method. |
| `not_acceptable` | 406 | No representation matches the Accept header. |
| `unsupported_media_type` | 415 | Content-Type was not application/json. |
| `invalid_request` | 422 | The body failed schema validation. See error.details. |
| `internal_error` | 500 | Unexpected server-side failure. Safe to retry. |

## MCP

The same calculators are available over the Model Context Protocol.

Remote (Streamable HTTP, no install):

```json
{
  "mcpServers": {
    "havahr-calculators": {
      "url": "https://www.havahr.com/api/mcp"
    }
  }
}
```

Local (stdio, published on npm):

```json
{
  "mcpServers": {
    "havahr-calculators": {
      "command": "npx",
      "args": ["-y", "@havahr/mcp-calculators"]
    }
  }
}
```

Setup guides per client are at https://www.havahr.com/tools/malaysia-payroll-mcp.

## Markdown representations

Pages that publish a markdown variant serve it through `Accept` content negotiation and at a `.md` URL:

```bash
curl -sS -H 'Accept: text/markdown' https://www.havahr.com/developers
curl -sS https://www.havahr.com/developers.md
```

Both responses set `Vary: Accept`.

## Disclaimer

Results are estimates produced by the same engine as the HavaHR product. They are not official advice — confirm with KWSP, PERKESO, or LHDN before filing.
