Skip to content

API reference

Time clock

Clocking in and out with breaks, today and time records, who's in, corrections with their history and approvals, overtime asked before it's worked and approved (or decided afterwards), month close and acknowledgement, the inspection export (registro de jornada), payroll hours and the monthly report. Machines: their own person at the current time; others only with machine consent for private data.

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

Time clock today#

POST/v1/timeclock/my.todayRead

The caller's clock: whether the company uses the time clock, their state (out, in, on a break) and since when, today's clockings, worked and expected minutes today and this week, today's schedule, the location rule (off, record, geofence — with the workplaces' names), how many corrections wait (theirs, or their confirmation of the company's), closed months to acknowledge and whether a kiosk PIN is set. For the person themself.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_my_today on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

15 fields
  • enabledbooleanrequired
  • todaystringrequired
  • timezonestringrequired
  • state"out" | "in" | "break"required
  • sincestring | nullrequired

    When the open shift started (ISO).

  • punchesobject[]required

    Today's clockings and the open shift's.

    13 fields
    • idstringrequired
    • kind"in" | "out" | "break_start" | "break_end"required
    • atstringrequired

      The instant (ISO, UTC).

    • timestringrequired

      Local time in the person's time zone (HH:MM).

    • daystringrequired
    • sourcestring (enum)required

      import: brought from the previous time-and-attendance system; terminal: a door terminal.

      One of: web, mobile, kiosk, offline, correction, api, import, terminal.

    • place"site" | "remote"required
    • late_syncbooleanrequired

      An offline clocking that reached Bizisy more than 10 minutes after its time.

    • correctedbooleanrequired

      Added by a correction.

    • voidedbooleanrequired

      Removed by a correction (kept for the history, never counted).

    • geofenceobject | nullrequired

      Geofence mode: inside a company site or not (managers and HR).

      2 fields
      • insidebooleanrequired
      • sitestring | nullrequired
    • geoobject | nullrequired

      Record mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).

      3 fields
      • latnumberrequired
      • lngnumberrequired
      • accuracy_mnumber | nullrequired
    • geo_deniedbooleanrequired
  • dayobject | nullrequired

    Today with its totals so far.

    20 fields
    • datestringrequired
    • workingbooleanrequired
    • holidaystring | nullrequired
    • company_daystring | nullrequired
    • leave"full" | "am" | "pm" | "hours"required

      Time off that day (never its type): a day-part, or hours (some hours of the day).

    • scheduleobject | nullrequired
      2 fields
      • startstring | nullrequired
      • endstring | nullrequired
    • plannedbooleanrequired

      The expected hours and start come from a published rota shift (Shifts), not the work schedule: Planned next to Clocked.

    • first_instring | nullrequired
    • last_outstring | nullrequired
    • workedintegerrequired
    • breaksintegerrequired
    • expectedintegerrequired
    • balanceintegerrequired
    • overtimeintegerrequired
    • nightintegerrequired
    • holiday_minutesintegerrequired
    • flagsstring (enum)[]required

      imported: the day's clockings came from the previous system (timeclock.records.import); unapproved_overtime: overtime worked beyond plan without approval while the company asks for it.

      One of: open, missing_out, late, no_record, on_leave, long_day, short_rest, short_break, late_sync, corrected, imported, unapproved_overtime.

    • closedbooleanrequired

      The month is closed: nothing in it changes until HR reopens it.

    • punchesobject[]required
      13 fields
      • idstringrequired
      • kind"in" | "out" | "break_start" | "break_end"required
      • atstringrequired

        The instant (ISO, UTC).

      • timestringrequired

        Local time in the person's time zone (HH:MM).

      • daystringrequired
      • sourcestring (enum)required

        import: brought from the previous time-and-attendance system; terminal: a door terminal.

        One of: web, mobile, kiosk, offline, correction, api, import, terminal.

      • place"site" | "remote"required
      • late_syncbooleanrequired

        An offline clocking that reached Bizisy more than 10 minutes after its time.

      • correctedbooleanrequired

        Added by a correction.

      • voidedbooleanrequired

        Removed by a correction (kept for the history, never counted).

      • geofenceobject | nullrequired

        Geofence mode: inside a company site or not (managers and HR).

        2 fields
        • insidebooleanrequired
        • sitestring | nullrequired
      • geoobject | nullrequired

        Record mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).

        3 fields
        • latnumberrequired
        • lngnumberrequired
        • accuracy_mnumber | nullrequired
      • geo_deniedbooleanrequired
    • overtime_approvalobject

      Overtime approval for the day, only while the company asks for it (Settings → Time clock); absent otherwise and in days before it was switched on.

      5 fields
      • approvedintegerrequired

        Overtime minutes approved for the day (before or after it was worked).

      • waitingintegerrequired

        Of the unapproved minutes, those in a request still waiting for a decision.

      • not_overtimeintegerrequired

        Minutes beyond plan an approver said are not overtime (kept as worked time, not paid as overtime).

      • unapprovedintegerrequired

        Overtime worked beyond plan nobody approved yet (waiting included): blocks the month close.

      • payableintegerrequired

        Overtime payroll counts: the worked overtime up to what was approved.

  • weekobjectrequired
    4 fields
    • fromstringrequired
    • tostringrequired
    • workedintegerrequired
    • expectedintegerrequired
  • geolocationobjectrequired
    3 fields
    • mode"off" | "record" | "geofence"required
    • requiredbooleanrequired
    • sitesobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • offline_hoursintegerrequired
  • corrections_pendingintegerrequired
  • confirm_waitingintegerrequired
  • to_acknowledgestring[]required

    Closed months (YYYY-MM) waiting for the person's acknowledgement.

  • pin_setbooleanrequired
  • overtimeobjectrequired
    2 fields
    • approvalbooleanrequired

      The company asks for overtime to be approved before it's worked.

    • selfbooleanrequired

      The person may ask for their own overtime (timeclock_overtime_request).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/my.today \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "enabled": true,
    "today": "2026-10-13",
    "timezone": "Europe/Madrid",
    "state": "in",
    "since": "2026-10-13T07:00:00.000Z",
    "punches": [
      {
        "id": "pu1",
        "kind": "in",
        "at": "2026-10-13T07:00:00.000Z",
        "time": "09:00",
        "day": "2026-10-13",
        "source": "mobile",
        "place": "site",
        "late_sync": false,
        "corrected": false,
        "voided": false,
        "geofence": {
          "inside": true,
          "site": "Madrid office"
        },
        "geo": null,
        "geo_denied": false
      }
    ],
    "day": {
      "date": "2026-10-13",
      "working": true,
      "holiday": null,
      "company_day": null,
      "leave": null,
      "schedule": {
        "start": "09:00",
        "end": "17:00"
      },
      "planned": false,
      "first_in": "09:00",
      "last_out": null,
      "worked": 480,
      "breaks": 30,
      "expected": 450,
      "balance": 30,
      "overtime": 30,
      "night": 0,
      "holiday_minutes": 0,
      "flags": [
        "open"
      ],
      "closed": false,
      "punches": [
        {
          "id": "pu1",
          "kind": "in",
          "at": "2026-10-13T07:00:00.000Z",
          "time": "09:00",
          "day": "2026-10-13",
          "source": "mobile",
          "place": "site",
          "late_sync": false,
          "corrected": false,
          "voided": false,
          "geofence": {
            "inside": true,
            "site": "Madrid office"
          },
          "geo": null,
          "geo_denied": false
        }
      ]
    },
    "week": {
      "from": "2026-10-12",
      "to": "2026-10-18",
      "worked": 600,
      "expected": 2250
    },
    "geolocation": {
      "mode": "geofence",
      "required": false,
      "sites": [
        {
          "id": "s1",
          "name": "Madrid office"
        }
      ]
    },
    "offline_hours": 72,
    "corrections_pending": 1,
    "confirm_waiting": 0,
    "to_acknowledge": [
      "2026-09"
    ],
    "pin_set": true,
    "overtime": {
      "approval": true,
      "self": false
    }
  }
}

Clock in or out#

POST/v1/timeclock/punchWrite

Records a clocking for the caller (spec time-clock C3–C5): kind in, out, break_start or break_end, in that order (clocking out also ends a break). Server time; the app's offline queue sends offline {at, client_id}: accepted up to the company's offline_hours after its time and never in the future, idempotent per client_id, marked late_sync when it arrives over 10 minutes late, sent for approval as the person's own correction when it arrives over 30 minutes late (if the company approves corrections; review then says which), refused when a later clocking exists (ask for a correction then). place (site or remote) on a clock-in. geo {lat, lng, accuracy_m} only when the company records location (C12); geo_denied when the person refused. API keys and AI apps clock their own person at server time only (no offline). Refused while the time clock is off, in a closed month, or out of order (the message says the current state).

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Only for the key's or app's own person, at the current time (no offline clockings).
MCP tool
timeclock_punch on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • kind"in" | "out" | "break_start" | "break_end"required
  • place"site" | "remote"
  • source"web" | "mobile"
  • offlineobject
    2 fields
    • atdate-timerequired

      ISO 8601 date and time (UTC).

    • client_idstringrequired

      8–64 characters. Pattern ^[A-Za-z0-9_-]+$.

  • geoobject | null
    3 fields
    • latnumberrequired

      From -90 to 90.

    • lngnumberrequired

      From -180 to 180.

    • accuracy_mnumber | null

      From 0 to 100000.

  • geo_deniedboolean

