> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hr-easy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The versioned employee-portal contract consumed by the Swiss HR Easy mobile app.

Swiss HR Easy exposes a **versioned contract for the employee self-service portal**.
It is what the iOS app talks to, and it is the supported surface for building against
the platform.

## Scope

The contract covers employee self-service:

| Area           | What it serves                                                       |
| -------------- | -------------------------------------------------------------------- |
| `profile`      | The caller's profile overview and entitlements.                      |
| `leave`        | Leave balances and requests.                                         |
| `time`         | Time entries and weekly summaries.                                   |
| `sick-leave`   | Sick-leave reports, summaries and certificates.                      |
| `payslips`     | Payslips and deduction breakdowns.                                   |
| `compensation` | The caller's compensation role, salary band and placement rationale. |
| `auth`         | Current-session retrieval and logout.                                |

Every endpoint is **self-scoped**: it serves the caller's own data, resolved from the
session, with no id parameter to swap. There is no HR- or admin-facing public API —
those surfaces are internal to the dashboard.

## Generated, not hand-written

The specification is generated from the same Zod schemas the server validates requests
and responses against. It is regenerated by `npm run gen:openapi` and verified
byte-for-byte in CI, so the published contract cannot drift from the running code.

This is [ADR-009](/development/adr). The mobile app regenerates its Dart client from the
artifact, which is why drift would be a cross-repo breakage rather than a documentation
nit.

<Note>
  Do not hand-edit the specification. A change starts in the Zod schema under
  `src/lib/contracts/portal/`, and the spec follows.
</Note>

## Base URL

Swiss HR Easy is single-tenant, so each customer install serves the contract from its
own host:

```
https://{tenantHost}
```

There is no shared API gateway and no cross-tenant endpoint.

## Getting started

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Sessions, SSO, and why the mobile client is SSO-only.
  </Card>

  <Card title="Conventions" icon="list-check" href="/api-reference/conventions">
    Response envelopes, error shapes, pagination, and idempotency.
  </Card>
</CardGroup>

The endpoint reference is generated from the specification and lives under
**Employee portal API** in this tab.