Skip to content

API reference

Time clock settings and kiosks

Switching the time clock on, who approves corrections, location (off, record, geofence) and workplaces, reminders, retention and acknowledgement per country, and shared kiosks.

5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

Time clock settings#

POST/v1/timeclock/settings.getRead

The company's time clock settings: on or off, who approves corrections, whether company corrections wait for the person's confirmation, how far back people correct themselves, late grace, offline window, location rule and workplaces, clock-out reminders, the rules and retention for each country it has a location in, and first-run setup progress. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
timeclock_settings_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

16 fields
  • enabledbooleanrequired

    The company uses the time clock: people see the clock button; until then nobody is asked to clock.

  • corrections"off" | "manager" | "hr"required

    Who approves a person's own corrections: off (applied at once, still recorded), manager (HR when there is none), hr.

  • company_edits_confirmbooleanrequired

    A manager's or HR's correction of someone's record waits for that person's confirmation (Spain's draft decree: both authorise).

  • self_daysintegerrequired

    How many days back people may ask for a correction themselves.

  • late_graceintegerrequired

    Minutes after the scheduled start before a clock-in counts as late.

  • offline_hoursintegerrequired

    Offline clockings are accepted up to this many hours after their time.

  • geolocation"off" | "record" | "geofence"required

    off (default); record (the position at the tap, ~100 m, HR only); geofence (only inside or outside a workplace).

  • geofence_requiredbooleanrequired

    geofence: clocking outside every workplace is refused (the person can ask for a correction).

  • sitesobject[]required
    6 fields
    • idstringrequired
    • namestringrequired
    • location_idstring | nullrequired
    • latnumberrequired
    • lngnumberrequired
    • radius_mintegerrequired
  • remind_clock_outbooleanrequired

    Remind people still clocked in an hour after their day (in the app, and by push when they turned it on).

  • overtime_approvalbooleanrequired

    Overtime needs approval before it's worked (spec 2026-11-17-hcm-gaps §10): requests go through Approval rules → Overtime, unapproved minutes worked beyond plan block the month close, and payroll counts only approved overtime. Off by default.

  • overtime_approval_sincestring | nullrequired

    The day approval was last switched on: days before it never need approval.

  • overtime_selfbooleanrequired

    People may ask for their own overtime (else their manager or HR asks).

  • overtime_rule"manager" | "hr" | "manager_then_hr"required

    Who approves overtime (Approval rules → Overtime): manager — the manager approves their team's, HR a manager's own and anyone's without a manager (default); hr; manager_then_hr.

  • countriesobject[]required

    The rules for each country the company has a location in (C8), with the company's overrides.

    9 fields
    • countrystringrequired
    • sourcestringrequired
    • retention_yearsintegerrequired
    • default_retention_yearsintegerrequired
    • acknowledgebooleanrequired
    • default_acknowledgebooleanrequired
    • nightobjectrequired
      2 fields
      • startstringrequired
      • endstringrequired
    • day_maxinteger | nullrequired
    • restintegerrequired
  • setupobjectrequired
    2 fields
    • stepsobject[]required
      2 fields
      • id"turn_on" | "approvals" | "places" | "retention"required
      • donebooleanrequired
    • completebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "enabled": true,
    "corrections": "manager",
    "company_edits_confirm": true,
    "self_days": 31,
    "late_grace": 10,
    "offline_hours": 72,
    "geolocation": "geofence",
    "geofence_required": false,
    "sites": [
      {
        "id": "s1",
        "name": "Madrid office",
        "location_id": "l1",
        "lat": 40.4168,
        "lng": -3.7038,
        "radius_m": 200
      }
    ],
    "remind_clock_out": true,
    "overtime_approval": true,
    "overtime_approval_since": "2026-10-01",
    "overtime_self": false,
    "overtime_rule": "manager",
    "countries": [
      {
        "country": "ES",
        "source": "Estatuto de los Trabajadores arts. 34, 35, 36",
        "retention_years": 4,
        "default_retention_years": 4,
        "acknowledge": true,
        "default_acknowledge": true,
        "night": {
          "start": "22:00",
          "end": "06:00"
        },
        "day_max": 540,
        "rest": 720
      }
    ],
    "setup": {
      "steps": [
        {
          "id": "turn_on",
          "done": true
        },
        {
          "id": "approvals",
          "done": true
        },
        {
          "id": "places",
          "done": false
        },
        {
          "id": "retention",
          "done": false
        }
      ],
      "complete": false
    }
  }
}