Returns

  • punchobject | nullrequired

    null when the clocking went for approval (review).

    13 fields
    • idstringrequired
    • kind"in" | "out" | "break_start" | "break_end"required
    • atstringrequired

      The instant (ISO, UTC).

    • timestringrequired

      Local time in the person's time zone (HH:MM).

    • daystringrequired
    • sourcestring (enum)required

      import: brought from the previous time-and-attendance system; terminal: a door terminal.

      One of: web, mobile, kiosk, offline, correction, api, import, terminal.

    • place"site" | "remote"required
    • late_syncbooleanrequired

      An offline clocking that reached Bizisy more than 10 minutes after its time.

    • correctedbooleanrequired

      Added by a correction.

    • voidedbooleanrequired

      Removed by a correction (kept for the history, never counted).

    • geofenceobject | nullrequired

      Geofence mode: inside a company site or not (managers and HR).

      2 fields
      • insidebooleanrequired
      • sitestring | nullrequired
    • geoobject | nullrequired

      Record mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).

      3 fields
      • latnumberrequired
      • lngnumberrequired
      • accuracy_mnumber | nullrequired
    • geo_deniedbooleanrequired
  • state"out" | "in" | "break"required
  • duplicatebooleanrequired

    This offline clocking was already recorded (a replayed queue).

  • reviewobject | nullrequired

    An offline clocking that arrived more than 30 minutes after its time: it waits for approval as the person's own correction (when the company approves corrections).

    1 field
    • correction_idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/punch \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "kind": "out",
  "offline": {
    "at": "2026-10-13T15:30:00.000Z",
    "client_id": "c-0f6a1d2e9b"
  },
  "geo_denied": true
}'
Response
{
  "data": {
    "punch": {
      "id": "pu1",
      "kind": "in",
      "at": "2026-10-13T07:00:00.000Z",
      "time": "09:00",
      "day": "2026-10-13",
      "source": "mobile",
      "place": "site",
      "late_sync": false,
      "corrected": false,
      "voided": false,
      "geofence": {
        "inside": true,
        "site": "Madrid office"
      },
      "geo": null,
      "geo_denied": false
    },
    "state": "in",
    "duplicate": false,
    "review": null
  }
}

Time records#

POST/v1/timeclock/records.listRead

A person's time records between from and to (at most 93 days; default the caller): each day with the clockings (removed ones too, marked voided, for the history), first in and last out, worked, breaks, expected, balance, overtime, night and holiday minutes, flags (open, missing_out, late, no_record, on_leave — never its type —, long_day, short_rest, short_break, late_sync, corrected, imported — from the previous system) and whether its month is closed; totals; the months' status; working-time limits on the clocked hours (limits: the 48-hour average, weekly rest, the yearly overtime cap per country, with the law; warnings only). Who: the person; their managers; owners, admins and HR. API keys and AI apps: their own person, or others only with the company's machine consent for private data; never coordinates.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Other people's records only with the company's machine consent for private data; never locations.
MCP tool
timeclock_records_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring

    1–120 characters.

  • fromstringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • timezonestringrequired
  • daysobject[]required
    20 fields
    • datestringrequired
    • workingbooleanrequired
    • holidaystring | nullrequired
    • company_daystring | nullrequired
    • leave"full" | "am" | "pm" | "hours"required

      Time off that day (never its type): a day-part, or hours (some hours of the day).

    • scheduleobject | nullrequired
      2 fields
      • startstring | nullrequired
      • endstring | nullrequired
    • plannedbooleanrequired

      The expected hours and start come from a published rota shift (Shifts), not the work schedule: Planned next to Clocked.

    • first_instring | nullrequired
    • last_outstring | nullrequired
    • workedintegerrequired
    • breaksintegerrequired
    • expectedintegerrequired
    • balanceintegerrequired
    • overtimeintegerrequired
    • nightintegerrequired
    • holiday_minutesintegerrequired
    • flagsstring (enum)[]required

      imported: the day's clockings came from the previous system (timeclock.records.import); unapproved_overtime: overtime worked beyond plan without approval while the company asks for it.

      One of: open, missing_out, late, no_record, on_leave, long_day, short_rest, short_break, late_sync, corrected, imported, unapproved_overtime.

    • closedbooleanrequired

      The month is closed: nothing in it changes until HR reopens it.

    • punchesobject[]required
      13 fields
      • idstringrequired
      • kind"in" | "out" | "break_start" | "break_end"required
      • atstringrequired

        The instant (ISO, UTC).

      • timestringrequired

        Local time in the person's time zone (HH:MM).

      • daystringrequired
      • sourcestring (enum)required

        import: brought from the previous time-and-attendance system; terminal: a door terminal.

        One of: web, mobile, kiosk, offline, correction, api, import, terminal.

      • place"site" | "remote"required
      • late_syncbooleanrequired

        An offline clocking that reached Bizisy more than 10 minutes after its time.

      • correctedbooleanrequired

        Added by a correction.

      • voidedbooleanrequired

        Removed by a correction (kept for the history, never counted).

      • geofenceobject | nullrequired

        Geofence mode: inside a company site or not (managers and HR).

        2 fields
        • insidebooleanrequired
        • sitestring | nullrequired
      • geoobject | nullrequired

        Record mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).

        3 fields
        • latnumberrequired
        • lngnumberrequired
        • accuracy_mnumber | nullrequired
      • geo_deniedbooleanrequired
    • overtime_approvalobject

      Overtime approval for the day, only while the company asks for it (Settings → Time clock); absent otherwise and in days before it was switched on.

      5 fields
      • approvedintegerrequired

        Overtime minutes approved for the day (before or after it was worked).

      • waitingintegerrequired

        Of the unapproved minutes, those in a request still waiting for a decision.

      • not_overtimeintegerrequired

        Minutes beyond plan an approver said are not overtime (kept as worked time, not paid as overtime).

      • unapprovedintegerrequired

        Overtime worked beyond plan nobody approved yet (waiting included): blocks the month close.

      • payableintegerrequired

        Overtime payroll counts: the worked overtime up to what was approved.

  • totalsobjectrequired

    Minutes, and how many days carry each flag.

    11 fields
    • workedintegerrequired
    • expectedintegerrequired
    • balanceintegerrequired
    • overtimeintegerrequired
    • nightintegerrequired
    • holidayintegerrequired
    • breaksintegerrequired
    • days_workedintegerrequired
    • flagsobjectrequired
    • overtime_payableinteger

      While overtime needs approval: the overtime payroll counts (approved).

    • overtime_unapprovedinteger

      While overtime needs approval: overtime worked beyond plan nobody approved yet.

  • monthsobject[]required
    4 fields
    • monthstringrequired
    • status"open" | "closed" | "reopened"required
    • acknowledged_atstring | nullrequired
    • digeststring | nullrequired
  • limitsobject[]required

    Working-time limits on the clocked hours (the 48-hour average up to `to`, each finished week's rest, overtime this calendar year against the country's cap), with the law. Warnings only.

    9 fields
    • kind"average_week" | "weekly_rest" | "overtime_year"required

      average_week: the average week over the reference period passes 48 hours (or the country's limit); weekly_rest: a week without the weekly rest the law asks for; overtime_year: overtime this calendar year near (80 %) or over the country's yearly cap.

    • level"over" | "near"required
    • valueintegerrequired

      average_week: average minutes a week; weekly_rest: the longest unbroken rest that week in minutes, or the rest days (unit days); overtime_year: overtime minutes this year.

    • limitintegerrequired
    • unit"minutes" | "days"required
    • fromstringrequired
    • tostringrequired
    • lawstringrequired

      The legal basis, as cited.

    • notestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/records.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p3","from":"2026-10-12","to":"2026-10-18"}'
Response
{
  "data": {
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "timezone": "Europe/Madrid",
    "days": [
      {
        "date": "2026-10-13",
        "working": true,
        "holiday": null,
        "company_day": null,
        "leave": null,
        "schedule": {
          "start": "09:00",
          "end": "17:00"
        },
        "planned": false,
        "first_in": "09:00",
        "last_out": "17:30",
        "worked": 480,
        "breaks": 30,
        "expected": 450,
        "balance": 30,
        "overtime": 30,
        "night": 0,
        "holiday_minutes": 0,
        "flags": [
          "corrected"
        ],
        "closed": false,
        "punches": [
          {
            "id": "pu1",
            "kind": "in",
            "at": "2026-10-13T07:00:00.000Z",
            "time": "09:00",
            "day": "2026-10-13",
            "source": "mobile",
            "place": "site",
            "late_sync": false,
            "corrected": false,
            "voided": false,
            "geofence": {
              "inside": true,
              "site": "Madrid office"
            },
            "geo": null,
            "geo_denied": false
          },
          {
            "id": "pu3",
            "kind": "break_start",
            "at": "2026-10-13T11:00:00.000Z",
            "time": "13:00",
            "day": "2026-10-13",
            "source": "mobile",
            "place": "site",
            "late_sync": false,
            "corrected": false,
            "voided": false,
            "geofence": null,
            "geo": null,
            "geo_denied": false
          },
          {
            "id": "pu4",
            "kind": "break_end",
            "at": "2026-10-13T11:30:00.000Z",
            "time": "13:30",
            "day": "2026-10-13",
            "source": "mobile",
            "place": "site",
            "late_sync": false,
            "corrected": false,
            "voided": false,
            "geofence": null,
            "geo": null,
            "geo_denied": false
          },
          {
            "id": "pu2",
            "kind": "out",
            "at": "2026-10-13T15:30:00.000Z",
            "time": "17:30",
            "day": "2026-10-13",
            "source": "correction",
            "place": null,
            "late_sync": false,
            "corrected": true,
            "voided": false,
            "geofence": null,
            "geo": null,
            "geo_denied": false
          }
        ]
      },
      {
        "date": "2026-10-13",
        "working": true,
        "holiday": null,
        "company_day": null,
        "leave": null,
        "schedule": {
          "start": "09:00",
          "end": "17:00"
        },
        "planned": false,
        "first_in": "09:00",
        "last_out": "17:30",
        "worked": 600,
        "breaks": 30,
        "expected": 450,
        "balance": 150,
        "overtime": 150,
        "night": 0,
        "holiday_minutes": 0,
        "flags": [
          "unapproved_overtime"
        ],
        "closed": false,
        "punches": [
          {
            "id": "pu1",
            "kind": "in",
            "at": "2026-10-13T07:00:00.000Z",
            "time": "09:00",
            "day": "2026-10-13",
            "source": "mobile",
            "place": "site",
            "late_sync": false,
            "corrected": false,
            "voided": false,
            "geofence": {
              "inside": true,
              "site": "Madrid office"
            },
            "geo": null,
            "geo_denied": false
          },
          {
            "id": "pu3",
            "kind": "break_start",
            "at": "2026-10-13T11:00:00.000Z",
            "time": "13:00",
            "day": "2026-10-13",
            "source": "mobile",
            "place": "site",
            "late_sync": false,
            "corrected": false,
            "voided": false,
            "geofence": null,
            "geo": null,
            "geo_denied": false
          },
          {
            "id": "pu4",
            "kind": "break_end",
            "at": "2026-10-13T11:30:00.000Z",
            "time": "13:30",
            "day": "2026-10-13",
            "source": "mobile",
            "place": "site",
            "late_sync": false,
            "corrected": false,
            "voided": false,
            "geofence": null,
            "geo": null,
            "geo_denied": false
          },
          {
            "id": "pu2",
            "kind": "out",
            "at": "2026-10-13T15:30:00.000Z",
            "time": "17:30",
            "day": "2026-10-13",
            "source": "correction",
            "place": null,
            "late_sync": false,
            "corrected": true,
            "voided": false,
            "geofence": null,
            "geo": null,
            "geo_denied": false
          }
        ],
        "overtime_approval": {
          "approved": 120,
          "waiting": 0,
          "not_overtime": 0,
          "unapproved": 30,
          "payable": 120
        }
      }
    ],
    "totals": {
      "worked": 9120,
      "expected": 9450,
      "balance": -330,
      "overtime": 60,
      "night": 0,
      "holiday": 0,
      "breaks": 600,
      "days_worked": 20,
      "flags": {
        "corrected": 1,
        "no_record": 1
      },
      "overtime_payable": 120,
      "overtime_unapproved": 30
    },
    "months": [
      {
        "month": "2026-10",
        "status": "open",
        "acknowledged_at": null,
        "digest": null
      }
    ],
    "limits": [
      {
        "kind": "overtime_year",
        "level": "near",
        "value": 4140,
        "limit": 4800,
        "unit": "minutes",
        "from": "2026-01-01",
        "to": "2026-10-31",
        "law": "Estatuto de los Trabajadores art. 35.2",
        "note": "Overtime compensated with rest within four months does not count."
      }
    ]
  }
}

Who's in#

POST/v1/timeclock/team.dayRead

The team day view (spec time-clock): for a day (default today), each person the caller may see — their reports for managers, everyone for owners, admins and HR — with their state at the end of that day (now, today: out, in, on a break), since when, first in and last out, worked and expected minutes, today's schedule, time off (never its type) or holiday, flags (late, missing_out, no_record, …) and overdue (still clocked in an hour after their scheduled end or for more than 10 hours: probably forgot to clock out). Filters: unit_id, location_id, state. Colleagues see nobody. API keys and AI apps only with the company's machine consent for private data. Use it for "who forgot to clock out today": state in or break with overdue true, plus missing_out.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_team_day on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • datestring

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • unit_idstring

    1–120 characters.

  • location_idstring

    1–120 characters.

  • state"out" | "in" | "break"

Returns

  • datestringrequired
  • todaystringrequired
  • peopleobject[]required
    13 fields
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • state"out" | "in" | "break"required

      At the end of that day (now, today).

    • sincestring | nullrequired

      When the open shift started (ISO).

    • overduebooleanrequired

      Still clocked in an hour after their scheduled end, or for more than 10 hours: probably forgot to clock out.

    • first_instring | nullrequired
    • last_outstring | nullrequired
    • workedintegerrequired
    • expectedintegerrequired
    • scheduleobject | nullrequired
      2 fields
      • startstring | nullrequired
      • endstring | nullrequired
    • plannedbooleanrequired

      The expected hours come from a published rota shift (Shifts): Planned next to Clocked.

    • leave"full" | "am" | "pm" | "hours"required

      Time off that day (never its type): hours = some hours of it.

    • holidaystring | nullrequired
    • flagsstring[]required
  • countsobjectrequired
    8 fields
    • inintegerrequired
    • breakintegerrequired
    • outintegerrequired
    • lateintegerrequired
    • overdueintegerrequired
    • missing_outintegerrequired
    • no_recordintegerrequired
    • on_leaveintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/team.day \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-10-13","unit_id":"u1","location_id":"l1","state":"in"}'
Response
{
  "data": {
    "date": "2026-10-13",
    "today": "2026-10-13",
    "people": [
      {
        "person": {
          "id": "p3",
          "name": "Carl Reis",
          "unit": {
            "id": "u1",
            "name": "Operations"
          }
        },
        "state": "in",
        "since": "2026-10-13T07:00:00.000Z",
        "overdue": false,
        "first_in": "09:00",
        "last_out": null,
        "worked": 120,
        "expected": 450,
        "schedule": {
          "start": "09:00",
          "end": "17:00"
        },
        "planned": false,
        "leave": null,
        "holiday": null,
        "flags": [
          "open"
        ]
      }
    ],
    "counts": {
      "in": 1,
      "break": 0,
      "out": 0,
      "late": 0,
      "overdue": 0,
      "missing_out": 0,
      "no_record": 0,
      "on_leave": 0
    }
  }
}

Ask for a time correction#

POST/v1/timeclock/corrections.requestWrite

Corrects a day of time records with a reason (spec time-clock C6): changes add a clocking ({op: add, kind, time HH:MM local, next_day for after midnight}) or remove one ({op: void, punch_id} — it stays in the history). The result must be a valid day (in → breaks → out). For yourself (default): within the company's self_days back; approved by your manager or HR per the company's setting, or applied at once when approvals are off. A manager (for their reports) or HR (anyone) correcting someone else: waits for that person's confirmation when the company asks for it, else applied at once. One pending correction per day; at most 20 pending per person; refused in a closed month. API keys and AI apps only for their own person.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Only for the key's or app's own person; correcting someone else needs a person signed in.
MCP tool
timeclock_corrections_request on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstring

    1–120 characters.

  • daystringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • changesobject[]required

    1–12 items.

    6 fields (one of several shapes)

    Option 1

    • op"add"required
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired

      Local time (HH:MM) in the person's time zone.

      Pattern ^([01]\d|2[0-3]):[0-5]\d$.

    • next_dayboolean

      The time is after midnight (a night shift).

    Option 2

    • op"void"required
    • punch_idstringrequired

      A clocking of that day to remove (it stays in the history).

      1–120 characters.

  • reasonstringrequired

    3–500 characters.

Returns

19 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • reasonstringrequired
  • status"pending" | "applied" | "declined" | "cancelled"required
  • changesobject[]required
    4 fields
    • op"add" | "void"required
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestring | nullrequired
    • punch_idstring | nullrequired
  • beforeobject[]required

    The day's clockings before the correction.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • afterobject[]required

    The day's clockings with it.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • waiting_for"manager" | "hr" | "worker"required

    worker: the person confirms a correction their manager or HR made.

  • approverobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • decidedobject | nullrequired
    4 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • decision"approved" | "declined"required
    • commentstring | nullrequired
  • disputeobject | nullrequired

    The person disagreed with the company's correction (kept with it).

    2 fields
    • commentstring | nullrequired
    • atstringrequired
  • appliedobject | nullrequired
    2 fields
    • atstringrequired
    • anywaybooleanrequired

      HR applied it although the person disagreed.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • can_apply_anywaybooleanrequired
  • importedbooleanrequired

    A day of the clock-history import, waiting for the person to confirm it (or applied).

  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/corrections.request \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p3",
  "day": "2026-10-13",
  "changes": [
    {
      "op": "void",
      "punch_id": "pu1"
    },
    {
      "op": "add",
      "kind": "in",
      "time": "08:30"
    },
    {
      "op": "add",
      "kind": "out",
      "time": "01:00",
      "next_day": true
    }
  ],
  "reason": "Night shift"
}'
Response
{
  "data": {
    "id": "co1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-13",
    "reason": "Night shift",
    "status": "pending",
    "changes": [
      {
        "op": "add",
        "kind": "out",
        "time": "17:30",
        "punch_id": null
      }
    ],
    "before": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      }
    ],
    "after": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      },
      {
        "kind": "out",
        "time": "17:30",
        "at": "2026-10-13T15:30:00.000Z",
        "source": "correction"
      }
    ],
    "waiting_for": "manager",
    "approver": {
      "id": "p2",
      "name": "Bea Lopes"
    },
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-14T08:00:00.000Z"
    },
    "decided": null,
    "dispute": null,
    "applied": null,
    "can_decide": true,
    "can_cancel": false,
    "can_apply_anyway": false,
    "imported": false,
    "created_at": "2026-10-14T08:00:00.000Z"
  }
}

