# Workant Open API

> A read-only REST API for pulling your own Workant HR data into your own applications. Authenticate with an API key sent as a bearer token; every response is scoped to your company.

The machine-readable OpenAPI 3.1 spec is the source of truth — prefer it over this summary.

## Specification
- [OpenAPI 3.1 spec](https://developers.workant.io/openapi.json): the complete, machine-readable definition of every endpoint, schema, parameter, and error. Point codegen, API clients, and AI tooling here.

## Essentials
- Base URL: `https://api.workant.io/public`
- Authentication: send `Authorization: Bearer wk_...`. Keys are created in Workant under Company Settings → Developers. Missing, malformed, or revoked keys return `401`.
- Scope: a key is bound to its company; responses never contain another organization's data.
- Pagination: `?page=` (1-indexed) and `?perPage=` (max 100, default 50). Responses use a `{ data, meta }` envelope; invalid values return `400` (no silent clamping).
- Rate limits: per-company quotas over rolling daily/weekly/monthly windows (UTC). Every response carries `X-RateLimit-Limit/Remaining/Reset/Window`; exceeding a limit returns `429` with `Retry-After`.
- Versioning: each area is versioned in its path, e.g. `/users/v1`. Old versions stay live during a published deprecation window (`Deprecation` / `Sunset` headers).

## Endpoints
- `GET /users/v1`: list the company's users — `id`, `firstName`, `lastName`, `email`, `phone`, `employeeNumber`, `dateBirth`, and public custom fields. Filters: `status` (`active` | `archived`), `email` (exact, case-insensitive). Paginated.
- `GET /timesheets/v1`: list the company's completed timesheets (running clock-ins excluded) — `start`, `end`, `status`, `breakMinutes`, `minutes`, `timesheetOrigin`, `note`, plus nested `user`, `timeTrackingLocation`, `clockInType`, and per-project/per-task breakdown. Filters: `status` (`pending` | `approved` | `declined`), `userId`, `from`/`to` (`YYYY-MM-DD`), `projectId`, `type` (`work` | `simplified` | `end-day`). Paginated.
- `GET /absences/v1`: list the company's absences — `id`, `startDate`, `endDate`, `status`, `note`, `type` (a resolved standard category that maps custom absence types onto `holiday`/`overtime`/`other`), nested `customAbsenceType` (`{ id, name }`, or `null` for a standard type), `createdAt`, plus nested `user`. Filters: `status` (`pending` | `approved` | `declined`), `userId`, `from`/`to` (`YYYY-MM-DD`, overlapping the absence span), `type` (`holiday` | `sick` | `unpaid` | `paid` | `parental` | `other` | `overtime`). Paginated.
- `GET /projects/v1`: list the company's projects (metadata only) — `id`, `title`, `description`, `status` (`active` | `on_hold` | `archived`), `isInternal`, `startDate`, `endDate`, `createdAt`. Filters: `status`. Paginated. Membership and work data are served by the per-project endpoints below.
- `GET /projects/v1/detail?projectId=`: a single project's metadata plus its full membership (`members` with a derived `projectRole` of `manager` | `member`). Not paginated.
- `GET /projects/v1/work?projectId=&year=`: a single project's tracked vs. expected work for a year (`year` defaults to the current year). `tracked` = logged timesheets (running clock-ins excluded) plus manual time balances, as a yearly total and a per-month (`YYYY-MM`) breakdown; `expected` = the project's planned `project_hours` (yearly total and/or per-month plan) plus its tasks' planned budgets (`{ id, title, status, expectedTotalMinutes }`).
- `GET /projects/v1/timesheets?projectId=`: a paginated, flat list of one project's timesheet entries (one row per project timesheet), newest first — `id`, `minutes`, `note`, `start`, `end`, `status`, nested `user`, and per-task breakdown. Running clock-ins excluded. Filters: `userId`, `from`/`to` (`YYYY-MM-DD`). Paginated.

## Guides
- [Authentication](https://developers.workant.io/authentication)
- [Pagination](https://developers.workant.io/pagination)
- [Rate limits](https://developers.workant.io/rate-limits)
- [Versioning](https://developers.workant.io/versioning)
- [API Reference](https://developers.workant.io/reference)