Change time clock settings#

POST/v1/timeclock/settings.updateWrite

Changes time clock settings (API keys and AI apps: not location, corrections, overtime approval or retention — those in the app only): enabled, overtime_approval (overtime needs approval before it's worked; switching it on applies from today), overtime_self (people ask for their own), overtime_rule (manager, hr, manager_then_hr), corrections (off, manager, hr), company_edits_confirm, self_days (0–92), late_grace (0–120), offline_hours (1–168), geolocation (off, record, geofence), geofence_required, sites (the whole list, at most 50: {id?, name, location_id?, lat, lng, radius_m 30–5000}), remind_clock_out, retention ({country: years 1–10}; a shorter period deletes older records at the next daily sweep), acknowledge ({country: true/false}), setup_done. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Location, corrections, overtime approval and retention settings are changed in the app only.
MCP tool
timeclock_settings_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • enabledboolean
  • corrections"off" | "manager" | "hr"
  • company_edits_confirmboolean
  • self_daysinteger

    From 0 to 92.

  • late_graceinteger

    From 0 to 120.

  • offline_hoursinteger

    From 1 to 168.

  • geolocation"off" | "record" | "geofence"
  • geofence_requiredboolean
  • sitesobject[]

    Up to 50 items.

    6 fields
    • idstring

      1–40 characters.

    • namestringrequired

      1–80 characters.

    • location_idstring | null

      1–120 characters.

    • latnumberrequired

      From -90 to 90.

    • lngnumberrequired

      From -180 to 180.

    • radius_mintegerrequired

      From 30 to 5000.

  • remind_clock_outboolean
  • overtime_approvalboolean
  • overtime_selfboolean
  • overtime_rule"manager" | "hr" | "manager_then_hr"
  • retentionobject
  • acknowledgeobject
  • setup_done"turn_on" | "approvals" | "places" | "retention"[]

    Up to 4 items.

Returns

16 fields
  • enabledbooleanrequired

    The company uses the time clock: people see the clock button; until then nobody is asked to clock.

  • corrections"off" | "manager" | "hr"required

    Who approves a person's own corrections: off (applied at once, still recorded), manager (HR when there is none), hr.

  • company_edits_confirmbooleanrequired

    A manager's or HR's correction of someone's record waits for that person's confirmation (Spain's draft decree: both authorise).

  • self_daysintegerrequired

    How many days back people may ask for a correction themselves.

  • late_graceintegerrequired

    Minutes after the scheduled start before a clock-in counts as late.

  • offline_hoursintegerrequired

    Offline clockings are accepted up to this many hours after their time.

  • geolocation"off" | "record" | "geofence"required

    off (default); record (the position at the tap, ~100 m, HR only); geofence (only inside or outside a workplace).

  • geofence_requiredbooleanrequired

    geofence: clocking outside every workplace is refused (the person can ask for a correction).

  • sitesobject[]required
    6 fields
    • idstringrequired
    • namestringrequired
    • location_idstring | nullrequired
    • latnumberrequired
    • lngnumberrequired
    • radius_mintegerrequired
  • remind_clock_outbooleanrequired

    Remind people still clocked in an hour after their day (in the app, and by push when they turned it on).

  • overtime_approvalbooleanrequired

    Overtime needs approval before it's worked (spec 2026-11-17-hcm-gaps §10): requests go through Approval rules → Overtime, unapproved minutes worked beyond plan block the month close, and payroll counts only approved overtime. Off by default.

  • overtime_approval_sincestring | nullrequired

    The day approval was last switched on: days before it never need approval.

  • overtime_selfbooleanrequired

    People may ask for their own overtime (else their manager or HR asks).

  • overtime_rule"manager" | "hr" | "manager_then_hr"required

    Who approves overtime (Approval rules → Overtime): manager — the manager approves their team's, HR a manager's own and anyone's without a manager (default); hr; manager_then_hr.

  • countriesobject[]required

    The rules for each country the company has a location in (C8), with the company's overrides.

    9 fields
    • countrystringrequired
    • sourcestringrequired
    • retention_yearsintegerrequired
    • default_retention_yearsintegerrequired
    • acknowledgebooleanrequired
    • default_acknowledgebooleanrequired
    • nightobjectrequired
      2 fields
      • startstringrequired
      • endstringrequired
    • day_maxinteger | nullrequired
    • restintegerrequired
  • setupobjectrequired
    2 fields
    • stepsobject[]required
      2 fields
      • id"turn_on" | "approvals" | "places" | "retention"required
      • donebooleanrequired
    • completebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "corrections": "hr",
  "company_edits_confirm": false,
  "self_days": 7,
  "late_grace": 5,
  "offline_hours": 48,
  "geolocation": "geofence",
  "geofence_required": true,
  "sites": [
    {
      "name": "Madrid office",
      "location_id": "l1",
      "lat": 40.4168,
      "lng": -3.7038,
      "radius_m": 200
    }
  ],
  "remind_clock_out": false,
  "retention": {
    "ES": 4
  },
  "acknowledge": {
    "PT": false
  },
  "setup_done": [
    "turn_on",
    "approvals"
  ]
}'
Response
{
  "data": {
    "enabled": true,
    "corrections": "hr",
    "company_edits_confirm": false,
    "self_days": 7,
    "late_grace": 5,
    "offline_hours": 48,
    "geolocation": "geofence",
    "geofence_required": true,
    "sites": [
      {
        "id": "s1",
        "name": "Madrid office",
        "location_id": "l1",
        "lat": 40.4168,
        "lng": -3.7038,
        "radius_m": 200
      }
    ],
    "remind_clock_out": false,
    "overtime_approval": true,
    "overtime_approval_since": "2026-10-01",
    "overtime_self": false,
    "overtime_rule": "manager",
    "countries": [
      {
        "country": "ES",
        "source": "Estatuto de los Trabajadores arts. 34, 35, 36",
        "retention_years": 4,
        "default_retention_years": 4,
        "acknowledge": true,
        "default_acknowledge": true,
        "night": {
          "start": "22:00",
          "end": "06:00"
        },
        "day_max": 540,
        "rest": 720
      }
    ],
    "setup": {
      "steps": [
        {
          "id": "turn_on",
          "done": true
        },
        {
          "id": "approvals",
          "done": true
        },
        {
          "id": "places",
          "done": false
        },
        {
          "id": "retention",
          "done": false
        }
      ],
      "complete": false
    }
  }
}

Kiosks#

POST/v1/timeclock/kiosks.listRead

The company's clocking kiosks (shared tablets): name, location, when it was last used, revoked or paused (too many wrong PINs). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
timeclock_kiosks_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    7 fields
    • idstringrequired
    • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • created_atstringrequired
    • last_used_atstring | nullrequired
    • revokedbooleanrequired
    • paused_untilstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/kiosks.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "k1",
        "name": "Front desk",
        "location": {
          "id": "l1",
          "name": "Madrid"
        },
        "created_at": "2026-10-01T09:00:00.000Z",
        "last_used_at": "2026-10-13T07:00:00.000Z",
        "revoked": false,
        "paused_until": null
      }
    ]
  }
}

