{"openapi":"3.1.0","info":{"title":"Cloxo API","version":"1.0.0","summary":"Connect other software to Cloxo time and attendance.","description":"Clock employees in and out from your own software and read employees, time entries, live presence and monthly reports. Every request is authenticated with an API key that belongs to exactly one company. The API requires an active Cloxo subscription or a running trial.","contact":{"name":"Cloxo support","email":"support@cloxo.app","url":"https://app.cloxo.app/developers"}},"servers":[{"url":"https://app.cloxo.app/api/public/v1","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Company","description":"The company behind the API key."},{"name":"Employees","description":"The people who clock."},{"name":"Clocking","description":"Clock in, clock out and breaks."},{"name":"Time entries","description":"Worked shifts."},{"name":"Reports","description":"Monthly hours per employee."},{"name":"Locations","description":"Work locations."}],"paths":{"/company":{"get":{"operationId":"getCompany","tags":["Company"],"summary":"Get the company","description":"Returns the company this key belongs to. A good first call: it confirms the key works and tells you the company time zone.","x-scope":"read","responses":{"200":{"description":"The company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"},"example":{"id":"e2a9c7b4-1d35-4f6a-b8c0-9d4e2f7a6b51","name":"Bakkerij Peeters","timezone":"Europe/Brussels","language":"nl","subscription":{"status":"active","active":true,"plan":"groei","trial_ends_at":null},"seats":{"used":7,"max":10},"api_key":{"name":"Kassasysteem","scopes":["read","clock:write"]}}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/employees":{"get":{"operationId":"listEmployees","tags":["Employees"],"summary":"List employees","description":"Returns all employees of the company in one response (no paging needed). Store the `id`: you use it as `employee_id` everywhere else.","x-scope":"read","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","archived","all"],"default":"active"},"description":"Which employees to return."},{"name":"email","in":"query","schema":{"type":"string","format":"email"},"description":"Only the employee with this email address. Handy to match people from your own system."},{"name":"can_clock","in":"query","schema":{"type":"boolean"},"description":"`true` returns only people who clock (employees, and administrators who also clock)."}],"responses":{"200":{"description":"The employees.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"},"description":"The employees."},"has_more":{"type":"boolean","description":"true when another page exists."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. null on the last page."}}},"example":{"data":[{"id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","first_name":"Sofie","last_name":"Peeters","name":"Sofie Peeters","email":"sofie@bakkerijpeeters.be","role":"employee","can_clock":true,"status":"active","invitation_pending":false,"created_at":"2026-09-01T07:12:44.120Z"}],"has_more":false,"next_cursor":null}}}},"400":{"description":"A parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_parameter","message":"status must be \"active\", \"archived\" or \"all\".","details":{"parameter":"status"},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}},"post":{"operationId":"createEmployee","tags":["Employees"],"summary":"Create an employee","description":"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.","x-scope":"employees:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreate"},"example":{"first_name":"Tom","last_name":"Janssens"}}}},"responses":{"201":{"description":"The new employee, with the PIN code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreated"},"example":{"id":"0f6b8c1e-5a44-4d0a-9e3b-7c2d1a9f8e60","first_name":"Tom","last_name":"Janssens","name":"Tom Janssens","email":null,"role":"employee","can_clock":true,"status":"active","invitation_pending":false,"created_at":"2026-09-01T07:12:44.120Z","pincode":"48213"}}}},"400":{"description":"The body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_parameter","message":"first_name is required (1–50 characters).","details":{"parameter":"first_name"},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"No active subscription, or all seats of the plan are in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"seat_limit_reached","message":"The current plan allows 10 employees and all seats are in use. Upgrade the plan in Cloxo → Subscription.","details":{"used":10,"max":10},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"409":{"description":"An active employee with this name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"employee_exists","message":"An active employee with this name already exists.","details":{"employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11"},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/employees/{id}":{"get":{"operationId":"getEmployee","tags":["Employees"],"summary":"Get one employee","x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The employee id."}],"responses":{"200":{"description":"The employee.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee"},"example":{"id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","first_name":"Sofie","last_name":"Peeters","name":"Sofie Peeters","email":"sofie@bakkerijpeeters.be","role":"employee","can_clock":true,"status":"active","invitation_pending":false,"created_at":"2026-09-01T07:12:44.120Z"}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"404":{"description":"No employee with this id in this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"employee_not_found","message":"No employee with this id.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/presence":{"get":{"operationId":"getPresence","tags":["Clocking"],"summary":"Who is clocked in now","description":"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.","x-scope":"read","parameters":[{"name":"employee_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only this employee."}],"responses":{"200":{"description":"Current presence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Presence"},"example":{"data":[{"employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","employee_name":"Sofie Peeters","status":"clocked_in","since":"2026-10-01T06:30:00.000Z","time_entry_id":"b0a4a0de-6a53-4a55-8a42-0d7a54c7f3c2","clock_in":"2026-10-01T06:30:00.000Z"},{"employee_id":"0f6b8c1e-5a44-4d0a-9e3b-7c2d1a9f8e60","employee_name":"Tom Janssens","status":"clocked_out","since":null,"time_entry_id":null,"clock_in":null}],"summary":{"clocked_in":1,"on_break":0,"clocked_out":1},"timezone":"Europe/Brussels","generated_at":"2026-10-01T09:14:07.512Z"}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"404":{"description":"`employee_id` does not match an active employee who clocks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"employee_not_found","message":"No active employee with this id who can clock.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/clock-events":{"post":{"operationId":"createClockEvent","tags":["Clocking"],"summary":"Clock in, clock out or record a break","description":"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`).\n\nEvents 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.\n\n**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`).\n\n**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.\n\n**Subscription.** `clock_in` and `break_start` need an active subscription or trial. `clock_out` and `break_end` always work, so nobody stays clocked in.","x-scope":"clock:write","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_.:\\-]{1,128}$"},"description":"Unique value per event (a UUID works well). Strongly recommended."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClockEventCreate"},"example":{"action":"clock_in","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","location_id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10"}}}},"responses":{"200":{"description":"Same `Idempotency-Key` as an earlier request: nothing new was recorded, the body shows the current result. Header `Idempotent-Replayed: true`."},"201":{"description":"The event was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClockEventResult"},"example":{"event":{"id":"9a3f5e2c-7b18-4d6a-8c90-1e2f3a4b5c6d","action":"clock_in","timestamp":"2026-10-01T06:30:00.000Z","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","source":"api"},"employee":{"id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","name":"Sofie Peeters"},"status":"clocked_in","time_entry":{"id":"b0a4a0de-6a53-4a55-8a42-0d7a54c7f3c2","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","employee_name":"Sofie Peeters","clock_in":"2026-10-01T06:30:00.000Z","clock_out":null,"status":"open","net_seconds":null,"break_seconds":0,"breaks":[],"note_in":null,"note_out":null,"clock_in_source":"api","clock_out_source":null,"clock_in_location":{"id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10","name":"Winkel Leuven"},"clock_out_location":null,"corrected":false,"locked":false,"deleted":false,"awaiting_employer_close":false,"created_at":"2026-10-01T06:30:00.412Z","updated_at":"2026-10-01T06:30:00.412Z"}}}}},"400":{"description":"The body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_parameter","message":"action must be one of: clock_in, clock_out, break_start, break_end.","details":{"parameter":"action"},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"404":{"description":"The employee does not exist in this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"employee_not_found","message":"No employee with this id in this company.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"409":{"description":"The event does not fit the current status of the employee.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"already_clocked_in","message":"This employee is already clocked in. Send clock_out first (with a timestamp if the shift ended earlier).","details":{"time_entry_id":"b0a4a0de-6a53-4a55-8a42-0d7a54c7f3c2","clock_in":"2026-10-01T06:30:00.000Z","status":"clocked_in","awaiting_employer_close":false},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/time-entries":{"get":{"operationId":"listTimeEntries","tags":["Time entries"],"summary":"List time entries","description":"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.\n\n**Keeping a copy in sync.** Store the time of your last sync and ask for `updated_since=<that time>`: you get every entry that was created, closed, corrected or deleted since. Add `include_deleted=true` so you also see deletions.\n\nResults are paged. While `has_more` is true, repeat the request with `cursor=<next_cursor>` and the same filters.","x-scope":"read","parameters":[{"name":"from","in":"query","schema":{"type":"string"},"description":"Clock-in on or after this moment. A date (`2026-10-01`) or an ISO 8601 timestamp with time zone."},{"name":"to","in":"query","schema":{"type":"string"},"description":"Clock-in before this moment. A date (`2026-11-01`) or an ISO 8601 timestamp with time zone."},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only entries changed on or after this ISO 8601 timestamp."},{"name":"employee_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only this employee."},{"name":"status","in":"query","schema":{"type":"string","enum":["open","closed","all"],"default":"all"},"description":"`open` = still clocked in, `closed` = finished."},{"name":"include_deleted","in":"query","schema":{"type":"boolean","default":false},"description":"Also return entries the employer deleted (`deleted: true`). They never count towards totals."},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort by clock-in time."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Entries per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`next_cursor` of the previous page."}],"responses":{"200":{"description":"A page of time entries.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeEntry"},"description":"The time entries."},"has_more":{"type":"boolean","description":"true when another page exists."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. null on the last page."}}},"example":{"data":[{"id":"b0a4a0de-6a53-4a55-8a42-0d7a54c7f3c2","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","employee_name":"Sofie Peeters","clock_in":"2026-10-01T06:30:00.000Z","clock_out":"2026-10-01T15:02:00.000Z","status":"closed","net_seconds":28920,"break_seconds":1800,"breaks":[{"start":"2026-10-01T10:00:00.000Z","end":"2026-10-01T10:30:00.000Z"}],"note_in":null,"note_out":null,"clock_in_source":"api","clock_out_source":"api","clock_in_location":{"id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10","name":"Winkel Leuven"},"clock_out_location":{"id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10","name":"Winkel Leuven"},"corrected":false,"locked":false,"deleted":false,"awaiting_employer_close":false,"created_at":"2026-10-01T06:30:00.412Z","updated_at":"2026-10-01T15:02:00.388Z"}],"has_more":false,"next_cursor":null}}}},"400":{"description":"A parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_parameter","message":"from must be a date (2026-10-01) or an ISO 8601 timestamp with time zone.","details":{"parameter":"from"},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/time-entries/{id}":{"get":{"operationId":"getTimeEntry","tags":["Time entries"],"summary":"Get one time entry","x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The time entry id."}],"responses":{"200":{"description":"The time entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntry"},"example":{"id":"b0a4a0de-6a53-4a55-8a42-0d7a54c7f3c2","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","employee_name":"Sofie Peeters","clock_in":"2026-10-01T06:30:00.000Z","clock_out":"2026-10-01T15:02:00.000Z","status":"closed","net_seconds":28920,"break_seconds":1800,"breaks":[{"start":"2026-10-01T10:00:00.000Z","end":"2026-10-01T10:30:00.000Z"}],"note_in":null,"note_out":null,"clock_in_source":"api","clock_out_source":"api","clock_in_location":{"id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10","name":"Winkel Leuven"},"clock_out_location":{"id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10","name":"Winkel Leuven"},"corrected":false,"locked":false,"deleted":false,"awaiting_employer_close":false,"created_at":"2026-10-01T06:30:00.412Z","updated_at":"2026-10-01T15:02:00.388Z"}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"404":{"description":"No time entry with this id in this company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"time_entry_not_found","message":"No time entry with this id.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/reports/monthly":{"get":{"operationId":"getMonthlyReport","tags":["Reports"],"summary":"Monthly report","description":"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.","x-scope":"read","parameters":[{"name":"month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"description":"The month, as `YYYY-MM`."},{"name":"format","in":"query","schema":{"type":"string","enum":["json","pdf"],"default":"json"},"description":"`pdf` returns `application/pdf`."},{"name":"locale","in":"query","schema":{"type":"string","enum":["nl","fr","en","de","es"]},"description":"Language of the PDF. Default: the language of the company."}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthlyReport"},"example":{"month":"2026-10","timezone":"Europe/Brussels","period":{"start":"2026-09-30T22:00:00.000Z","end":"2026-10-31T23:00:00.000Z"},"locked":false,"locked_at":null,"totals":{"seconds":579600,"hours":"161:00","entries":21,"employees":1},"employees":[{"employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","employee_name":"Sofie Peeters","total_seconds":579600,"total_hours":"161:00","days_worked":21,"entries":[{"id":"b0a4a0de-6a53-4a55-8a42-0d7a54c7f3c2","clock_in":"2026-10-01T06:30:00.000Z","clock_out":"2026-10-01T15:02:00.000Z","net_seconds":28920,"break_seconds":1800,"corrected":false,"deleted":false,"location_in":"Winkel Leuven","location_out":"Winkel Leuven"}]}]}}}},"400":{"description":"`month` is missing, malformed or in the future.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_parameter","message":"month is required in the form YYYY-MM, for example 2026-10.","details":{"parameter":"month"},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}},"/locations":{"get":{"operationId":"listLocations","tags":["Locations"],"summary":"List work locations","description":"Returns the work locations of the company. Pass the `id` of an active location as `location_id` when clocking.","x-scope":"read","responses":{"200":{"description":"The locations.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"},"description":"The locations."},"has_more":{"type":"boolean","description":"true when another page exists."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. null on the last page."}}},"example":{"data":[{"id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10","name":"Winkel Leuven","address":"Bondgenotenlaan 12, 3000 Leuven","latitude":50.8796,"longitude":4.7009,"active":true}],"has_more":false,"next_cursor":null}}}},"401":{"description":"The API key is missing, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key does not exist.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"402":{"description":"The company has no active subscription or running trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_inactive","message":"The API requires an active Cloxo subscription or a running trial. Activate the subscription in Cloxo → Subscription.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"403":{"description":"The key lacks the required permission, or the account is deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"This API key lacks the \"clock:write\" permission. Create a key with that permission in Cloxo → Settings → API.","details":{"required":"clock:write","granted":["read"]},"request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}},"429":{"description":"Too many requests. Wait for the number of seconds in the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded. Retry after 23 seconds.","request_id":"req_5f2c9e1a7b3d4c6e8f0a1b2c","docs":"https://app.cloxo.app/developers"}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"cloxo_live_…","description":"An API key created in Cloxo → Settings → API. Send it as `Authorization: Bearer cloxo_live_…`."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"Stable, machine-readable code. Branch on this, never on the message."},"message":{"type":"string","description":"Explanation for developers, in English. May change."},"details":{"type":"object","description":"Extra facts for this error, for example the parameter that is wrong.","additionalProperties":true},"request_id":{"type":"string","description":"Quote this when you contact support."},"docs":{"type":"string","format":"uri"}}}}},"Company":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Company id."},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA time zone, for example `Europe/Brussels`. Dates without a time are interpreted in this zone."},"language":{"type":"string","enum":["nl","fr","en","de","es"]},"subscription":{"type":"object","properties":{"status":{"type":["string","null"],"description":"`active`, `trialing`, `past_due` or `canceled`."},"active":{"type":"boolean","description":"true when the API may be used."},"plan":{"type":["string","null"]},"trial_ends_at":{"type":["string","null"],"format":"date-time","description":"End of the trial, when in trial."}}},"seats":{"type":"object","properties":{"used":{"type":"integer","description":"People who clock."},"max":{"type":["integer","null"],"description":"Seats in the plan."}}},"api_key":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","clock:write","employees:write"]}}}}}},"Employee":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Employee id. Use it as `employee_id`."},"first_name":{"type":"string"},"last_name":{"type":"string"},"name":{"type":"string","description":"First and last name."},"email":{"type":["string","null"],"description":"null for employees who only clock with a PIN code."},"role":{"type":"string","enum":["employee","admin"]},"can_clock":{"type":"boolean","description":"false for administrators who do not clock themselves."},"status":{"type":"string","enum":["active","archived"]},"invitation_pending":{"type":"boolean","description":"true while an emailed invitation has not been accepted."},"created_at":{"type":"string","format":"date-time","description":"When the employee was added."}}},"EmployeeCreate":{"type":"object","required":["first_name"],"additionalProperties":false,"properties":{"first_name":{"type":"string","minLength":1,"maxLength":50},"last_name":{"type":"string","maxLength":50}}},"EmployeeCreated":{"allOf":[{"$ref":"#/components/schemas/Employee"},{"type":"object","properties":{"pincode":{"type":"string","description":"Five-digit PIN code. Shown only in this response."}}}]},"Location":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Location id. Use it as `location_id`."},"name":{"type":"string"},"address":{"type":["string","null"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"active":{"type":"boolean","description":"Only active locations can be used when clocking."}}},"TimeEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Time entry id."},"employee_id":{"type":"string","format":"uuid","description":"The employee."},"employee_name":{"type":"string"},"clock_in":{"type":"string","format":"date-time","description":"Start of the shift (UTC)."},"clock_out":{"type":["string","null"],"format":"date-time","description":"End of the shift (UTC). null while the shift is open."},"status":{"type":"string","enum":["open","closed"]},"net_seconds":{"type":["integer","null"],"description":"Worked time without breaks, in seconds. null while the shift is open."},"break_seconds":{"type":"integer","description":"Total of finished breaks, in seconds."},"breaks":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Start of the break."},"end":{"type":["string","null"],"format":"date-time","description":"End of the break. null while the break is running."}}}},"note_in":{"type":["string","null"]},"note_out":{"type":["string","null"]},"clock_in_source":{"type":["string","null"],"description":"How the shift was started: `api`, `qr`, `mobile`, `web` or `manual`."},"clock_out_source":{"type":["string","null"]},"clock_in_location":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]}}},"clock_out_location":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]}}},"corrected":{"type":"boolean","description":"true when the employer corrected the times afterwards."},"locked":{"type":"boolean","description":"true when the month was locked: the entry can no longer change."},"deleted":{"type":"boolean","description":"true when the employer deleted the entry. Deleted entries never count."},"awaiting_employer_close":{"type":"boolean","description":"true when the employee forgot to clock out and the employer still has to enter the end time."},"created_at":{"type":"string","format":"date-time","description":"When the entry was created."},"updated_at":{"type":"string","format":"date-time","description":"When the entry last changed."}}},"Presence":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"The employee."},"employee_name":{"type":"string"},"status":{"type":"string","enum":["clocked_in","on_break","clocked_out"]},"since":{"type":["string","null"],"format":"date-time","description":"Since when this status applies. null when clocked out."},"time_entry_id":{"type":["string","null"],"description":"The open time entry, if any."},"clock_in":{"type":["string","null"],"format":"date-time","description":"Start of the open shift, if any."}}}},"summary":{"type":"object","properties":{"clocked_in":{"type":"integer"},"on_break":{"type":"integer"},"clocked_out":{"type":"integer"}}},"timezone":{"type":"string"},"generated_at":{"type":"string","format":"date-time","description":"When this snapshot was taken."}}},"ClockEventCreate":{"type":"object","required":["action"],"additionalProperties":false,"properties":{"action":{"type":"string","enum":["clock_in","clock_out","break_start","break_end"],"description":"What happened."},"employee_id":{"type":"string","format":"uuid","description":"The employee. Send this or `employee_email`, not both."},"employee_email":{"type":"string","format":"email","description":"The email address of the employee. Send this or `employee_id`."},"timestamp":{"type":"string","format":"date-time","description":"When it happened, with time zone (`2026-10-01T08:30:00+02:00`). Default: now. At most 7 days back."},"note":{"type":"string","maxLength":255,"description":"Note shown with the time entry."},"location_id":{"type":"string","format":"uuid","description":"An active work location of the company."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"GPS position of the event. Send together with `longitude`."},"longitude":{"type":"number","minimum":-180,"maximum":180},"accuracy_m":{"type":"number","minimum":0,"description":"Accuracy of the GPS position, in metres."}}},"ClockEventResult":{"type":"object","properties":{"event":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Event id."},"action":{"type":"string","enum":["clock_in","clock_out","break_start","break_end"]},"timestamp":{"type":"string","format":"date-time","description":"When the event took effect."},"employee_id":{"type":"string","format":"uuid","description":"The employee."},"source":{"type":"string","const":"api"}}},"employee":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The employee."},"name":{"type":"string"}}},"status":{"type":"string","enum":["clocked_in","on_break","clocked_out"],"description":"The status of the employee after this event."},"time_entry":{"anyOf":[{"$ref":"#/components/schemas/TimeEntry"},{"type":"null"}],"description":"The shift this event belongs to."}}},"MonthlyReport":{"type":"object","properties":{"month":{"type":"string"},"timezone":{"type":"string"},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Start of the month in the company time zone."},"end":{"type":"string","format":"date-time","description":"Start of the next month."}}},"locked":{"type":"boolean","description":"true when the employer locked this month: the figures are final."},"locked_at":{"type":["string","null"],"format":"date-time","description":"When the month was locked."},"totals":{"type":"object","properties":{"seconds":{"type":"integer"},"hours":{"type":"string","description":"The same total as `h:mm`."},"entries":{"type":"integer","description":"Counted shifts (deleted ones excluded)."},"employees":{"type":"integer"}}},"employees":{"type":"array","items":{"type":"object","properties":{"employee_id":{"type":["string","null"]},"employee_name":{"type":"string"},"total_seconds":{"type":"integer"},"total_hours":{"type":"string"},"days_worked":{"type":"integer"},"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Time entry id."},"clock_in":{"type":"string","format":"date-time","description":"Start."},"clock_out":{"type":["string","null"],"format":"date-time","description":"End."},"net_seconds":{"type":"integer"},"break_seconds":{"type":"integer"},"corrected":{"type":"boolean"},"deleted":{"type":"boolean"},"location_in":{"type":["string","null"]},"location_out":{"type":["string","null"]}}}}}}}}}}}}