Time corrections#

POST/v1/timeclock/corrections.listRead

Corrections the caller may see: their own; their reports' (managers); everyone's (owners, admins, HR). Each with the day, reason, before and after, who asked and as what, who decides now (manager, hr, or worker — the person confirming the company's correction), the decision, a disagreement and whether HR applied it anyway. Filters: status, person_id, waiting_for_me (the ones the caller decides now), from/to (days). Newest first; at most 200. API keys and AI apps: their own person, others only with the company's machine consent for private data.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_corrections_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"pending" | "applied" | "declined" | "cancelled"
  • person_idstring

    1–120 characters.

  • waiting_for_meboolean
  • fromstring

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • itemsobject[]required
    19 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • daystringrequired
    • reasonstringrequired
    • status"pending" | "applied" | "declined" | "cancelled"required
    • changesobject[]required
      4 fields
      • op"add" | "void"required
      • kind"in" | "out" | "break_start" | "break_end"required
      • timestring | nullrequired
      • punch_idstring | nullrequired
    • beforeobject[]required

      The day's clockings before the correction.

      4 fields
      • kind"in" | "out" | "break_start" | "break_end"required
      • timestringrequired
      • atstringrequired
      • sourcestringrequired
    • afterobject[]required

      The day's clockings with it.

      4 fields
      • kind"in" | "out" | "break_start" | "break_end"required
      • timestringrequired
      • atstringrequired
      • sourcestringrequired
    • waiting_for"manager" | "hr" | "worker"required

      worker: the person confirms a correction their manager or HR made.

    • approverobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • requestedobjectrequired
      3 fields
      • as"self" | "manager" | "hr"required
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
    • decidedobject | nullrequired
      4 fields
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
      • decision"approved" | "declined"required
      • commentstring | nullrequired
    • disputeobject | nullrequired

      The person disagreed with the company's correction (kept with it).

      2 fields
      • commentstring | nullrequired
      • atstringrequired
    • appliedobject | nullrequired
      2 fields
      • atstringrequired
      • anywaybooleanrequired

        HR applied it although the person disagreed.

    • can_decidebooleanrequired
    • can_cancelbooleanrequired
    • can_apply_anywaybooleanrequired
    • importedbooleanrequired

      A day of the clock-history import, waiting for the person to confirm it (or applied).

    • created_atstringrequired
  • waiting_for_meintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/corrections.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "pending",
  "person_id": "p3",
  "waiting_for_me": true,
  "from": "2026-10-01",
  "to": "2026-10-31"
}'
Response
{
  "data": {
    "items": [
      {
        "id": "co1",
        "person": {
          "id": "p3",
          "name": "Carl Reis"
        },
        "day": "2026-10-13",
        "reason": "Forgot to clock out",
        "status": "pending",
        "changes": [
          {
            "op": "add",
            "kind": "out",
            "time": "17:30",
            "punch_id": null
          }
        ],
        "before": [
          {
            "kind": "in",
            "time": "09:00",
            "at": "2026-10-13T07:00:00.000Z",
            "source": "mobile"
          }
        ],
        "after": [
          {
            "kind": "in",
            "time": "09:00",
            "at": "2026-10-13T07:00:00.000Z",
            "source": "mobile"
          },
          {
            "kind": "out",
            "time": "17:30",
            "at": "2026-10-13T15:30:00.000Z",
            "source": "correction"
          }
        ],
        "waiting_for": "manager",
        "approver": {
          "id": "p2",
          "name": "Bea Lopes"
        },
        "requested": {
          "as": "self",
          "by": {
            "id": "p3",
            "name": "Carl Reis"
          },
          "at": "2026-10-14T08:00:00.000Z"
        },
        "decided": null,
        "dispute": null,
        "applied": null,
        "can_decide": true,
        "can_cancel": false,
        "can_apply_anyway": false,
        "imported": false,
        "created_at": "2026-10-14T08:00:00.000Z"
      }
    ],
    "waiting_for_me": 1
  }
}

