Voor ontwikkelaars

Cloxo API

Koppel je eigen software aan Cloxo. Laat medewerkers in- en uitklokken vanuit je kassa, planning of toegangscontrole, en haal uren, aanwezigheid en maandrapporten op. Cloxo verzorgt de registratie, de correcties en de rapporten.

Adres
https://app.cloxo.app/api/public/v1
Formaat
JSON over HTTPS
Limiet
120 aanvragen per minuut
Overzicht

Snel starten

In drie stappen klok je de eerste medewerker in.

  1. 1

    Maak een sleutel aan

    Een beheerder opent in Cloxo Instellingen → API & koppelingen en maakt een sleutel aan. De sleutel begint met cloxo_live_ en is maar één keer zichtbaar. Bewaar hem als een wachtwoord.

  2. 2

    Test de verbinding

    Vraag het bedrijf op. Krijg je de naam en de tijdzone terug, dan werkt de sleutel.

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

    Klok iemand in

    Haal de medewerkers op, neem de id van de juiste persoon en stuur een klokactie.

    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"}'

De medewerker staat nu ingeklokt in Cloxo. Uitklokken gaat op dezelfde manier, met "action": "clock_out".

Authenticatie

Stuur de sleutel bij elke aanvraag mee in de Authorization-header. Zet hem nooit in de URL.

HTTP
Authorization: Bearer cloxo_live_…

Een sleutel hoort bij precies één bedrijf. Je stuurt dus nergens een bedrijfs-id mee, en een sleutel kan nooit gegevens van een ander bedrijf zien. Werk je voor meerdere werkgevers, dan maakt elke werkgever zijn eigen sleutel aan.

De API is bedoeld voor verkeer tussen servers. Vanuit een webpagina kun je hem niet rechtstreeks aanroepen: een sleutel in front-endcode is voor iedereen leesbaar.

Toegang en abonnement

De API werkt alleen als de werkgever een actief Cloxo-abonnement heeft of in de proefperiode zit. Is dat niet zo, dan antwoordt elke aanvraag met 402 subscription_inactive.

Eén uitzondering: clock_out en break_end blijven altijd werken, zodat niemand ingeklokt blijft staan.

Met GET /company zie je de status in subscription.active.

Rechten

Bij het aanmaken kiest de beheerder wat een sleutel mag.

RechtNaam in CloxoGeeft toegang tot
readGegevens lezenAlle GET-endpoints: bedrijf, medewerkers, aanwezigheid, registraties, rapporten, locaties.
clock:writeIn- en uitklokkenPOST /clock-events: in- en uitklokken en pauzes.
employees:writeMedewerkers toevoegenPOST /employees: medewerkers met een pincode aanmaken.

Vraag alleen de rechten die je koppeling nodig heeft. Mist een sleutel een recht, dan krijg je 403 insufficient_scope.

Limieten

Per sleutel zijn er 120 aanvragen per minuut. Elk antwoord bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (seconden tot het venster opnieuw begint).

Boven de limiet krijg je 429 rate_limited met een Retry-After-header. Wacht dat aantal seconden en probeer opnieuw.

Aanwezigheid opvragen hoeft niet vaker dan eens per 30 seconden.

Fouten

Een fout heeft altijd dezelfde vorm. Vertak in je code op error.code; die verandert niet. De message is uitleg voor ontwikkelaars en kan wijzigen.

Vermeld het request_id als je hulp vraagt. Het staat ook in de header X-Request-Id van elk antwoord.

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

Herhaal een aanvraag alleen na 429, 500 of 503, met een pauze ertussen. Een andere fout herhalen heeft geen zin: pas eerst de aanvraag aan.

De beschrijvingen hieronder zijn in het Engels, net als de foutmeldingen van de API.

StatusCodeBetekenis
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.

Afspraken

Tijd
Alle tijdstippen zijn ISO 8601 in UTC, bijvoorbeeld 2026-10-01T06:30:00.000Z. Stuur je zelf een tijdstip, geef dan altijd de tijdzone mee (Z of +02:00). Een datum zonder tijd, zoals 2026-10-01, betekent het begin van die dag in de tijdzone van het bedrijf.
Duur
Duur staat in seconden. net_seconds is de gewerkte tijd zonder pauzes.
Periodes
from telt mee, to niet. Oktober 2026 is dus from=2026-10-01&to=2026-11-01.
Pagina's
Lijsten geven data, has_more en next_cursor. Zolang has_more waar is, herhaal je de aanvraag met cursor=<next_cursor> en dezelfde filters.
Herhalen zonder dubbels
Stuur bij POST /clock-events een Idempotency-Key-header met een unieke waarde per klokactie, bijvoorbeeld een UUID. Valt de verbinding weg, herhaal dan met dezelfde waarde: Cloxo registreert de actie één keer.
Nieuwe velden
Antwoorden kunnen er velden bij krijgen. Negeer velden die je niet kent.

Zo werkt klokken

Een medewerker is uitgeklokt, ingeklokt of in pauze. Elke klokactie brengt hem van de ene toestand naar de andere. Past een actie niet bij de toestand, dan weigert Cloxo ze met 409 en wordt er niets geregistreerd.

ActieMag wanneerAnders
clock_inuitgekloktalready_clocked_in
break_startingeklokt, niet in pauzenot_clocked_in / already_on_break
break_endin pauzenot_on_break
clock_outingeklokt of in pauzenot_clocked_in
  • Het antwoord op elke klokactie bevat de nieuwe toestand en de volledige registratie. Je hoeft die dus niet apart op te vragen.
  • Zonder timestamp gebeurt de actie nu. Met timestamp registreer je iets wat eerder gebeurde, bijvoorbeeld nadat je toestel offline was: maximaal 7 dagen terug, nooit in de toekomst, nooit vóór de vorige actie van die medewerker en nooit in een maand die in Cloxo is afgesloten.
  • Staat er nog een beurt open van een vorige dag? Stuur dan clock_out met het timestamp waarop die beurt eindigde. Weet niemand de eindtijd, dan vult de werkgever die in Cloxo in.
  • Registraties via de API krijgen de bron api. De werkgever ziet ze in Cloxo naast de registraties via QR-code en app, en kan ze daar corrigeren.

Endpoints

Alle paden beginnen met https://app.cloxo.app/api/public/v1.

De beschrijvingen hieronder zijn in het Engels, net als de foutmeldingen van de API.

get/companyRecht: 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.

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

Mogelijke fouten

  • 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/employeesRecht: 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

NaamTypeUitleg
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).
Voorbeeld
curl "https://app.cloxo.app/api/public/v1/employees" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Antwoord 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
}

Mogelijke fouten

  • 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/employeesRecht: 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

NaamTypeUitleg
first_nameverplichtstring
last_namestring
Voorbeeld
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"}'
Antwoord 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"
}

Mogelijke fouten

  • 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}Recht: read

Get one employee

Parameters

NaamTypeUitleg
idverplichtuuidThe employee id.
Voorbeeld
curl "https://app.cloxo.app/api/public/v1/employees/7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Antwoord 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"
}

Mogelijke fouten

  • 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/presenceRecht: 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

NaamTypeUitleg
employee_iduuidOnly this employee.
Voorbeeld
curl "https://app.cloxo.app/api/public/v1/presence" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Antwoord 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"
}

Mogelijke fouten

  • 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-eventsRecht: 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

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

Body

NaamTypeUitleg
actionverplicht"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.
Voorbeeld
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"}'
Antwoord 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"
  }
}

Mogelijke fouten

  • 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-entriesRecht: 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

NaamTypeUitleg
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.
Voorbeeld
curl "https://app.cloxo.app/api/public/v1/time-entries" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Antwoord 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
}

Mogelijke fouten

  • 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}Recht: read

Get one time entry

Parameters

NaamTypeUitleg
idverplichtuuidThe time entry id.
Voorbeeld
curl "https://app.cloxo.app/api/public/v1/time-entries/7c1d6a52-3f0e-4c9b-9a51-2f6f3f1f0b11" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Antwoord 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"
}

Mogelijke fouten

  • 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/monthlyRecht: 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

NaamTypeUitleg
monthverplichtstringThe 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.
Voorbeeld
curl "https://app.cloxo.app/api/public/v1/reports/monthly?month=2026-10" \
  -H "Authorization: Bearer $CLOXO_API_KEY"
Antwoord 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"
        }
      ]
    }
  ]
}

Mogelijke fouten

  • 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/locationsRecht: read

List work locations

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

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

Mogelijke fouten

  • 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.

Objecten

De velden van de objecten in de antwoorden.

Employee

NaamTypeUitleg
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

NaamTypeUitleg
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

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

Company

NaamTypeUitleg
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

NaamTypeUitleg
errorverplichtobject
error.codeverplichtstringStable, machine-readable code. Branch on this, never on the message.
error.messageverplichtstringExplanation for developers, in English. May change.
error.detailsobjectExtra facts for this error, for example the parameter that is wrong.
error.request_idverplichtstringQuote this when you contact support.
error.docsstring

MCP voor AI-assistenten

Met MCP (Model Context Protocol) werkt een AI-assistent rechtstreeks met Cloxo. Je stelt dan vragen als "Wie is er nu aan het werk?" of "Hoeveel uren werkte Sofie in oktober?" en de assistent haalt het antwoord zelf op.

De MCP-server gebruikt dezelfde sleutel en dezelfde regels als de REST-API: één bedrijf per sleutel, een actief abonnement of proefperiode, dezelfde rechten en limieten.

Verbinden

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

De server werkt met een API-sleutel in de Authorization-header (transport: Streamable HTTP). Programma's die alleen aanmelden via OAuth ondersteunen, kunnen nog niet verbinden.

Claude Code
claude mcp add --transport http cloxo https://app.cloxo.app/api/mcp \
  --header "Authorization: Bearer cloxo_live_…"
Programma's met een configuratiebestand (zoals Cursor)
{
  "mcpServers": {
    "cloxo": {
      "url": "https://app.cloxo.app/api/mcp",
      "headers": {
        "Authorization": "Bearer cloxo_live_…"
      }
    }
  }
}

Ondersteunt je programma alleen lokale MCP-servers, gebruik dan een brug zoals mcp-remote:

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

Tools

ToolDoetRecht
get_companyleestReturns 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_employeesleestLists 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_presenceleestShows, 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_entriesleestLists 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_reportleestReturns 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_locationsleestLists the work locations of the company (id, name, address). Use the id as location_id when clocking.read
clockwijzigtRecords 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_employeewijzigtAdds 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
  • Geef een AI-assistent een sleutel met alleen het recht Gegevens lezen, tenzij je wilt dat hij ook kan klokken. Een sleutel zonder schrijfrechten krijgt de tools clock en create_employee niet te zien.
  • Namen en notities in de antwoorden zijn door mensen ingevoerd. De server meldt de assistent dat hij die nooit als opdracht mag lezen.

Beveiliging

Wat jij doet

  • Bewaar de sleutel in een geheimenbeheerder of omgevingsvariabele. Nooit in broncode, een app, een webpagina of een e-mail.
  • Maak per koppeling een aparte sleutel, met alleen de rechten die nodig zijn.
  • Vervangen gaat zonder onderbreking: maak een nieuwe sleutel aan, schakel om en trek de oude in.
  • Is een sleutel gelekt? Trek hem meteen in. Hij werkt dan direct niet meer.
  • Kies een vervaldatum als de koppeling tijdelijk is.

Wat Cloxo doet

  • Cloxo bewaart alleen een hash van de sleutel. Niemand kan hem na het aanmaken nog tonen, ook wij niet.
  • Elke aanvraag is afgeschermd tot het bedrijf van de sleutel. Er bestaat geen parameter om een ander bedrijf te kiezen.
  • Alle verkeer loopt over HTTPS. Er zijn limieten per sleutel en tegen pogingen met ongeldige sleutels.
  • Bij elke klokactie houdt Cloxo bij welke sleutel ze registreerde.

Versies

De versie staat in het pad: /v1. Binnen v1 komen er alleen dingen bij: nieuwe endpoints, nieuwe optionele parameters en nieuwe velden. Wat bestaat, houdt zijn betekenis.

De volledige beschrijving staat als OpenAPI 3.1 op /api/public/v1/openapi.json. Je kunt ze importeren in Postman of gebruiken om een client te genereren.

Hulp

Een vraag, of mis je een endpoint? Mail support@cloxo.app. Gaat het over een fout, vermeld dan het request_id.