For developers

Cloxo API

Connect your own software to Cloxo. Clock employees in and out from your point of sale, scheduling or access control system, and fetch hours, presence and monthly reports. Cloxo takes care of the records, the corrections and the reports.

Address
https://app.cloxo.app/api/public/v1
Format
JSON over HTTPS
Limit
120 requests per minute
Overview

Quick start

Three steps to clock in your first employee.

  1. 1

    Create a key

    An administrator opens Settings → API & integrations in Cloxo and creates a key. The key starts with cloxo_live_ and is shown only once. Store it like a password.

  2. 2

    Test the connection

    Fetch the company. If you get the name and time zone back, the key works.

    curl
    export CLOXO_API_KEY="cloxo_live_…"
    
    curl "https://app.cloxo.app/api/public/v1/company" \
      -H "Authorization: Bearer $CLOXO_API_KEY"
  3. 3

    Clock someone in

    Fetch the employees, take the id of the right person and send a clock event.

    curl
    curl "https://app.cloxo.app/api/public/v1/employees" \
      -H "Authorization: Bearer $CLOXO_API_KEY"
    
    curl -X POST "https://app.cloxo.app/api/public/v1/clock-events" \
      -H "Authorization: Bearer $CLOXO_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 5d0c7f0e-2a1b-4c3d-9e8f-7a6b5c4d3e2f" \
      -d '{"action":"clock_in","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11"}'

The employee is now clocked in in Cloxo. Clocking out works the same way, with "action": "clock_out".

Authentication

Send the key with every request in the Authorization header. Never put it in the URL.

HTTP
Authorization: Bearer cloxo_live_…

A key belongs to exactly one company. You never send a company id, and a key can never see data of another company. If you work for several employers, each employer creates their own key.

The API is meant for server-to-server traffic. You cannot call it directly from a web page: a key in front-end code is readable by everyone.

Access and subscription

The API only works when the employer has an active Cloxo subscription or is in the trial. Otherwise every request answers 402 subscription_inactive.

One exception: clock_out and break_end always work, so nobody stays clocked in.

GET /company shows the state in subscription.active.

Permissions

When creating a key, the administrator chooses what it may do.

PermissionName in CloxoGives access to
readRead dataAll GET endpoints: company, employees, presence, time entries, reports, locations.
clock:writeClock in and outPOST /clock-events: clocking in and out and breaks.
employees:writeAdd employeesPOST /employees: creating employees with a PIN code.

Ask only for the permissions your integration needs. When a key lacks a permission you get 403 insufficient_scope.

Rate limits

Each key gets 120 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window restarts).

Above the limit you get 429 rate_limited with a Retry-After header. Wait that many seconds and try again.

There is no need to poll presence more than once every 30 seconds.

Errors

An error always has the same shape. Branch on error.code in your code; it does not change. The message is an explanation for developers and may change.

Quote the request_id when you ask for help. It is also in the X-Request-Id header of every response.

409
{
  "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"
  }
}

Retry a request only after 429, 500 or 503, with a pause in between. Retrying any other error is pointless: change the request first.

StatusCodeMeaning
400invalid_parameterA query parameter or body field is missing or malformed. details.parameter names it.
400invalid_jsonThe body is not a JSON object.
400invalid_idempotency_keyThe Idempotency-Key header contains other characters than letters, digits and _ . : -, or is longer than 128.
400invalid_locationlocation_id is not an active location of this company.
400timestamp_in_futuretimestamp lies in the future.
400timestamp_too_oldtimestamp lies more than 7 days back.
400email_not_supportedEmployees created through the API have no email address.
401missing_api_keyNo Authorization: Bearer … header.
401invalid_api_keyThe key does not exist.
401api_key_revokedThe key was revoked in Cloxo.
401api_key_expiredThe key passed its expiry date.
401api_key_disabledThe key was disabled by Cloxo. Contact support.
402subscription_inactiveThe company has no active subscription or running trial.
402seat_limit_reachedAll employee seats of the plan are in use.
403insufficient_scopeThe key lacks the permission this endpoint needs.
403company_inactiveThe Cloxo account is deactivated.
403demo_accountThe demo account cannot be changed.
404employee_not_foundNo such employee in this company.
404time_entry_not_foundNo such time entry in this company.
409already_clocked_inclock_in while a shift is open. details holds the open shift.
409not_clocked_inclock_out or a break event while no shift is open.
409already_on_breakbreak_start while a break is running.
409not_on_breakbreak_end while no break is running.
409timestamp_conflicttimestamp lies before an event that is already recorded. details.must_be_after gives the limit.
409period_lockedtimestamp falls in a month the employer locked.
409employee_archivedThe employee is archived.
409employee_cannot_clockThe person is an administrator who does not clock.
409clocked_in_elsewhereThe person is still clocked in at another company in Cloxo.
409employee_existsAn active employee with this name exists. details.employee_id gives the id.
409idempotency_key_reusedThe Idempotency-Key was used before for a different event.
413payload_too_largeThe body is larger than 16 kB.
415unsupported_media_typeThe body was not sent as application/json.
429rate_limitedMore than 120 requests in one minute with this key (PDF reports: 10 per minute). Wait for Retry-After seconds.
429too_many_failed_attemptsToo many requests with an unknown key from your address.
500server_errorOur fault. Retry later and quote request_id to support.
503temporarily_unavailableTry again in a few seconds.

Conventions

Time
All timestamps are ISO 8601 in UTC, for example 2026-10-01T06:30:00.000Z. When you send a timestamp, always include the time zone (Z or +02:00). A date without a time, like 2026-10-01, means the start of that day in the company time zone.
Duration
Durations are in seconds. net_seconds is the time worked without breaks.
Periods
from is included, to is not. October 2026 is therefore from=2026-10-01&to=2026-11-01.
Pages
Lists return data, has_more and next_cursor. While has_more is true, repeat the request with cursor=<next_cursor> and the same filters.
Retrying without duplicates
With POST /clock-events, send an Idempotency-Key header with a unique value per clock event, for example a UUID. If the connection drops, repeat with the same value: Cloxo records the event once.
New fields
Responses may gain fields. Ignore fields you do not know.

How clocking works

An employee is clocked out, clocked in or on a break. Every clock event moves them from one state to another. If an event does not fit the state, Cloxo refuses it with 409 and records nothing.

ActionAllowed whenOtherwise
clock_inclocked outalready_clocked_in
break_startclocked in, not on a breaknot_clocked_in / already_on_break
break_endon a breaknot_on_break
clock_outclocked in or on a breaknot_clocked_in
  • The response to every clock event contains the new state and the full time entry, so you do not need to fetch it separately.
  • Without timestamp the event happens now. With timestamp you record something 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.
  • Is a shift from an earlier day still open? Send clock_out with the timestamp at which that shift ended. If nobody knows the end time, the employer enters it in Cloxo.
  • Records made through the API get the source api. The employer sees them in Cloxo next to the records made with the QR code and the app, and can correct them there.

Endpoints

All paths start with https://app.cloxo.app/api/public/v1.

get/companyPermission: read

Get the company

Returns the company this key belongs to. A good first call: it confirms the key works and tells you the company time zone.

Example
curl "https://app.cloxo.app/api/public/v1/company" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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"
    ]
  }
}

Possible errors

  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/employeesPermission: read

List employees

Returns all employees of the company in one response (no paging needed). Store the id: you use it as employee_id everywhere else.

Parameters

NameTypeDescription
status"active" | "archived" | "all" = activeWhich employees to return.
emailstringOnly the employee with this email address. Handy to match people from your own system.
can_clockbooleantrue returns only people who clock (employees, and administrators who also clock).
Example
curl "https://app.cloxo.app/api/public/v1/employees" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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
}

Possible errors

  • 400 A parameter is invalid.
  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
post/employeesPermission: employees:write

Create an employee

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.

Body

NameTypeDescription
first_namerequiredstring
last_namestring
Example
curl -X POST "https://app.cloxo.app/api/public/v1/employees" \
  -H "Authorization: Bearer $CLOXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Tom","last_name":"Janssens"}'
Response 201
{
  "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"
}

Possible errors

  • 400 The body is invalid.
  • 401 The API key is missing, unknown, revoked or expired.
  • 402 No active subscription, or all seats of the plan are in use.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 409 An active employee with this name already exists.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/employees/{id}Permission: read

Get one employee

Parameters

NameTypeDescription
idrequireduuidThe employee id.
Example
curl "https://app.cloxo.app/api/public/v1/employees/7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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"
}

Possible errors

  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 404 No employee with this id in this company.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/presencePermission: read

Who is clocked in now

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

NameTypeDescription
employee_iduuidOnly this employee.
Example
curl "https://app.cloxo.app/api/public/v1/presence" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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"
}

Possible errors

  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 404 `employee_id` does not match an active employee who clocks.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
post/clock-eventsPermission: clock:write

Clock in, clock out or record a break

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

NameTypeDescription
Idempotency-KeyheaderUnique value per event (a UUID works well). Strongly recommended.

Body

NameTypeDescription
actionrequired"clock_in" | "clock_out" | "break_start" | "break_end"What happened.
employee_iduuidThe employee. Send this or employee_email, not both.
employee_emailstringThe email address of the employee. Send this or employee_id.
timestamptimestampWhen it happened, with time zone (2026-10-01T08:30:00+02:00). Default: now. At most 7 days back.
notestringNote shown with the time entry.
location_iduuidAn active work location of the company.
latitudenumberGPS position of the event. Send together with longitude.
longitudenumber
accuracy_mnumberAccuracy of the GPS position, in metres.
Example
curl -X POST "https://app.cloxo.app/api/public/v1/clock-events" \
  -H "Authorization: Bearer $CLOXO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d0c7f0e-2a1b-4c3d-9e8f-7a6b5c4d3e2f" \
  -d '{"action":"clock_in","employee_id":"7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11","location_id":"3e9f1d0a-98b4-4f7e-8d0c-5a2f9c6d7e10"}'
Response 201
{
  "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"
  }
}

Possible errors

  • 400 The body is invalid.
  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 404 The employee does not exist in this company.
  • 409 The event does not fit the current status of the employee.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/time-entriesPermission: read

List time entries

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=<that time>: 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=<next_cursor> and the same filters.

Parameters

NameTypeDescription
fromstringClock-in on or after this moment. A date (2026-10-01) or an ISO 8601 timestamp with time zone.
tostringClock-in before this moment. A date (2026-11-01) or an ISO 8601 timestamp with time zone.
updated_sincetimestampOnly entries changed on or after this ISO 8601 timestamp.
employee_iduuidOnly this employee.
status"open" | "closed" | "all" = allopen = still clocked in, closed = finished.
include_deletedboolean = falseAlso return entries the employer deleted (deleted: true). They never count towards totals.
order"asc" | "desc" = ascSort by clock-in time.
limitinteger = 50Entries per page.
cursorstringnext_cursor of the previous page.
Example
curl "https://app.cloxo.app/api/public/v1/time-entries" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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
}

Possible errors

  • 400 A parameter is invalid.
  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/time-entries/{id}Permission: read

Get one time entry

Parameters

NameTypeDescription
idrequireduuidThe time entry id.
Example
curl "https://app.cloxo.app/api/public/v1/time-entries/7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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"
}

Possible errors

  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 404 No time entry with this id in this company.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/reports/monthlyPermission: read

Monthly report

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

NameTypeDescription
monthrequiredstringThe month, as YYYY-MM.
format"json" | "pdf" = jsonpdf returns application/pdf.
locale"nl" | "fr" | "en" | "de" | "es"Language of the PDF. Default: the language of the company.
Example
curl "https://app.cloxo.app/api/public/v1/reports/monthly?month=2026-10" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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"
        }
      ]
    }
  ]
}

Possible errors

  • 400 `month` is missing, malformed or in the future.
  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.
get/locationsPermission: read

List work locations

Returns the work locations of the company. Pass the id of an active location as location_id when clocking.

Example
curl "https://app.cloxo.app/api/public/v1/locations" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Response 200
{
  "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
}

Possible errors

  • 401 The API key is missing, unknown, revoked or expired.
  • 402 The company has no active subscription or running trial.
  • 403 The key lacks the required permission, or the account is deactivated.
  • 429 Too many requests. Wait for the number of seconds in the Retry-After header.

Objects

The fields of the objects in the responses.

Employee

NameTypeDescription
iduuidEmployee id. Use it as employee_id.
first_namestring
last_namestring
namestringFirst and last name.
emailstring | nullnull for employees who only clock with a PIN code.
role"employee" | "admin"
can_clockbooleanfalse for administrators who do not clock themselves.
status"active" | "archived"
invitation_pendingbooleantrue while an emailed invitation has not been accepted.
created_attimestampWhen the employee was added.

TimeEntry

NameTypeDescription
iduuidTime entry id.
employee_iduuidThe employee.
employee_namestring
clock_intimestampStart of the shift (UTC).
clock_outtimestamp | nullEnd of the shift (UTC). null while the shift is open.
status"open" | "closed"
net_secondsinteger | nullWorked time without breaks, in seconds. null while the shift is open.
break_secondsintegerTotal of finished breaks, in seconds.
breaksobject[]
breaks[].starttimestampStart of the break.
breaks[].endtimestamp | nullEnd of the break. null while the break is running.
note_instring | null
note_outstring | null
clock_in_sourcestring | nullHow the shift was started: api, qr, mobile, web or manual.
clock_out_sourcestring | null
clock_in_locationobject | null
clock_in_location.idstring | null
clock_in_location.namestring | null
clock_out_locationobject | null
clock_out_location.idstring | null
clock_out_location.namestring | null
correctedbooleantrue when the employer corrected the times afterwards.
lockedbooleantrue when the month was locked: the entry can no longer change.
deletedbooleantrue when the employer deleted the entry. Deleted entries never count.
awaiting_employer_closebooleantrue when the employee forgot to clock out and the employer still has to enter the end time.
created_attimestampWhen the entry was created.
updated_attimestampWhen the entry last changed.

Location

NameTypeDescription
iduuidLocation id. Use it as location_id.
namestring
addressstring | null
latitudenumber
longitudenumber
activebooleanOnly active locations can be used when clocking.

Company

NameTypeDescription
iduuidCompany id.
namestring
timezonestringIANA time zone, for example Europe/Brussels. Dates without a time are interpreted in this zone.
language"nl" | "fr" | "en" | "de" | "es"
subscriptionobject
subscription.statusstring | nullactive, trialing, past_due or canceled.
subscription.activebooleantrue when the API may be used.
subscription.planstring | null
subscription.trial_ends_attimestamp | nullEnd of the trial, when in trial.
seatsobject
seats.usedintegerPeople who clock.
seats.maxinteger | nullSeats in the plan.
api_keyobject
api_key.namestring
api_key.scopes"read" | "clock:write" | "employees:write"[]

Error

NameTypeDescription
errorrequiredobject
error.coderequiredstringStable, machine-readable code. Branch on this, never on the message.
error.messagerequiredstringExplanation for developers, in English. May change.
error.detailsobjectExtra facts for this error, for example the parameter that is wrong.
error.request_idrequiredstringQuote this when you contact support.
error.docsstring

MCP for AI assistants

With MCP (Model Context Protocol) an AI assistant works with Cloxo directly. You ask questions like "Who is at work right now?" or "How many hours did Sofie work in October?" and the assistant fetches the answer itself.

The MCP server uses the same key and the same rules as the REST API: one company per key, an active subscription or trial, the same permissions and limits.

Connecting

URL
https://app.cloxo.app/api/mcp

The server works with an API key in the Authorization header (transport: Streamable HTTP). Programs that only support signing in through OAuth cannot connect yet.

Claude Code
claude mcp add --transport http cloxo https://app.cloxo.app/api/mcp \
  --header "Authorization: Bearer cloxo_live_…"
Programs with a configuration file (such as Cursor)
{
  "mcpServers": {
    "cloxo": {
      "url": "https://app.cloxo.app/api/mcp",
      "headers": {
        "Authorization": "Bearer cloxo_live_…"
      }
    }
  }
}

If your program only supports local MCP servers, use a bridge such as mcp-remote:

mcp-remote
npx -y mcp-remote https://app.cloxo.app/api/mcp --header "Authorization: Bearer cloxo_live_…"

Tools

ToolDoesPermission
get_companyreadsReturns 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.read
list_employeesreadsLists 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.read
get_presencereadsShows, 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?".read
list_time_entriesreadsLists 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.read
get_monthly_reportreadsReturns 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.read
list_locationsreadsLists the work locations of the company (id, name, address). Use the id as location_id when clocking.read
clockchangesRecords 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.clock:write
create_employeechangesAdds 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.employees:write
  • Give an AI assistant a key with only the Read data permission, unless you want it to clock as well. A key without write permissions does not see the clock and create_employee tools.
  • Names and notes in the results were entered by people. The server tells the assistant never to read them as instructions.

Security

What you do

  • Store the key in a secrets manager or environment variable. Never in source code, an app, a web page or an email.
  • Create a separate key per integration, with only the permissions it needs.
  • Replacing a key needs no downtime: create a new key, switch over and revoke the old one.
  • Has a key leaked? Revoke it at once. It stops working immediately.
  • Choose an expiry date when the integration is temporary.

What Cloxo does

  • Cloxo stores only a hash of the key. Nobody can show it again after creation, including us.
  • Every request is confined to the company of the key. No parameter exists to choose another company.
  • All traffic runs over HTTPS. There are limits per key and against attempts with invalid keys.
  • For every clock event Cloxo records which key created it.

Versioning

The version is in the path: /v1. Within v1, things are only added: new endpoints, new optional parameters and new fields. What exists keeps its meaning.

The full description is available as OpenAPI 3.1 at /api/public/v1/openapi.json. You can import it into Postman or use it to generate a client.

Help

A question, or missing an endpoint? Email support@cloxo.app. If it concerns an error, include the request_id.