Decide on a time correction#

POST/v1/timeclock/corrections.decideWrite

Approves or declines the correction waiting for the caller: as the manager asked (or anyone above them in the chain) or HR for a person's own request — never your own; or, as the person, confirms (approve) or disagrees with (decline, a comment helps) a correction your manager or HR made. Approving applies it; a disagreement is recorded with it and HR may apply it anyway. In the app only.

Web app only
Refused for API keys and connected apps. Deciding or confirming a time correction needs a person signed in to Bizisy.
MCP tool
timeclock_corrections_decide on My Workplace, 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

  • correction_idstringrequired

    1–120 characters.

  • decision"approve" | "decline"required
  • commentstring | null

    Up to 500 characters.

Returns

19 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • reasonstringrequired
  • status"pending" | "applied" | "declined" | "cancelled"required
  • changesobject[]required
    4 fields
    • op"add" | "void"required
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestring | nullrequired
    • punch_idstring | nullrequired
  • beforeobject[]required

    The day's clockings before the correction.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • afterobject[]required

    The day's clockings with it.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • waiting_for"manager" | "hr" | "worker"required

    worker: the person confirms a correction their manager or HR made.

  • approverobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • decidedobject | nullrequired
    4 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • decision"approved" | "declined"required
    • commentstring | nullrequired
  • disputeobject | nullrequired

    The person disagreed with the company's correction (kept with it).

    2 fields
    • commentstring | nullrequired
    • atstringrequired
  • appliedobject | nullrequired
    2 fields
    • atstringrequired
    • anywaybooleanrequired

      HR applied it although the person disagreed.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • can_apply_anywaybooleanrequired
  • importedbooleanrequired

    A day of the clock-history import, waiting for the person to confirm it (or applied).

  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/corrections.decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"correction_id":"co1","decision":"decline","comment":"I left at 17:30"}'
Response
{
  "data": {
    "id": "co1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-13",
    "reason": "Forgot to clock out",
    "status": "applied",
    "changes": [
      {
        "op": "add",
        "kind": "out",
        "time": "17:30",
        "punch_id": null
      }
    ],
    "before": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      }
    ],
    "after": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      },
      {
        "kind": "out",
        "time": "17:30",
        "at": "2026-10-13T15:30:00.000Z",
        "source": "correction"
      }
    ],
    "waiting_for": null,
    "approver": null,
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-14T08:00:00.000Z"
    },
    "decided": {
      "by": {
        "id": "p2",
        "name": "Bea Lopes"
      },
      "at": "2026-10-14T09:00:00.000Z",
      "decision": "approved",
      "comment": null
    },
    "dispute": null,
    "applied": {
      "at": "2026-10-14T09:00:00.000Z",
      "anyway": false
    },
    "can_decide": false,
    "can_cancel": false,
    "can_apply_anyway": false,
    "imported": false,
    "created_at": "2026-10-14T08:00:00.000Z"
  }
}

Apply a disputed correction#

POST/v1/timeclock/corrections.apply_anywayWrite

Applies a correction the person disagreed with (spec time-clock C6, ES2: recorded with the disagreement). Owners, admins and HR, in the app, with a comment saying why. Never your own record.

Web app only
Refused for API keys and connected apps. Applying a disputed correction needs HR signed in to Bizisy.
MCP tool
timeclock_corrections_apply_anyway 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

  • correction_idstringrequired

    1–120 characters.

  • commentstringrequired

    3–500 characters.

Returns

19 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • reasonstringrequired
  • status"pending" | "applied" | "declined" | "cancelled"required
  • changesobject[]required
    4 fields
    • op"add" | "void"required
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestring | nullrequired
    • punch_idstring | nullrequired
  • beforeobject[]required

    The day's clockings before the correction.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • afterobject[]required

    The day's clockings with it.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • waiting_for"manager" | "hr" | "worker"required

    worker: the person confirms a correction their manager or HR made.

  • approverobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • decidedobject | nullrequired
    4 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • decision"approved" | "declined"required
    • commentstring | nullrequired
  • disputeobject | nullrequired

    The person disagreed with the company's correction (kept with it).

    2 fields
    • commentstring | nullrequired
    • atstringrequired
  • appliedobject | nullrequired
    2 fields
    • atstringrequired
    • anywaybooleanrequired

      HR applied it although the person disagreed.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • can_apply_anywaybooleanrequired
  • importedbooleanrequired

    A day of the clock-history import, waiting for the person to confirm it (or applied).

  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/corrections.apply_anyway \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"correction_id":"co1","comment":"The door log shows 15:02"}'
Response
{
  "data": {
    "id": "co1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-13",
    "reason": "Forgot to clock out",
    "status": "applied",
    "changes": [
      {
        "op": "add",
        "kind": "out",
        "time": "17:30",
        "punch_id": null
      }
    ],
    "before": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      }
    ],
    "after": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      },
      {
        "kind": "out",
        "time": "17:30",
        "at": "2026-10-13T15:30:00.000Z",
        "source": "correction"
      }
    ],
    "waiting_for": null,
    "approver": null,
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-14T08:00:00.000Z"
    },
    "decided": null,
    "dispute": {
      "comment": "I left at 17:30",
      "at": "2026-10-14T10:00:00.000Z"
    },
    "applied": {
      "at": "2026-10-14T11:00:00.000Z",
      "anyway": true
    },
    "can_decide": false,
    "can_cancel": false,
    "can_apply_anyway": false,
    "imported": false,
    "created_at": "2026-10-14T08:00:00.000Z"
  }
}

Cancel a time correction#

POST/v1/timeclock/corrections.cancelWrite

Withdraws a correction still waiting: the person who asked for their own, or HR for a correction HR made. Nothing changes in the records.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_corrections_cancel on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • correction_idstringrequired

    1–120 characters.

Returns

19 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • reasonstringrequired
  • status"pending" | "applied" | "declined" | "cancelled"required
  • changesobject[]required
    4 fields
    • op"add" | "void"required
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestring | nullrequired
    • punch_idstring | nullrequired
  • beforeobject[]required

    The day's clockings before the correction.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • afterobject[]required

    The day's clockings with it.

    4 fields
    • kind"in" | "out" | "break_start" | "break_end"required
    • timestringrequired
    • atstringrequired
    • sourcestringrequired
  • waiting_for"manager" | "hr" | "worker"required

    worker: the person confirms a correction their manager or HR made.

  • approverobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • decidedobject | nullrequired
    4 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • decision"approved" | "declined"required
    • commentstring | nullrequired
  • disputeobject | nullrequired

    The person disagreed with the company's correction (kept with it).

    2 fields
    • commentstring | nullrequired
    • atstringrequired
  • appliedobject | nullrequired
    2 fields
    • atstringrequired
    • anywaybooleanrequired

      HR applied it although the person disagreed.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • can_apply_anywaybooleanrequired
  • importedbooleanrequired

    A day of the clock-history import, waiting for the person to confirm it (or applied).

  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/corrections.cancel \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"correction_id":"co1"}'
Response
{
  "data": {
    "id": "co1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-13",
    "reason": "Forgot to clock out",
    "status": "cancelled",
    "changes": [
      {
        "op": "add",
        "kind": "out",
        "time": "17:30",
        "punch_id": null
      }
    ],
    "before": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      }
    ],
    "after": [
      {
        "kind": "in",
        "time": "09:00",
        "at": "2026-10-13T07:00:00.000Z",
        "source": "mobile"
      },
      {
        "kind": "out",
        "time": "17:30",
        "at": "2026-10-13T15:30:00.000Z",
        "source": "correction"
      }
    ],
    "waiting_for": null,
    "approver": null,
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-14T08:00:00.000Z"
    },
    "decided": null,
    "dispute": null,
    "applied": null,
    "can_decide": false,
    "can_cancel": false,
    "can_apply_anyway": false,
    "imported": false,
    "created_at": "2026-10-14T08:00:00.000Z"
  }
}

Month close#

POST/v1/timeclock/months.listRead

For a month, each person the caller may see (reports for managers, everyone for owners, admins and HR) with the month's status (open, closed, reopened), totals in minutes, what blocks closing (days with a missing clock-out, corrections waiting), the acknowledgement, and working-time limits on the clocked hours (limits: the 48-hour average over the country's reference period, weekly rest, the yearly overtime cap such as ES 80 h or PT 150/175 h, each with the law; warnings, never blocks). Filters: unit_id, location_id. API keys and AI apps only with the company's machine consent for private data.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_months_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • unit_idstring

    1–120 characters.

  • location_idstring

    1–120 characters.

Returns

  • monthstringrequired
  • peopleobject[]required
    8 fields
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • status"open" | "closed" | "reopened"required
    • totalsobjectrequired

      Minutes, and how many days carry each flag.

      11 fields
      • workedintegerrequired
      • expectedintegerrequired
      • balanceintegerrequired
      • overtimeintegerrequired
      • nightintegerrequired
      • holidayintegerrequired
      • breaksintegerrequired
      • days_workedintegerrequired
      • flagsobjectrequired
      • overtime_payableinteger

        While overtime needs approval: the overtime payroll counts (approved).

      • overtime_unapprovedinteger

        While overtime needs approval: overtime worked beyond plan nobody approved yet.

    • issuesobjectrequired
      3 fields
      • open_shiftsintegerrequired

        Days with a missing clock-out (close skips the person).

      • pending_correctionsintegerrequired
      • unapproved_overtimeintegerrequired

        While overtime needs approval: minutes worked beyond plan nobody approved yet (close skips the person; timeclock_overtime_unapproved lists the days).

    • ack_requiredbooleanrequired
    • acknowledged_atstring | nullrequired
    • closed_atstring | nullrequired
    • limitsobject[]required

      Working-time limits on the clocked hours (the 48-hour average, weekly rest, the yearly overtime cap), with the law: warnings for HR before closing; they never block.

      9 fields
      • kind"average_week" | "weekly_rest" | "overtime_year"required

        average_week: the average week over the reference period passes 48 hours (or the country's limit); weekly_rest: a week without the weekly rest the law asks for; overtime_year: overtime this calendar year near (80 %) or over the country's yearly cap.

      • level"over" | "near"required
      • valueintegerrequired

        average_week: average minutes a week; weekly_rest: the longest unbroken rest that week in minutes, or the rest days (unit days); overtime_year: overtime minutes this year.

      • limitintegerrequired
      • unit"minutes" | "days"required
      • fromstringrequired
      • tostringrequired
      • lawstringrequired

        The legal basis, as cited.

      • notestring | nullrequired
  • closablebooleanrequired

    The month has ended.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/months.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"month":"2026-10","unit_id":"u1","location_id":"l1"}'
Response
{
  "data": {
    "month": "2026-10",
    "closable": true,
    "people": [
      {
        "person": {
          "id": "p3",
          "name": "Carl Reis",
          "unit": {
            "id": "u1",
            "name": "Operations"
          }
        },
        "status": "open",
        "totals": {
          "worked": 9120,
          "expected": 9450,
          "balance": -330,
          "overtime": 60,
          "night": 0,
          "holiday": 0,
          "breaks": 600,
          "days_worked": 20,
          "flags": {
            "corrected": 1,
            "no_record": 1
          }
        },
        "issues": {
          "open_shifts": 0,
          "pending_corrections": 1,
          "unapproved_overtime": 30
        },
        "ack_required": true,
        "acknowledged_at": null,
        "closed_at": null,
        "limits": [
          {
            "kind": "overtime_year",
            "level": "near",
            "value": 4140,
            "limit": 4800,
            "unit": "minutes",
            "from": "2026-01-01",
            "to": "2026-10-31",
            "law": "Estatuto de los Trabajadores art. 35.2",
            "note": "Overtime compensated with rest within four months does not count."
          }
        ]
      }
    ]
  }
}

A month of time records#

POST/v1/timeclock/months.getRead

A person's month (default the caller): its status, the sealed summary when closed (every day, totals, corrections) with its SHA-256 digest, or the live one while open; whether the person must acknowledge it and when they did; the close/reopen history; working-time limits on the clocked hours up to the month's end (limits, with the law). Who: the person, their managers, owners, admins and HR.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_months_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring

    1–120 characters.

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

Returns

11 fields
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • monthstringrequired
  • status"open" | "closed" | "reopened"required
  • digeststring | nullrequired

    SHA-256 of the sealed summary (closed months).

  • closed_atstring | nullrequired
  • ack_requiredbooleanrequired
  • acknowledged_atstring | nullrequired
  • can_acknowledgebooleanrequired
  • summaryobjectrequired

    The sealed summary when closed; the live one otherwise.

    9 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • monthstringrequired
    • timezonestringrequired
    • countrystring | nullrequired
    • generated_atstringrequired
    • retention_yearsintegerrequired
    • daysobject[]required
      20 fields
      • datestringrequired
      • workingbooleanrequired
      • holidaystring | nullrequired
      • company_daystring | nullrequired
      • leave"full" | "am" | "pm" | "hours"required

        Time off that day (never its type): a day-part, or hours (some hours of the day).

      • scheduleobject | nullrequired
        2 fields
        • startstring | nullrequired
        • endstring | nullrequired
      • plannedbooleanrequired

        The expected hours and start come from a published rota shift (Shifts), not the work schedule: Planned next to Clocked.

      • first_instring | nullrequired
      • last_outstring | nullrequired
      • workedintegerrequired
      • breaksintegerrequired
      • expectedintegerrequired
      • balanceintegerrequired
      • overtimeintegerrequired
      • nightintegerrequired
      • holiday_minutesintegerrequired
      • flagsstring (enum)[]required

        imported: the day's clockings came from the previous system (timeclock.records.import); unapproved_overtime: overtime worked beyond plan without approval while the company asks for it.

        One of: open, missing_out, late, no_record, on_leave, long_day, short_rest, short_break, late_sync, corrected, imported, unapproved_overtime.

      • closedbooleanrequired

        The month is closed: nothing in it changes until HR reopens it.

      • punchesobject[]required
        13 fields
        • idstringrequired
        • kind"in" | "out" | "break_start" | "break_end"required
        • atstringrequired

          The instant (ISO, UTC).

        • timestringrequired

          Local time in the person's time zone (HH:MM).

        • daystringrequired
        • sourcestring (enum)required

          import: brought from the previous time-and-attendance system; terminal: a door terminal.

          One of: web, mobile, kiosk, offline, correction, api, import, terminal.

        • place"site" | "remote"required
        • late_syncbooleanrequired

          An offline clocking that reached Bizisy more than 10 minutes after its time.

        • correctedbooleanrequired

          Added by a correction.

        • voidedbooleanrequired

          Removed by a correction (kept for the history, never counted).

        • geofenceobject | nullrequired

          Geofence mode: inside a company site or not (managers and HR).

          2 fields
          • insidebooleanrequired
          • sitestring | nullrequired
        • geoobject | nullrequired

          Record mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).

          3 fields
          • latnumberrequired
          • lngnumberrequired
          • accuracy_mnumber | nullrequired
        • geo_deniedbooleanrequired
      • overtime_approvalobject

        Overtime approval for the day, only while the company asks for it (Settings → Time clock); absent otherwise and in days before it was switched on.

        5 fields
        • approvedintegerrequired

          Overtime minutes approved for the day (before or after it was worked).

        • waitingintegerrequired

          Of the unapproved minutes, those in a request still waiting for a decision.

        • not_overtimeintegerrequired

          Minutes beyond plan an approver said are not overtime (kept as worked time, not paid as overtime).

        • unapprovedintegerrequired

          Overtime worked beyond plan nobody approved yet (waiting included): blocks the month close.

        • payableintegerrequired

          Overtime payroll counts: the worked overtime up to what was approved.

    • totalsobjectrequired

      Minutes, and how many days carry each flag.

      11 fields
      • workedintegerrequired
      • expectedintegerrequired
      • balanceintegerrequired
      • overtimeintegerrequired
      • nightintegerrequired
      • holidayintegerrequired
      • breaksintegerrequired
      • days_workedintegerrequired
      • flagsobjectrequired
      • overtime_payableinteger

        While overtime needs approval: the overtime payroll counts (approved).

      • overtime_unapprovedinteger

        While overtime needs approval: overtime worked beyond plan nobody approved yet.

    • correctionsobject[]required
      6 fields
      • daystringrequired
      • reasonstringrequired
      • requested_asstringrequired
      • applied_atstring | nullrequired
      • anywaybooleanrequired
      • disputedbooleanrequired
  • historyobject[]required
    4 fields
    • event"closed" | "reopened" | "acknowledged"required
    • atstringrequired
    • reasonstring | nullrequired
    • digeststring | nullrequired
  • limitsobject[]required

    Working-time limits on the clocked hours up to the month's end (computed now from the records; not part of the sealed summary).

    9 fields
    • kind"average_week" | "weekly_rest" | "overtime_year"required

      average_week: the average week over the reference period passes 48 hours (or the country's limit); weekly_rest: a week without the weekly rest the law asks for; overtime_year: overtime this calendar year near (80 %) or over the country's yearly cap.

    • level"over" | "near"required
    • valueintegerrequired

      average_week: average minutes a week; weekly_rest: the longest unbroken rest that week in minutes, or the rest days (unit days); overtime_year: overtime minutes this year.

    • limitintegerrequired
    • unit"minutes" | "days"required
    • fromstringrequired
    • tostringrequired
    • lawstringrequired

      The legal basis, as cited.

    • notestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/months.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p3","month":"2026-10"}'
Response
{
  "data": {
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "month": "2026-10",
    "status": "closed",
    "digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "closed_at": "2026-11-03T08:00:00.000Z",
    "ack_required": true,
    "acknowledged_at": null,
    "can_acknowledge": true,
    "summary": {
      "person": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "month": "2026-10",
      "timezone": "Europe/Madrid",
      "country": "ES",
      "generated_at": "2026-11-03T08:00:00.000Z",
      "retention_years": 4,
      "days": [
        {
          "date": "2026-10-13",
          "working": true,
          "holiday": null,
          "company_day": null,
          "leave": null,
          "schedule": {
            "start": "09:00",
            "end": "17:00"
          },
          "planned": false,
          "first_in": "09:00",
          "last_out": "17:30",
          "worked": 480,
          "breaks": 30,
          "expected": 450,
          "balance": 30,
          "overtime": 30,
          "night": 0,
          "holiday_minutes": 0,
          "flags": [
            "corrected"
          ],
          "closed": true,
          "punches": [
            {
              "id": "pu1",
              "kind": "in",
              "at": "2026-10-13T07:00:00.000Z",
              "time": "09:00",
              "day": "2026-10-13",
              "source": "mobile",
              "place": "site",
              "late_sync": false,
              "corrected": false,
              "voided": false,
              "geofence": {
                "inside": true,
                "site": "Madrid office"
              },
              "geo": null,
              "geo_denied": false
            },
            {
              "id": "pu3",
              "kind": "break_start",
              "at": "2026-10-13T11:00:00.000Z",
              "time": "13:00",
              "day": "2026-10-13",
              "source": "mobile",
              "place": "site",
              "late_sync": false,
              "corrected": false,
              "voided": false,
              "geofence": null,
              "geo": null,
              "geo_denied": false
            },
            {
              "id": "pu4",
              "kind": "break_end",
              "at": "2026-10-13T11:30:00.000Z",
              "time": "13:30",
              "day": "2026-10-13",
              "source": "mobile",
              "place": "site",
              "late_sync": false,
              "corrected": false,
              "voided": false,
              "geofence": null,
              "geo": null,
              "geo_denied": false
            },
            {
              "id": "pu2",
              "kind": "out",
              "at": "2026-10-13T15:30:00.000Z",
              "time": "17:30",
              "day": "2026-10-13",
              "source": "correction",
              "place": null,
              "late_sync": false,
              "corrected": true,
              "voided": false,
              "geofence": null,
              "geo": null,
              "geo_denied": false
            }
          ]
        }
      ],
      "totals": {
        "worked": 9120,
        "expected": 9450,
        "balance": -330,
        "overtime": 60,
        "night": 0,
        "holiday": 0,
        "breaks": 600,
        "days_worked": 20,
        "flags": {
          "corrected": 1,
          "no_record": 1
        }
      },
      "corrections": [
        {
          "day": "2026-10-13",
          "reason": "Forgot to clock out",
          "requested_as": "self",
          "applied_at": "2026-10-14T09:00:00.000Z",
          "anyway": false,
          "disputed": false
        }
      ]
    },
    "history": [
      {
        "event": "closed",
        "at": "2026-11-03T08:00:00.000Z",
        "reason": null,
        "digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
      }
    ],
    "limits": [
      {
        "kind": "overtime_year",
        "level": "near",
        "value": 4140,
        "limit": 4800,
        "unit": "minutes",
        "from": "2026-01-01",
        "to": "2026-10-31",
        "law": "Estatuto de los Trabajadores art. 35.2",
        "note": "Overtime compensated with rest within four months does not count."
      }
    ]
  }
}

Close a month of time records#

POST/v1/timeclock/months.closeWrite

Closes an ended month (spec time-clock C9) for person_ids (default: everyone employed that month), up to 100 a call (more: call again — closed people are skipped): freezes each person's summary with its SHA-256 digest; their records in that month can no longer change until HR reopens it. Skips people with a missing clock-out, a correction waiting or — while overtime needs approval — overtime worked without approval in that month (approve it with timeclock_overtime_settle), and says who and why; with approval on, the sealed summary counts only approved overtime for payroll. People who must acknowledge it (by country or the company's setting) are told. Owners, admins and HR.

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

Input

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • person_idsstring[]

    1–120 characters. 1–5000 items.

Returns

  • closedstring[]required
  • skippedobject[]required
    3 fields
    • person_idstringrequired
    • reason"open_shift" | "pending_correction" | "unapproved_overtime" | "already_closed" | "not_employed"required
    • minutesinteger

      unapproved_overtime: the minutes waiting for approval.

  • remainingintegerrequired

    People left to close (call again).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/months.close \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"month":"2026-09","person_ids":["p3"]}'
Response
{
  "data": {
    "closed": [
      "p3"
    ],
    "skipped": [
      {
        "person_id": "p4",
        "reason": "open_shift"
      },
      {
        "person_id": "p5",
        "reason": "unapproved_overtime",
        "minutes": 90
      }
    ],
    "remaining": 0
  }
}

Reopen a month of time records#

POST/v1/timeclock/months.reopenWrite

Reopens a closed month for one person so its records can be corrected (spec time-clock C9): the reason is kept in the month's history with the digest it had; the person acknowledges again after the next close. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. Reopening a closed month needs HR signed in to Bizisy.
MCP tool
timeclock_months_reopen on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstringrequired

    1–120 characters.

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • reasonstringrequired

    3–500 characters.

Returns

  • person_idstringrequired
  • monthstringrequired
  • status"reopened"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/months.reopen \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p3","month":"2026-10","reason":"Payroll query"}'
Response
{
  "data": {
    "person_id": "p3",
    "month": "2026-10",
    "status": "reopened"
  }
}

Acknowledge my month#

POST/v1/timeclock/months.acknowledgeWrite

The person acknowledges their closed month's summary (spec time-clock C9): the time, their login and the summary's digest are recorded. A simple acknowledgement, not a qualified signature. In the app only.

Web app only
Refused for API keys and connected apps. People acknowledge their month in the app only.
MCP tool
timeclock_months_acknowledge on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

Returns

  • monthstringrequired
  • acknowledged_atstringrequired
  • digeststringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/months.acknowledge \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"month":"2026-10"}'