Set up a kiosk#

POST/v1/timeclock/kiosks.createWrite

Creates a clocking kiosk for a location (spec time-clock C13) and returns its setup link, shown once: open it on the shared tablet (it keeps the device key; the key is in the link's #fragment, never sent to a server log). People at that location clock there with their own PIN. At most 50. In the app only.

Web app only
Refused for API keys and connected apps. Kiosks are set up in the app only (the result is a one-time device link).
MCP tool
timeclock_kiosks_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • namestringrequired

    1–60 characters.

  • location_idstring | null

    1–120 characters.

Returns

  • kioskobjectrequired
    7 fields
    • idstringrequired
    • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • created_atstringrequired
    • last_used_atstring | nullrequired
    • revokedbooleanrequired
    • paused_untilstring | nullrequired
  • setup_pathstringrequired

    /kiosk#k=<device key>: open on the tablet at the company address.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/kiosks.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Front desk","location_id":"l1"}'
Response
{
  "data": {
    "kiosk": {
      "id": "k1",
      "name": "Front desk",
      "location": {
        "id": "l1",
        "name": "Madrid"
      },
      "created_at": "2026-10-01T09:00:00.000Z",
      "last_used_at": "2026-10-13T07:00:00.000Z",
      "revoked": false,
      "paused_until": null
    },
    "setup_path": "/kiosk#k=k1.abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQ"
  }
}

Revoke a kiosk#

POST/v1/timeclock/kiosks.revokeWrite

Stops a kiosk at once (a lost or replaced tablet): its device key no longer works. Clockings made there stay. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
timeclock_kiosks_revoke on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • kiosk_idstringrequired

    1–120 characters.

Returns

  • revokedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/kiosks.revoke \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kiosk_id":"k1"}'
Response
{
  "data": {
    "revoked": true
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs