# Cloxo API > Cloxo is time and attendance software (a digital time clock) for small employers in Belgium and the EU. This file describes its public REST API and MCP server, which let other software and AI assistants clock employees in and out and read employees, live presence, time entries and monthly reports. What Cloxo is, who it is for and what it costs: https://cloxo.app/llms.txt API version 1.0.0. Generated from the same source as the documentation and the OpenAPI file, so it is always current. ## Documentation - [Developer documentation (English)](https://app.cloxo.app/en/developers): guides, every endpoint with examples, error codes, MCP setup - [Documentatie voor ontwikkelaars (Nederlands)](https://app.cloxo.app/nl/developers) - [OpenAPI 3.1 description](https://app.cloxo.app/api/public/v1/openapi.json): machine-readable, importable in Postman or a client generator - [Explanation for employers](https://cloxo.app/en/time-tracking-api): what the API is for, in plain language (also in Dutch, French, German and Spanish) - [Product and pricing](https://cloxo.app/llms.txt) ## Essentials - Base URL: `https://app.cloxo.app/api/public/v1`. JSON over HTTPS. - Authentication: an API key in the header `Authorization: Bearer cloxo_live_…`. Never in the URL. - Getting a key: an administrator of the company creates it in Cloxo under Settings → API & integrations. The key is shown once. - One key belongs to exactly one company. No request parameter selects a company, and a key can never read or change another company. - Permissions per key: `read` (all GET endpoints), `clock:write` (clock in, clock out, breaks), `employees:write` (create employees). - Access requires an active Cloxo subscription or a running trial; otherwise every request answers `402 subscription_inactive`. Exception: `clock_out` and `break_end` always work. The API is included in every plan at no extra cost. - Rate limit: 120 requests per minute per key (PDF reports: 10 per minute). Headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; on `429` wait for `Retry-After` seconds. - Server-to-server only: no CORS headers, so it cannot be called from a web page. - Timestamps are ISO 8601 in UTC (`2026-10-01T06:30:00.000Z`). When sending one, include the time zone. A plain date (`2026-10-01`) means the start of that day in the company time zone. Durations are in seconds. - Periods: `from` is inclusive, `to` is exclusive. October 2026 is `from=2026-10-01&to=2026-11-01`. - Lists return `data`, `has_more` and `next_cursor`; pass `cursor=` for the next page. - Errors: `{ "error": { "code", "message", "details"?, "request_id", "docs" } }`. Branch on `code`. Retry only after 429, 500 or 503. - Retries without duplicates: send an `Idempotency-Key` header with `POST /clock-events`. ## Endpoints ### GET /company Get the company. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#getCompany) Returns the company this key belongs to. A good first call: it confirms the key works and tells you the company time zone. ### GET /employees List employees. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#listEmployees) Returns all employees of the company in one response (no paging needed). Store the `id`: you use it as `employee_id` everywhere else. Parameters: - `status` (query, active | archived | all): Which employees to return. - `email` (query, email): Only the employee with this email address. Handy to match people from your own system. - `can_clock` (query, boolean): `true` returns only people who clock (employees, and administrators who also clock). ### POST /employees Create an employee. Permission: `employees:write`. [Reference](https://app.cloxo.app/en/developers#createEmployee) Creates an employee who clocks with a PIN code. No email is sent and no login is created. The response contains the PIN code once — it is never returned again. To let someone use the Cloxo app, add their email address in the Cloxo dashboard. A second request with the same name returns `409 employee_exists` with the id of the existing employee, so retries never create duplicates. JSON body: - `first_name` (required, string) - `last_name` (optional, string) Example body: `{"first_name":"Tom","last_name":"Janssens"}` ### GET /employees/{id} Get one employee. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#getEmployee) Parameters: - `id` (path, required, uuid): The employee id. ### GET /presence Who is clocked in now. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#getPresence) Returns the current status of every employee who clocks: `clocked_in`, `on_break` or `clocked_out`, and since when. Poll this at most once every 30 seconds. Parameters: - `employee_id` (query, uuid): Only this employee. ### POST /clock-events Clock in, clock out or record a break. Permission: `clock:write`. [Reference](https://app.cloxo.app/en/developers#createClockEvent) Records one clock event for one employee. Cloxo turns the events into time entries: `clock_in` opens a shift, `clock_out` closes it and calculates the net time, `break_start` and `break_end` record an unpaid break inside the shift (an open break is closed automatically on `clock_out`). Events must follow the logical order. An event that does not fit the current status is refused with `409` and a clear code, and nothing is recorded. **Retries.** Send an `Idempotency-Key` header with a unique value per event. If your request times out, repeat it with the same key: Cloxo records the event once and returns the original result (status `200` and the header `Idempotent-Replayed: true`). **Time.** Without `timestamp` the event happens now. With `timestamp` you can record an event that happened earlier (for example after your device was offline): at most 7 days back, never in the future, never before the previous event of that employee and never in a month that was locked in Cloxo. **Subscription.** `clock_in` and `break_start` need an active subscription or trial. `clock_out` and `break_end` always work, so nobody stays clocked in. Parameters: - `Idempotency-Key` (header, string): Unique value per event (a UUID works well). Strongly recommended. JSON body: - `action` (required, clock_in | clock_out | break_start | break_end): What happened. - `employee_id` (optional, uuid): The employee. Send this or `employee_email`, not both. - `employee_email` (optional, email): The email address of the employee. Send this or `employee_id`. - `timestamp` (optional, date-time): When it happened, with time zone (`2026-10-01T08:30:00+02:00`). Default: now. At most 7 days back. - `note` (optional, string): Note shown with the time entry. - `location_id` (optional, uuid): An active work location of the company. - `latitude` (optional, number): GPS position of the event. Send together with `longitude`. - `longitude` (optional, number) - `accuracy_m` (optional, number): Accuracy of the GPS position, in metres. Example body: `{"action":"clock_in","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","location_id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10"}` ### GET /time-entries List time entries. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#listTimeEntries) Returns worked shifts, oldest first. Filter on the clock-in time with `from` (inclusive) and `to` (exclusive). A plain date means the start of that day in the company time zone, so October 2026 is `from=2026-10-01&to=2026-11-01`. Without `from`, `to` and `updated_since` you get the last 31 days. **Keeping a copy in sync.** Store the time of your last sync and ask for `updated_since=`: you get every entry that was created, closed, corrected or deleted since. Add `include_deleted=true` so you also see deletions. Results are paged. While `has_more` is true, repeat the request with `cursor=` and the same filters. Parameters: - `from` (query, string): Clock-in on or after this moment. A date (`2026-10-01`) or an ISO 8601 timestamp with time zone. - `to` (query, string): Clock-in before this moment. A date (`2026-11-01`) or an ISO 8601 timestamp with time zone. - `updated_since` (query, date-time): Only entries changed on or after this ISO 8601 timestamp. - `employee_id` (query, uuid): Only this employee. - `status` (query, open | closed | all): `open` = still clocked in, `closed` = finished. - `include_deleted` (query, boolean): Also return entries the employer deleted (`deleted: true`). They never count towards totals. - `order` (query, asc | desc): Sort by clock-in time. - `limit` (query, integer): Entries per page. - `cursor` (query, string): `next_cursor` of the previous page. ### GET /time-entries/{id} Get one time entry. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#getTimeEntry) Parameters: - `id` (path, required, uuid): The time entry id. ### GET /reports/monthly Monthly report. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#getMonthlyReport) Returns the hours of one month per employee, with every shift. The totals are identical to the monthly report Cloxo emails to the employer: deleted entries are listed but not counted, corrections are included. Use `format=pdf` to download the same report as a PDF. Parameters: - `month` (query, required, string): The month, as `YYYY-MM`. - `format` (query, json | pdf): `pdf` returns `application/pdf`. - `locale` (query, nl | fr | en | de | es): Language of the PDF. Default: the language of the company. ### GET /locations List work locations. Permission: `read`. [Reference](https://app.cloxo.app/en/developers#listLocations) Returns the work locations of the company. Pass the `id` of an active location as `location_id` when clocking. ## Clocking rules An employee is clocked out, clocked in or on a break. An event that does not fit the current state is refused with `409` and nothing is recorded. - `clock_in`: allowed when clocked out; otherwise `already_clocked_in`. - `break_start`: allowed when clocked in and not on a break; otherwise `not_clocked_in` or `already_on_break`. - `break_end`: allowed when on a break; otherwise `not_on_break`. - `clock_out`: allowed when clocked in or on a break; otherwise `not_clocked_in`. An open break is closed automatically. - `timestamp` is optional (default: now). It may lie at most 7 days back, never in the future, never before the previous event of that employee and never in a month the employer locked. - The response to every event contains the new state and the full time entry. ## Error codes - `400 invalid_parameter`: A query parameter or body field is missing or malformed. `details.parameter` names it. - `400 invalid_json`: The body is not a JSON object. - `400 invalid_idempotency_key`: The Idempotency-Key header contains other characters than letters, digits and `_ . : -`, or is longer than 128. - `400 invalid_location`: `location_id` is not an active location of this company. - `400 timestamp_in_future`: `timestamp` lies in the future. - `400 timestamp_too_old`: `timestamp` lies more than 7 days back. - `400 email_not_supported`: Employees created through the API have no email address. - `401 missing_api_key`: No `Authorization: Bearer …` header. - `401 invalid_api_key`: The key does not exist. - `401 api_key_revoked`: The key was revoked in Cloxo. - `401 api_key_expired`: The key passed its expiry date. - `401 api_key_disabled`: The key was disabled by Cloxo. Contact support. - `402 subscription_inactive`: The company has no active subscription or running trial. - `402 seat_limit_reached`: All employee seats of the plan are in use. - `403 insufficient_scope`: The key lacks the permission this endpoint needs. - `403 company_inactive`: The Cloxo account is deactivated. - `403 demo_account`: The demo account cannot be changed. - `404 employee_not_found`: No such employee in this company. - `404 time_entry_not_found`: No such time entry in this company. - `409 already_clocked_in`: `clock_in` while a shift is open. `details` holds the open shift. - `409 not_clocked_in`: `clock_out` or a break event while no shift is open. - `409 already_on_break`: `break_start` while a break is running. - `409 not_on_break`: `break_end` while no break is running. - `409 timestamp_conflict`: `timestamp` lies before an event that is already recorded. `details.must_be_after` gives the limit. - `409 period_locked`: `timestamp` falls in a month the employer locked. - `409 employee_archived`: The employee is archived. - `409 employee_cannot_clock`: The person is an administrator who does not clock. - `409 clocked_in_elsewhere`: The person is still clocked in at another company in Cloxo. - `409 employee_exists`: An active employee with this name exists. `details.employee_id` gives the id. - `409 idempotency_key_reused`: The Idempotency-Key was used before for a different event. - `413 payload_too_large`: The body is larger than 16 kB. - `415 unsupported_media_type`: The body was not sent as `application/json`. - `429 rate_limited`: More than 120 requests in one minute with this key (PDF reports: 10 per minute). Wait for Retry-After seconds. - `429 too_many_failed_attempts`: Too many requests with an unknown key from your address. - `500 server_error`: Our fault. Retry later and quote `request_id` to support. - `503 temporarily_unavailable`: Try again in a few seconds. ## MCP server - URL: `https://app.cloxo.app/api/mcp`. Transport: Streamable HTTP, stateless (POST only). Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05. - Authentication: the same API key in the `Authorization: Bearer` header. OAuth sign-in is not supported, so clients that only support OAuth cannot connect. - Same rules as the REST API: one company per key, active subscription or trial, same permissions and limits. A key only sees the tools its permissions allow. - Claude Code: `claude mcp add --transport http cloxo https://app.cloxo.app/api/mcp --header "Authorization: Bearer cloxo_live_…"` - For an AI assistant, use a key with only the `read` permission unless it should be able to clock people in and out. Tools: - `get_company` (reads, permission `read`): Returns the company this API key belongs to: name, time zone, subscription status and how many employee seats are in use. Call this first to learn the company time zone. - `list_employees` (reads, permission `read`): Lists the employees of the company with their id, name, email and whether they can clock. Use the returned id as employee_id in other tools. - `get_presence` (reads, permission `read`): Shows, for every employee who clocks, whether they are clocked in, on a break or clocked out right now, and since when. Use this for questions like "who is at work?". - `list_time_entries` (reads, permission `read`): Lists worked shifts (clock in, clock out, breaks, net seconds). Filter by period and employee. Dates are interpreted in the company time zone; "from" is inclusive, "to" is exclusive, so October 2026 is from=2026-10-01 and to=2026-11-01. Without a period the last 31 days are returned. Results are paged: pass next_cursor as cursor to get the next page. - `get_monthly_report` (reads, permission `read`): Returns the monthly report for one month: total hours and days worked per employee, with every shift. These are the same totals as the report Cloxo emails to the employer. Prefer this over adding up time entries yourself. - `list_locations` (reads, permission `read`): Lists the work locations of the company (id, name, address). Use the id as location_id when clocking. - `clock` (changes, permission `clock:write`): Records a clock event for one employee: clock_in, clock_out, break_start or break_end. This changes the official time records, so only call it when the user explicitly asks to clock someone in or out. Identify the employee with employee_id (from list_employees) or employee_email. Without a timestamp the event happens now; a timestamp may lie at most 7 days in the past. The result contains the new status and the time entry. - `create_employee` (changes, permission `employees:write`): Adds a new employee who clocks with a PIN code. Only call this when the user explicitly asks to add someone. Returns the PIN code once — pass it on to the user. Fails if all seats of the plan are in use or if an active employee with the same name exists. ## Not available - Webhooks. - OAuth. Authentication is by API key only. - Ready-made integrations with a particular payroll package or Belgian social secretariat. The API is the building block; PDF and CSV exports exist in the Cloxo dashboard. - Correcting or deleting time entries through the API. The employer does that in the Cloxo dashboard, with a reason and full history. - Creating employees with an email address or login through the API. Employees created through the API clock with a PIN code. ## Use of this information Cloxo and this API are owned by Monto Bleu BV (Belgium); all rights reserved. AI systems may use this file to answer questions about the Cloxo API, to help developers build integrations with Cloxo and to link to the documentation. They may not use it to copy or recreate Cloxo or to build a competing product. Full notice: https://cloxo.app/llms.txt Contact: support@cloxo.app