Response
{
  "data": {
    "month": "2026-10",
    "acknowledged_at": "2026-11-04T09:00:00.000Z",
    "digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  }
}

Inspection export (registro de jornada)#

POST/v1/timeclock/exports.registroWrite

The inspection-ready daily record (spec time-clock C10; art. 34.9 ET, ITSS Criterio Técnico 101/2019, Código do Trabalho art. 202, BAG 1 ABR 22/21): per worker per day the start and end, every clocking span, breaks, worked, expected, overtime, night and holiday minutes, on site or remote, corrections (reason and who asked) and notes; a header with the company, its tax id, the period, the workplace and the retention. from/to (at most 93 days), optional person_ids or location_id; csv or xlsx; headers in lang. Owners, admins, HR and roles with Payroll at View, for the people they cover.

Who can call it
Manage key owner admin hr
MCP tool
timeclock_exports_registro 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

  • fromstringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • person_idsstring[]

    1–120 characters. Up to 5000 items.

  • location_idstring

    1–120 characters.

  • format"csv" | "xlsx"

    Default "xlsx".

  • lang"en" | "es" | "pt" | "de" | "fr" | "it"

    Language of the headers (default en).

Returns

  • filesobject[]required
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired
  • peopleintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/exports.registro \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "person_ids": [
    "p3"
  ],
  "location_id": "l1",
  "format": "csv",
  "lang": "es"
}'
Response
{
  "data": {
    "files": [
      {
        "name": "registro-jornada-2026-10-01-2026-10-31.xlsx",
        "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "encoding": "base64",
        "content": "UEsDBA==",
        "bytes": 4,
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    ],
    "people": 12
  }
}

Monthly time report#

POST/v1/timeclock/exports.monthlyRead

One person's month as a PDF (or CSV): every day's start, end, breaks, worked, expected, overtime and night, the totals, the corrections, and — when the month is closed — the sealed digest and the acknowledgement. The person themself, owners, admins, HR and roles with Payroll at View (for the people they cover). Headers in lang.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_exports_monthly on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring

    1–120 characters.

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • format"pdf" | "csv"

    Default "pdf".

  • lang"en" | "es" | "pt" | "de" | "fr" | "it"

    Language of the headers (default en).

Returns

  • fileobjectrequired
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/exports.monthly \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p3","month":"2026-10","format":"csv","lang":"pt"}'
Response
{
  "data": {
    "file": {
      "name": "time-carl-reis-2026-10.pdf",
      "content_type": "application/pdf",
      "encoding": "base64",
      "content": "UEsDBA==",
      "bytes": 4,
      "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    }
  }
}

Payroll hours#

POST/v1/timeclock/exports.payrollWrite

Hours for payroll for a month (spec time-clock C10): per person worked, expected, balance, overtime (while overtime needs approval: approved overtime only), night and holiday hours, days worked and days without a record, and whether the month is closed. csv or xlsx; optional location_id. Owners, admins, HR and roles with Payroll at View, for the people they cover.

Who can call it
Manage key owner admin hr
MCP tool
timeclock_exports_payroll 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

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • location_idstring

    1–120 characters.

  • format"csv" | "xlsx"

    Default "xlsx".

  • lang"en" | "es" | "pt" | "de" | "fr" | "it"

    Language of the headers (default en).

Returns

  • filesobject[]required
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired
  • peopleintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/exports.payroll \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"month":"2026-10","location_id":"l1","format":"csv","lang":"de"}'
Response
{
  "data": {
    "files": [
      {
        "name": "payroll-hours-2026-10.xlsx",
        "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "encoding": "base64",
        "content": "UEsDBA==",
        "bytes": 4,
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    ],
    "people": 12
  }
}

Set my kiosk PIN#

POST/v1/timeclock/pin.setWrite

Sets the caller's 6-digit PIN for clocking at a company kiosk (spec time-clock C13). Stored as a salted scrypt hash, never the digits; obvious PINs (one digit repeated, 123456…) are refused. In the app only; HR can only clear it.

Web app only
Refused for API keys and connected apps. A kiosk PIN is set by the person in the app only.
MCP tool
timeclock_pin_set on My Workplace, 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

  • pinstringrequired

    Pattern ^\d{6}$.

Returns

  • pin_settruerequired
  • set_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/pin.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"pin":"482915"}'
Response
{
  "data": {
    "pin_set": true,
    "set_at": "2026-10-13T08:00:00.000Z"
  }
}

Clear someone's kiosk PIN#

POST/v1/timeclock/pin.clearWrite

Removes a person's kiosk PIN (they set a new one in My workspace) and their kiosk lockouts. Owners, admins and HR.

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

Input

  • person_idstringrequired

    1–120 characters.

Returns

  • clearedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/pin.clear \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p3"}'
Response
{
  "data": {
    "cleared": true
  }
}

Import clock records#

POST/v1/timeclock/records.importWrite

Imports clock records from a previous time-and-attendance system (spec demo-company P4): up to 2000 day rows {work_email or person_id, day (YYYY-MM-DD), punches [{kind in|break_start|break_end|out, time HH:MM local, next_day?, place? site|remote on the clock-in, geo? {lat,lng,accuracy_m}}], source_ref (the record's id there)}. Each day is checked like a correction: in → (break start → break end)* → out with a clock-out, the person employed that day, not a closed month, not after today, at most the last 24 months, and never into a day that already has clockings (refused, never merged) or overlapping the day before/after. Recorded with source "import", marked "Imported" in the records, month close and exports; nobody is notified. When the company has people confirm HR's changes to their records (company_edits_confirm, the default), a current worker's day becomes a correction waiting for that person (status pending, one notice per person): it is recorded, as imported, when they confirm it, and their disagreement is kept as for any correction; refused only for someone without a Bizisy sign-in (needs_confirmation) or a day with a correction already waiting. Leavers' days import directly. Idempotent: the same source_ref and day are skipped when run again. One call writes at most 480 clockings; rows past that come back as "later" (send them again). Dry run first: the same per-row answer without writing. Owners, admins and HR (also their API keys and AI apps); at most 100 calls a day that import something (Bizisy support can raise it). Location follows the company's setting (record: rounded; geofence: inside/outside only; off: dropped).

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

Input

  • rowsobject[]required

    1–2000 items.

    5 fields
    • person_idstring

      1–120 characters.

    • work_emailstring

      Up to 320 characters.

    • daystringrequired

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • punchesobject[]required

      1–40 items.

      5 fields
      • kind"in" | "out" | "break_start" | "break_end"required
      • timestringrequired

        Local time (HH:MM) in the person's time zone.

        Pattern ^([01]\d|2[0-3]):[0-5]\d$.

      • next_dayboolean

        The time is after midnight (a night shift).

      • place"site" | "remote"

        On a clock-in: on site or remote.

      • geoobject

        Where it was clocked: kept rounded (~100 m) only when the company records location; turned into inside/outside a workplace in geofence mode (coordinates dropped); ignored when location is off.

        3 fields
        • latnumberrequired

          From -90 to 90.

        • lngnumberrequired

          From -180 to 180.

        • accuracy_mnumber | null

          From 0 to 100000.

    • source_refstringrequired

      The record's id in the previous system: re-running the same row never records it twice.

      1–200 characters.

Returns

8 fields
  • imported_daysintegerrequired
  • imported_punchesintegerrequired
  • pending_daysintegerrequired

    Days waiting for the person to confirm them (company_edits_confirm).

  • pending_peopleintegerrequired

    People asked to confirm days.

  • skippedintegerrequired
  • refusedintegerrequired
  • remainingintegerrequired

    Rows left for another call (status later).

  • rowsobject[]required
    6 fields
    • indexintegerrequired
    • source_refstringrequired
    • daystringrequired
    • status"imported" | "pending" | "skipped" | "refused" | "later"required

      imported (would be, on a dry run); pending: waits for the person to confirm it (the company asks people to confirm HR's changes to their records); skipped: already imported or already waiting; refused (see reason); later: over this call's budget, send it again.

    • reasonstring (enum)required

      One of: unknown_person, not_employed, future, too_old, closed_month, day_has_records, order, open, not_on_day, overlaps_neighbour, duplicate_row, too_long, ambiguous_email, needs_confirmation, correction_waiting, own_records, in_app.

    • messagestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/records.import \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "rows": [
    {
      "person_id": "p3",
      "day": "2026-10-06",
      "source_ref": "old-2",
      "punches": [
        {
          "kind": "in",
          "time": "22:00",
          "geo": {
            "lat": 40.4,
            "lng": -3.7,
            "accuracy_m": 10
          }
        },
        {
          "kind": "out",
          "time": "06:00",
          "next_day": true
        }
      ]
    }
  ]
}'
Response
{
  "data": {
    "imported_days": 1,
    "imported_punches": 2,
    "pending_days": 1,
    "pending_people": 1,
    "skipped": 0,
    "refused": 1,
    "remaining": 0,
    "rows": [
      {
        "index": 0,
        "source_ref": "old-1",
        "day": "2026-10-05",
        "status": "imported",
        "reason": null,
        "message": null
      },
      {
        "index": 2,
        "source_ref": "old-3",
        "day": "2026-10-07",
        "status": "pending",
        "reason": null,
        "message": null
      },
      {
        "index": 1,
        "source_ref": "old-2",
        "day": "2026-10-06",
        "status": "refused",
        "reason": "day_has_records",
        "message": "The day already has clockings in Bizisy; imports never merge into them (correct the day instead)."
      }
    ]
  }
}

Ask for overtime#

POST/v1/timeclock/overtime.requestWrite

Asks for overtime on a day before it is worked (spec 2026-11-17-hcm-gaps §10), while the company asks for approval (Settings → Time clock): person_id (default yourself — only when the company lets people ask for their own), day (today up to 92 days ahead), minutes (15–720), reason. Approved per Approval rules → Overtime (default: the person's manager; HR for a manager's own or with no manager; or HR; or manager then HR); steps the asker may decide are approved at once (a manager asking for their report: approved). The result warns (cap) when the year's overtime with it would be near or over the country's yearly cap (ES 80 h, PT 150/175 h): a warning, never a block. One waiting request per person and day; asking again for a day replaces its approved hours once approved; at most 20 waiting per person and 31 active (waiting or approved) per person and month. HR may ask for their own even when people can't. For days already worked use timeclock_overtime_settle. Managers for their reports, HR for anyone. API keys and AI apps only for their own person.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Only for the key's or app's own person, when the company lets people ask for their own overtime.
MCP tool
timeclock_overtime_request on My Workplace, 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

  • person_idstring

    1–120 characters.

  • daystringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • minutesintegerrequired

    From 15 to 720.

  • reasonstringrequired

    3–500 characters.

Returns

16 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • minutesintegerrequired
  • reasonstringrequired
  • when"before" | "after"required

    before: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.

  • status"pending" | "approved" | "declined" | "cancelled"required

    declined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).

  • stepsobject[]required
    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      The manager step's manager (anyone above them, or HR, may decide it too).

      2 fields
      • idstringrequired
      • namestringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • autobooleanrequired

      Approved without a separate decision: whoever asked could decide this step (or nobody else could).

  • waiting_for"manager" | "hr"required
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • capobject | nullrequired

    The yearly overtime cap check when asked: with this request the year's overtime would be near (80 %) or over the country's cap. A warning, never a block.

    4 fields
    • level"near" | "over"required
    • projectedintegerrequired
    • limitintegerrequired
    • lawstringrequired
  • bulkbooleanrequired

    Approved by HR with others at once (from the month close), with one reason.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/overtime.request \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p3",
  "day": "2026-10-16",
  "minutes": 60,
  "reason": "Release night"
}'
Response
{
  "data": {
    "id": "ot1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-16",
    "minutes": 60,
    "reason": "Release night",
    "when": "before",
    "status": "pending",
    "steps": [
      {
        "role": "manager",
        "state": "pending",
        "approver": {
          "id": "p2",
          "name": "Bea Lopes"
        },
        "by": null,
        "at": null,
        "comment": null,
        "auto": false
      }
    ],
    "waiting_for": "manager",
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-13T08:00:00.000Z"
    },
    "cap": {
      "level": "near",
      "projected": 4020,
      "limit": 4800,
      "law": "Estatuto de los Trabajadores art. 35.2"
    },
    "bulk": false,
    "can_decide": true,
    "can_cancel": false,
    "created_at": "2026-10-13T08:00:00.000Z",
    "closed_at": null
  }
}

Overtime requests#

POST/v1/timeclock/overtime.listRead

Overtime requests and decisions the caller may see: their own (including what their manager asked for them); their reports' (managers); everyone's (owners, admins, HR). Each with the day, minutes, reason, before/after, status, the approval steps (who decided, comments), the yearly cap warning, and whether the caller decides it now. Filters: status, person_id, waiting_for_me, from/to (days; without them and without person_id, days from 92 days ago on). Newest first; at most 200. API keys and AI apps: their own person, others only with the company's machine consent for private data.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Other people's overtime only with the company's machine consent for private data.
MCP tool
timeclock_overtime_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"pending" | "approved" | "declined" | "cancelled"
  • person_idstring

    1–120 characters.

  • waiting_for_meboolean
  • fromstring

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • itemsobject[]required
    16 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • daystringrequired
    • minutesintegerrequired
    • reasonstringrequired
    • when"before" | "after"required

      before: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.

    • status"pending" | "approved" | "declined" | "cancelled"required

      declined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).

    • stepsobject[]required
      7 fields
      • role"manager" | "hr"required
      • state"waiting" | "pending" | "approved" | "declined"required
      • approverobject | nullrequired

        The manager step's manager (anyone above them, or HR, may decide it too).

        2 fields
        • idstringrequired
        • namestringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired

        Approved without a separate decision: whoever asked could decide this step (or nobody else could).

    • waiting_for"manager" | "hr"required
    • requestedobjectrequired
      3 fields
      • as"self" | "manager" | "hr"required
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
    • capobject | nullrequired

      The yearly overtime cap check when asked: with this request the year's overtime would be near (80 %) or over the country's cap. A warning, never a block.

      4 fields
      • level"near" | "over"required
      • projectedintegerrequired
      • limitintegerrequired
      • lawstringrequired
    • bulkbooleanrequired

      Approved by HR with others at once (from the month close), with one reason.

    • can_decidebooleanrequired
    • can_cancelbooleanrequired
    • created_atstringrequired
    • closed_atstring | nullrequired
  • waiting_for_meintegerrequired
  • approvalbooleanrequired

    The company asks for overtime approval now.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/overtime.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "approved",
  "person_id": "p3",
  "waiting_for_me": true,
  "from": "2026-10-01",
  "to": "2026-10-31"
}'
Response
{
  "data": {
    "items": [
      {
        "id": "ot1",
        "person": {
          "id": "p3",
          "name": "Carl Reis"
        },
        "day": "2026-10-15",
        "minutes": 120,
        "reason": "Stock count",
        "when": "before",
        "status": "pending",
        "steps": [
          {
            "role": "manager",
            "state": "pending",
            "approver": {
              "id": "p2",
              "name": "Bea Lopes"
            },
            "by": null,
            "at": null,
            "comment": null,
            "auto": false
          }
        ],
        "waiting_for": "manager",
        "requested": {
          "as": "self",
          "by": {
            "id": "p3",
            "name": "Carl Reis"
          },
          "at": "2026-10-13T08:00:00.000Z"
        },
        "cap": {
          "level": "near",
          "projected": 4020,
          "limit": 4800,
          "law": "Estatuto de los Trabajadores art. 35.2"
        },
        "bulk": false,
        "can_decide": true,
        "can_cancel": false,
        "created_at": "2026-10-13T08:00:00.000Z",
        "closed_at": null
      }
    ],
    "waiting_for_me": 1,
    "approval": true
  }
}

Decide on overtime#

POST/v1/timeclock/overtime.decideWrite

Approves or declines the overtime request waiting for the caller (spec 2026-11-17-hcm-gaps §10): the manager step — the person's manager, anyone above them, or HR; the HR step — owners, admins and HR. Never your own overtime. Approving moves it to the next step or approves it; declining closes it (a comment helps; on minutes already worked it means they are not overtime). The person is told. In the app only.

Web app only
Refused for API keys and connected apps. Approving or declining overtime needs a person signed in to Bizisy.
MCP tool
timeclock_overtime_decide on My Workplace, 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

  • overtime_idstringrequired

    1–120 characters.

  • decision"approve" | "decline"required
  • commentstring | null

    Up to 500 characters.

Returns

16 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • minutesintegerrequired
  • reasonstringrequired
  • when"before" | "after"required

    before: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.

  • status"pending" | "approved" | "declined" | "cancelled"required

    declined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).

  • stepsobject[]required
    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      The manager step's manager (anyone above them, or HR, may decide it too).

      2 fields
      • idstringrequired
      • namestringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • autobooleanrequired

      Approved without a separate decision: whoever asked could decide this step (or nobody else could).

  • waiting_for"manager" | "hr"required
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • capobject | nullrequired

    The yearly overtime cap check when asked: with this request the year's overtime would be near (80 %) or over the country's cap. A warning, never a block.

    4 fields
    • level"near" | "over"required
    • projectedintegerrequired
    • limitintegerrequired
    • lawstringrequired
  • bulkbooleanrequired

    Approved by HR with others at once (from the month close), with one reason.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/overtime.decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"overtime_id":"ot1","decision":"decline","comment":"Not this week"}'
Response
{
  "data": {
    "id": "ot1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-15",
    "minutes": 120,
    "reason": "Stock count",
    "when": "before",
    "status": "approved",
    "steps": [
      {
        "role": "manager",
        "state": "approved",
        "approver": {
          "id": "p2",
          "name": "Bea Lopes"
        },
        "by": {
          "id": "p2",
          "name": "Bea Lopes"
        },
        "at": "2026-10-13T09:00:00.000Z",
        "comment": "Thanks",
        "auto": false
      }
    ],
    "waiting_for": null,
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-13T08:00:00.000Z"
    },
    "cap": {
      "level": "near",
      "projected": 4020,
      "limit": 4800,
      "law": "Estatuto de los Trabajadores art. 35.2"
    },
    "bulk": false,
    "can_decide": false,
    "can_cancel": false,
    "created_at": "2026-10-13T08:00:00.000Z",
    "closed_at": "2026-10-13T09:00:00.000Z"
  }
}

Withdraw overtime#

POST/v1/timeclock/overtime.cancelWrite

Withdraws an overtime request: one still waiting — whoever asked, or HR; an approved one for a day not yet past — whoever asked, the person's managers, or HR. Nothing changes in the clock records; minutes worked beyond plan that day then need approval again.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_overtime_cancel on My Workplace, 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

  • overtime_idstringrequired

    1–120 characters.

Returns

16 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • daystringrequired
  • minutesintegerrequired
  • reasonstringrequired
  • when"before" | "after"required

    before: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.

  • status"pending" | "approved" | "declined" | "cancelled"required

    declined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).

  • stepsobject[]required
    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      The manager step's manager (anyone above them, or HR, may decide it too).

      2 fields
      • idstringrequired
      • namestringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • autobooleanrequired

      Approved without a separate decision: whoever asked could decide this step (or nobody else could).

  • waiting_for"manager" | "hr"required
  • requestedobjectrequired
    3 fields
    • as"self" | "manager" | "hr"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • capobject | nullrequired

    The yearly overtime cap check when asked: with this request the year's overtime would be near (80 %) or over the country's cap. A warning, never a block.

    4 fields
    • level"near" | "over"required
    • projectedintegerrequired
    • limitintegerrequired
    • lawstringrequired
  • bulkbooleanrequired

    Approved by HR with others at once (from the month close), with one reason.

  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/overtime.cancel \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"overtime_id":"ot1"}'
Response
{
  "data": {
    "id": "ot1",
    "person": {
      "id": "p3",
      "name": "Carl Reis"
    },
    "day": "2026-10-15",
    "minutes": 120,
    "reason": "Stock count",
    "when": "before",
    "status": "cancelled",
    "steps": [
      {
        "role": "manager",
        "state": "pending",
        "approver": {
          "id": "p2",
          "name": "Bea Lopes"
        },
        "by": null,
        "at": null,
        "comment": null,
        "auto": false
      }
    ],
    "waiting_for": null,
    "requested": {
      "as": "self",
      "by": {
        "id": "p3",
        "name": "Carl Reis"
      },
      "at": "2026-10-13T08:00:00.000Z"
    },
    "cap": {
      "level": "near",
      "projected": 4020,
      "limit": 4800,
      "law": "Estatuto de los Trabajadores art. 35.2"
    },
    "bulk": false,
    "can_decide": false,
    "can_cancel": false,
    "created_at": "2026-10-13T08:00:00.000Z",
    "closed_at": "2026-10-13T09:00:00.000Z"
  }
}

Overtime worked without approval#

POST/v1/timeclock/overtime.unapprovedRead

For a month, the days where people worked beyond plan without approval while the company asks for it (spec 2026-11-17-hcm-gaps §10), computed now from the clock records and the requests: worked, expected, overtime, approved, waiting and unapproved minutes per person and day. These block the month close until approved, marked not overtime (timeclock_overtime_settle) or the clockings are corrected. Managers see their reports, owners, admins and HR everyone (person_id: one person, also yourself). Filters: unit_id. At most 1,000 days (more: filter by team). API keys and AI apps only with the company's machine consent for private data.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Other people's days only with the company's machine consent for private data.
MCP tool
timeclock_overtime_unapproved on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • person_idstring

    1–120 characters.

  • unit_idstring

    1–120 characters.

Returns

  • monthstringrequired
  • approvalbooleanrequired
  • itemsobject[]required
    9 fields
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • daystringrequired
    • workedintegerrequired
    • expectedintegerrequired
    • overtimeintegerrequired

      Worked beyond plan (minutes).

    • approvedintegerrequired
    • waitingintegerrequired

      Of unapproved, in a request still waiting.

    • unapprovedintegerrequired
    • can_settlebooleanrequired

      The caller may approve these minutes (or say they are not overtime) with timeclock_overtime_settle.

  • totalsobjectrequired
    4 fields
    • daysintegerrequired
    • peopleintegerrequired
    • minutesintegerrequired
    • waitingintegerrequired
  • truncatedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/overtime.unapproved \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"month":"2026-10","person_id":"p3","unit_id":"u1"}'
Response
{
  "data": {
    "month": "2026-10",
    "approval": true,
    "truncated": false,
    "totals": {
      "days": 1,
      "people": 1,
      "minutes": 30,
      "waiting": 0
    },
    "items": [
      {
        "person": {
          "id": "p3",
          "name": "Carl Reis",
          "unit": {
            "id": "u1",
            "name": "Operations"
          }
        },
        "day": "2026-10-14",
        "worked": 600,
        "expected": 450,
        "overtime": 150,
        "approved": 120,
        "waiting": 0,
        "unapproved": 30,
        "can_settle": true
      }
    ]
  }
}

Approve overtime already worked#

POST/v1/timeclock/overtime.settleWrite

Decides minutes already worked beyond plan without approval (spec 2026-11-17-hcm-gaps §10): decision approve (they count as overtime for payroll) or not_overtime (kept as worked time, not paid as overtime), with a reason. items ({person_id, day}, up to 100) — or month (with optional person_ids) for every unapproved day of that month: HR's bulk approval from the month close. Requests still waiting on those days that the caller decides are decided the same way. Under Approval rules a later step (manager then HR) may still wait; with HR-only approval a manager's approval asks HR. Managers for their reports, owners, admins and HR for anyone, never their own (skipped and said) — except the only HR member, whose own approves by itself, noted; a closed month is skipped (the monthly cap of requests never applies here: worked overtime is always decided). One notice per login for the whole call. More than 100 days: call again (remaining). In the app only.

Web app only
Refused for API keys and connected apps. Approving overtime already worked (or marking it not overtime) needs a person signed in to Bizisy.
MCP tool
timeclock_overtime_settle on My Workplace, 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

  • decision"approve" | "not_overtime"required
  • reasonstringrequired

    3–500 characters.

  • itemsobject[]

    1–100 items.

    2 fields
    • person_idstringrequired

      1–120 characters.

    • daystringrequired

      Pattern ^\d{4}-\d{2}-\d{2}$.

  • monthstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • person_idsstring[]

    1–120 characters. 1–5000 items.

Returns

  • settledintegerrequired

    Days decided.

  • minutesintegerrequired

    Minutes approved or marked not overtime.

  • waitingintegerrequired

    Days now waiting for a later approver (manager then HR, or HR only).

  • skippedobject[]required
    3 fields
    • person_idstringrequired
    • daystringrequired
    • reason"nothing_to_settle" | "not_yours" | "closed_month"required
  • remainingintegerrequired

    Days left (call again).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/overtime.settle \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "decision": "not_overtime",
  "reason": "Stayed for the party",
  "items": [
    {
      "person_id": "p3",
      "day": "2026-10-14"
    }
  ]
}'
Response
{
  "data": {
    "settled": 1,
    "minutes": 30,
    "waiting": 0,
    "skipped": [
      {
        "person_id": "p3",
        "day": "2026-10-13",
        "reason": "nothing_to_settle"
      }
    ],
    "remaining": 0
  }
}

My terminal punches not recorded#

POST/v1/timeclock/my.terminal_punchesRead

The caller's own door-terminal punches that were not recorded (spec hcm-gaps §8): waiting in To match (with why) or dismissed by HR, from the last 92 days, newest first (at most 100). Punches that were recorded are in the person's records. For the person themself.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
timeclock_my_terminal_punches on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    8 fields
    • idstringrequired
    • terminalstringrequired
    • atstringrequired
    • daystringrequired
    • timestringrequired
    • status"held" | "dismissed"required
    • reasonstring (enum)required

      One of: unmatched, future, too_old, not_employed, open_shift, sequence, later_exists, closed_month, day_cap, off.

    • reason_textstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/my.terminal_punches \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "ev2",
        "terminal": "Front door",
        "at": "2026-10-13T07:01:00.000Z",
        "day": "2026-10-13",
        "time": "09:01",
        "status": "held",
        "reason": "sequence",
        "reason_text": "It is out of order (for example a clock-in while already clocked in)."
      }
    ]
  }
}

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

Developer docs