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_todayon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
15 fields
enabledbooleanrequiredtodaystringrequiredtimezonestringrequiredstate"out" | "in" | "break"requiredsincestring | nullrequiredWhen the open shift started (ISO).
punchesobject[]requiredToday's clockings and the open shift's.
13 fields
idstringrequiredkind"in" | "out" | "break_start" | "break_end"requiredatstringrequiredThe instant (ISO, UTC).
timestringrequiredLocal time in the person's time zone (HH:MM).
daystringrequiredsourcestring (enum)requiredimport: 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"requiredlate_syncbooleanrequiredAn offline clocking that reached Bizisy more than 10 minutes after its time.
correctedbooleanrequiredAdded by a correction.
voidedbooleanrequiredRemoved by a correction (kept for the history, never counted).
geofenceobject | nullrequiredGeofence mode: inside a company site or not (managers and HR).
2 fields
insidebooleanrequiredsitestring | nullrequired
geoobject | nullrequiredRecord mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).
3 fields
latnumberrequiredlngnumberrequiredaccuracy_mnumber | nullrequired
geo_deniedbooleanrequired
dayobject | nullrequiredToday with its totals so far.
20 fields
datestringrequiredworkingbooleanrequiredholidaystring | nullrequiredcompany_daystring | nullrequiredleave"full" | "am" | "pm" | "hours"requiredTime off that day (never its type): a day-part, or hours (some hours of the day).
scheduleobject | nullrequired2 fields
startstring | nullrequiredendstring | nullrequired
plannedbooleanrequiredThe expected hours and start come from a published rota shift (Shifts), not the work schedule: Planned next to Clocked.
first_instring | nullrequiredlast_outstring | nullrequiredworkedintegerrequiredbreaksintegerrequiredexpectedintegerrequiredbalanceintegerrequiredovertimeintegerrequirednightintegerrequiredholiday_minutesintegerrequiredflagsstring (enum)[]requiredimported: 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.closedbooleanrequiredThe month is closed: nothing in it changes until HR reopens it.
punchesobject[]required13 fields
idstringrequiredkind"in" | "out" | "break_start" | "break_end"requiredatstringrequiredThe instant (ISO, UTC).
timestringrequiredLocal time in the person's time zone (HH:MM).
daystringrequiredsourcestring (enum)requiredimport: 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"requiredlate_syncbooleanrequiredAn offline clocking that reached Bizisy more than 10 minutes after its time.
correctedbooleanrequiredAdded by a correction.
voidedbooleanrequiredRemoved by a correction (kept for the history, never counted).
geofenceobject | nullrequiredGeofence mode: inside a company site or not (managers and HR).
2 fields
insidebooleanrequiredsitestring | nullrequired
geoobject | nullrequiredRecord mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).
3 fields
latnumberrequiredlngnumberrequiredaccuracy_mnumber | nullrequired
geo_deniedbooleanrequired
overtime_approvalobjectOvertime 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
approvedintegerrequiredOvertime minutes approved for the day (before or after it was worked).
waitingintegerrequiredOf the unapproved minutes, those in a request still waiting for a decision.
not_overtimeintegerrequiredMinutes beyond plan an approver said are not overtime (kept as worked time, not paid as overtime).
unapprovedintegerrequiredOvertime worked beyond plan nobody approved yet (waiting included): blocks the month close.
payableintegerrequiredOvertime payroll counts: the worked overtime up to what was approved.
weekobjectrequired4 fields
fromstringrequiredtostringrequiredworkedintegerrequiredexpectedintegerrequired
geolocationobjectrequired3 fields
mode"off" | "record" | "geofence"requiredrequiredbooleanrequiredsitesobject[]required2 fields
idstringrequirednamestringrequired
offline_hoursintegerrequiredcorrections_pendingintegerrequiredconfirm_waitingintegerrequiredto_acknowledgestring[]requiredClosed months (YYYY-MM) waiting for the person's acknowledgement.
pin_setbooleanrequiredovertimeobjectrequired2 fields
approvalbooleanrequiredThe company asks for overtime to be approved before it's worked.
selfbooleanrequiredThe person may ask for their own overtime (timeclock_overtime_request).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/my.today \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeclock/my.today', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/my.today",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_punchon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
kind"in" | "out" | "break_start" | "break_end"requiredplace"site" | "remote"source"web" | "mobile"offlineobject2 fields
atdate-timerequiredISO 8601 date and time (UTC).
client_idstringrequired8–64 characters. Pattern
^[A-Za-z0-9_-]+$.
geoobject | null3 fields
latnumberrequiredFrom -90 to 90.
lngnumberrequiredFrom -180 to 180.
accuracy_mnumber | nullFrom 0 to 100000.
geo_deniedboolean
Returns
punchobject | nullrequirednull when the clocking went for approval (review).
13 fields
idstringrequiredkind"in" | "out" | "break_start" | "break_end"requiredatstringrequiredThe instant (ISO, UTC).
timestringrequiredLocal time in the person's time zone (HH:MM).
daystringrequiredsourcestring (enum)requiredimport: 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"requiredlate_syncbooleanrequiredAn offline clocking that reached Bizisy more than 10 minutes after its time.
correctedbooleanrequiredAdded by a correction.
voidedbooleanrequiredRemoved by a correction (kept for the history, never counted).
geofenceobject | nullrequiredGeofence mode: inside a company site or not (managers and HR).
2 fields
insidebooleanrequiredsitestring | nullrequired
geoobject | nullrequiredRecord mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).
3 fields
latnumberrequiredlngnumberrequiredaccuracy_mnumber | nullrequired
geo_deniedbooleanrequired
state"out" | "in" | "break"requiredduplicatebooleanrequiredThis offline clocking was already recorded (a replayed queue).
reviewobject | nullrequiredAn 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 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
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/punch', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"kind": "out",
"offline": {
"at": "2026-10-13T15:30:00.000Z",
"client_id": "c-0f6a1d2e9b"
},
"geo_denied": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/punch",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"kind": "out",
"offline": {
"at": "2026-10-13T15:30:00.000Z",
"client_id": "c-0f6a1d2e9b",
},
"geo_denied": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstring1–120 characters.
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
Returns
personobjectrequired2 fields
idstringrequirednamestringrequired
timezonestringrequireddaysobject[]required20 fields
datestringrequiredworkingbooleanrequiredholidaystring | nullrequiredcompany_daystring | nullrequiredleave"full" | "am" | "pm" | "hours"requiredTime off that day (never its type): a day-part, or hours (some hours of the day).
scheduleobject | nullrequired2 fields
startstring | nullrequiredendstring | nullrequired
plannedbooleanrequiredThe expected hours and start come from a published rota shift (Shifts), not the work schedule: Planned next to Clocked.
first_instring | nullrequiredlast_outstring | nullrequiredworkedintegerrequiredbreaksintegerrequiredexpectedintegerrequiredbalanceintegerrequiredovertimeintegerrequirednightintegerrequiredholiday_minutesintegerrequiredflagsstring (enum)[]requiredimported: 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.closedbooleanrequiredThe month is closed: nothing in it changes until HR reopens it.
punchesobject[]required13 fields
idstringrequiredkind"in" | "out" | "break_start" | "break_end"requiredatstringrequiredThe instant (ISO, UTC).
timestringrequiredLocal time in the person's time zone (HH:MM).
daystringrequiredsourcestring (enum)requiredimport: 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"requiredlate_syncbooleanrequiredAn offline clocking that reached Bizisy more than 10 minutes after its time.
correctedbooleanrequiredAdded by a correction.
voidedbooleanrequiredRemoved by a correction (kept for the history, never counted).
geofenceobject | nullrequiredGeofence mode: inside a company site or not (managers and HR).
2 fields
insidebooleanrequiredsitestring | nullrequired
geoobject | nullrequiredRecord mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).
3 fields
latnumberrequiredlngnumberrequiredaccuracy_mnumber | nullrequired
geo_deniedbooleanrequired
overtime_approvalobjectOvertime 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
approvedintegerrequiredOvertime minutes approved for the day (before or after it was worked).
waitingintegerrequiredOf the unapproved minutes, those in a request still waiting for a decision.
not_overtimeintegerrequiredMinutes beyond plan an approver said are not overtime (kept as worked time, not paid as overtime).
unapprovedintegerrequiredOvertime worked beyond plan nobody approved yet (waiting included): blocks the month close.
payableintegerrequiredOvertime payroll counts: the worked overtime up to what was approved.
totalsobjectrequiredMinutes, and how many days carry each flag.
11 fields
workedintegerrequiredexpectedintegerrequiredbalanceintegerrequiredovertimeintegerrequirednightintegerrequiredholidayintegerrequiredbreaksintegerrequireddays_workedintegerrequiredflagsobjectrequiredovertime_payableintegerWhile overtime needs approval: the overtime payroll counts (approved).
overtime_unapprovedintegerWhile overtime needs approval: overtime worked beyond plan nobody approved yet.
monthsobject[]required4 fields
monthstringrequiredstatus"open" | "closed" | "reopened"requiredacknowledged_atstring | nullrequireddigeststring | nullrequired
limitsobject[]requiredWorking-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"requiredaverage_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"requiredvalueintegerrequiredaverage_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.
limitintegerrequiredunit"minutes" | "days"requiredfromstringrequiredtostringrequiredlawstringrequiredThe legal basis, as cited.
notestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/records.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p3",
"from": "2026-10-12",
"to": "2026-10-18"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/records.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p3",
"from": "2026-10-12",
"to": "2026-10-18",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_dayon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
datestringPattern
^\d{4}-\d{2}-\d{2}$.unit_idstring1–120 characters.
location_idstring1–120 characters.
state"out" | "in" | "break"
Returns
datestringrequiredtodaystringrequiredpeopleobject[]required13 fields
personobjectrequired3 fields
idstringrequirednamestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
state"out" | "in" | "break"requiredAt the end of that day (now, today).
sincestring | nullrequiredWhen the open shift started (ISO).
overduebooleanrequiredStill clocked in an hour after their scheduled end, or for more than 10 hours: probably forgot to clock out.
first_instring | nullrequiredlast_outstring | nullrequiredworkedintegerrequiredexpectedintegerrequiredscheduleobject | nullrequired2 fields
startstring | nullrequiredendstring | nullrequired
plannedbooleanrequiredThe expected hours come from a published rota shift (Shifts): Planned next to Clocked.
leave"full" | "am" | "pm" | "hours"requiredTime off that day (never its type): hours = some hours of it.
holidaystring | nullrequiredflagsstring[]required
countsobjectrequired8 fields
inintegerrequiredbreakintegerrequiredoutintegerrequiredlateintegerrequiredoverdueintegerrequiredmissing_outintegerrequiredno_recordintegerrequiredon_leaveintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/team.day', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"date": "2026-10-13",
"unit_id": "u1",
"location_id": "l1",
"state": "in"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/team.day",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"date": "2026-10-13",
"unit_id": "u1",
"location_id": "l1",
"state": "in",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_requeston My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstring1–120 characters.
daystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.changesobject[]required1–12 items.
6 fields (one of several shapes)
Option 1
op"add"requiredkind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredLocal time (HH:MM) in the person's time zone.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.next_daybooleanThe time is after midnight (a night shift).
Option 2
op"void"requiredpunch_idstringrequiredA clocking of that day to remove (it stays in the history).
1–120 characters.
reasonstringrequired3–500 characters.
Returns
19 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredreasonstringrequiredstatus"pending" | "applied" | "declined" | "cancelled"requiredchangesobject[]required4 fields
op"add" | "void"requiredkind"in" | "out" | "break_start" | "break_end"requiredtimestring | nullrequiredpunch_idstring | nullrequired
beforeobject[]requiredThe day's clockings before the correction.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
afterobject[]requiredThe day's clockings with it.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
waiting_for"manager" | "hr" | "worker"requiredworker: the person confirms a correction their manager or HR made.
approverobject | nullrequired2 fields
idstringrequirednamestringrequired
requestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
decidedobject | nullrequired4 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequireddecision"approved" | "declined"requiredcommentstring | nullrequired
disputeobject | nullrequiredThe person disagreed with the company's correction (kept with it).
2 fields
commentstring | nullrequiredatstringrequired
appliedobject | nullrequired2 fields
atstringrequiredanywaybooleanrequiredHR applied it although the person disagreed.
can_decidebooleanrequiredcan_cancelbooleanrequiredcan_apply_anywaybooleanrequiredimportedbooleanrequiredA 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 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"
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/corrections.request', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/corrections.request",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"pending" | "applied" | "declined" | "cancelled"person_idstring1–120 characters.
waiting_for_mebooleanfromstringPattern
^\d{4}-\d{2}-\d{2}$.tostringPattern
^\d{4}-\d{2}-\d{2}$.
Returns
itemsobject[]required19 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredreasonstringrequiredstatus"pending" | "applied" | "declined" | "cancelled"requiredchangesobject[]required4 fields
op"add" | "void"requiredkind"in" | "out" | "break_start" | "break_end"requiredtimestring | nullrequiredpunch_idstring | nullrequired
beforeobject[]requiredThe day's clockings before the correction.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
afterobject[]requiredThe day's clockings with it.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
waiting_for"manager" | "hr" | "worker"requiredworker: the person confirms a correction their manager or HR made.
approverobject | nullrequired2 fields
idstringrequirednamestringrequired
requestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
decidedobject | nullrequired4 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequireddecision"approved" | "declined"requiredcommentstring | nullrequired
disputeobject | nullrequiredThe person disagreed with the company's correction (kept with it).
2 fields
commentstring | nullrequiredatstringrequired
appliedobject | nullrequired2 fields
atstringrequiredanywaybooleanrequiredHR applied it although the person disagreed.
can_decidebooleanrequiredcan_cancelbooleanrequiredcan_apply_anywaybooleanrequiredimportedbooleanrequiredA 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 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"
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/corrections.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "pending",
"person_id": "p3",
"waiting_for_me": true,
"from": "2026-10-01",
"to": "2026-10-31"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/corrections.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "pending",
"person_id": "p3",
"waiting_for_me": True,
"from": "2026-10-01",
"to": "2026-10-31",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_decideon My Workplace, HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–120 characters.
decision"approve" | "decline"requiredcommentstring | nullUp to 500 characters.
Returns
19 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredreasonstringrequiredstatus"pending" | "applied" | "declined" | "cancelled"requiredchangesobject[]required4 fields
op"add" | "void"requiredkind"in" | "out" | "break_start" | "break_end"requiredtimestring | nullrequiredpunch_idstring | nullrequired
beforeobject[]requiredThe day's clockings before the correction.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
afterobject[]requiredThe day's clockings with it.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
waiting_for"manager" | "hr" | "worker"requiredworker: the person confirms a correction their manager or HR made.
approverobject | nullrequired2 fields
idstringrequirednamestringrequired
requestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
decidedobject | nullrequired4 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequireddecision"approved" | "declined"requiredcommentstring | nullrequired
disputeobject | nullrequiredThe person disagreed with the company's correction (kept with it).
2 fields
commentstring | nullrequiredatstringrequired
appliedobject | nullrequired2 fields
atstringrequiredanywaybooleanrequiredHR applied it although the person disagreed.
can_decidebooleanrequiredcan_cancelbooleanrequiredcan_apply_anywaybooleanrequiredimportedbooleanrequiredA 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 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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/corrections.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"correction_id": "co1",
"decision": "decline",
"comment": "I left at 17:30"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/corrections.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"correction_id": "co1",
"decision": "decline",
"comment": "I left at 17:30",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_anywayon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–120 characters.
commentstringrequired3–500 characters.
Returns
19 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredreasonstringrequiredstatus"pending" | "applied" | "declined" | "cancelled"requiredchangesobject[]required4 fields
op"add" | "void"requiredkind"in" | "out" | "break_start" | "break_end"requiredtimestring | nullrequiredpunch_idstring | nullrequired
beforeobject[]requiredThe day's clockings before the correction.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
afterobject[]requiredThe day's clockings with it.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
waiting_for"manager" | "hr" | "worker"requiredworker: the person confirms a correction their manager or HR made.
approverobject | nullrequired2 fields
idstringrequirednamestringrequired
requestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
decidedobject | nullrequired4 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequireddecision"approved" | "declined"requiredcommentstring | nullrequired
disputeobject | nullrequiredThe person disagreed with the company's correction (kept with it).
2 fields
commentstring | nullrequiredatstringrequired
appliedobject | nullrequired2 fields
atstringrequiredanywaybooleanrequiredHR applied it although the person disagreed.
can_decidebooleanrequiredcan_cancelbooleanrequiredcan_apply_anywaybooleanrequiredimportedbooleanrequiredA 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 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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/corrections.apply_anyway', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"correction_id": "co1",
"comment": "The door log shows 15:02"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/corrections.apply_anyway",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"correction_id": "co1",
"comment": "The door log shows 15:02",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_cancelon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
correction_idstringrequired1–120 characters.
Returns
19 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredreasonstringrequiredstatus"pending" | "applied" | "declined" | "cancelled"requiredchangesobject[]required4 fields
op"add" | "void"requiredkind"in" | "out" | "break_start" | "break_end"requiredtimestring | nullrequiredpunch_idstring | nullrequired
beforeobject[]requiredThe day's clockings before the correction.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
afterobject[]requiredThe day's clockings with it.
4 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredatstringrequiredsourcestringrequired
waiting_for"manager" | "hr" | "worker"requiredworker: the person confirms a correction their manager or HR made.
approverobject | nullrequired2 fields
idstringrequirednamestringrequired
requestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
decidedobject | nullrequired4 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequireddecision"approved" | "declined"requiredcommentstring | nullrequired
disputeobject | nullrequiredThe person disagreed with the company's correction (kept with it).
2 fields
commentstring | nullrequiredatstringrequired
appliedobject | nullrequired2 fields
atstringrequiredanywaybooleanrequiredHR applied it although the person disagreed.
can_decidebooleanrequiredcan_cancelbooleanrequiredcan_apply_anywaybooleanrequiredimportedbooleanrequiredA 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 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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/corrections.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"correction_id": "co1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/corrections.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"correction_id": "co1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.unit_idstring1–120 characters.
location_idstring1–120 characters.
Returns
monthstringrequiredpeopleobject[]required8 fields
personobjectrequired3 fields
idstringrequirednamestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
status"open" | "closed" | "reopened"requiredtotalsobjectrequiredMinutes, and how many days carry each flag.
11 fields
workedintegerrequiredexpectedintegerrequiredbalanceintegerrequiredovertimeintegerrequirednightintegerrequiredholidayintegerrequiredbreaksintegerrequireddays_workedintegerrequiredflagsobjectrequiredovertime_payableintegerWhile overtime needs approval: the overtime payroll counts (approved).
overtime_unapprovedintegerWhile overtime needs approval: overtime worked beyond plan nobody approved yet.
issuesobjectrequired3 fields
open_shiftsintegerrequiredDays with a missing clock-out (close skips the person).
pending_correctionsintegerrequiredunapproved_overtimeintegerrequiredWhile overtime needs approval: minutes worked beyond plan nobody approved yet (close skips the person; timeclock_overtime_unapproved lists the days).
ack_requiredbooleanrequiredacknowledged_atstring | nullrequiredclosed_atstring | nullrequiredlimitsobject[]requiredWorking-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"requiredaverage_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"requiredvalueintegerrequiredaverage_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.
limitintegerrequiredunit"minutes" | "days"requiredfromstringrequiredtostringrequiredlawstringrequiredThe legal basis, as cited.
notestring | nullrequired
closablebooleanrequiredThe month has ended.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/months.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"month": "2026-10",
"unit_id": "u1",
"location_id": "l1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/months.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"month": "2026-10",
"unit_id": "u1",
"location_id": "l1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstring1–120 characters.
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.
Returns
11 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
monthstringrequiredstatus"open" | "closed" | "reopened"requireddigeststring | nullrequiredSHA-256 of the sealed summary (closed months).
closed_atstring | nullrequiredack_requiredbooleanrequiredacknowledged_atstring | nullrequiredcan_acknowledgebooleanrequiredsummaryobjectrequiredThe sealed summary when closed; the live one otherwise.
9 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
monthstringrequiredtimezonestringrequiredcountrystring | nullrequiredgenerated_atstringrequiredretention_yearsintegerrequireddaysobject[]required20 fields
datestringrequiredworkingbooleanrequiredholidaystring | nullrequiredcompany_daystring | nullrequiredleave"full" | "am" | "pm" | "hours"requiredTime off that day (never its type): a day-part, or hours (some hours of the day).
scheduleobject | nullrequired2 fields
startstring | nullrequiredendstring | nullrequired
plannedbooleanrequiredThe expected hours and start come from a published rota shift (Shifts), not the work schedule: Planned next to Clocked.
first_instring | nullrequiredlast_outstring | nullrequiredworkedintegerrequiredbreaksintegerrequiredexpectedintegerrequiredbalanceintegerrequiredovertimeintegerrequirednightintegerrequiredholiday_minutesintegerrequiredflagsstring (enum)[]requiredimported: 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.closedbooleanrequiredThe month is closed: nothing in it changes until HR reopens it.
punchesobject[]required13 fields
idstringrequiredkind"in" | "out" | "break_start" | "break_end"requiredatstringrequiredThe instant (ISO, UTC).
timestringrequiredLocal time in the person's time zone (HH:MM).
daystringrequiredsourcestring (enum)requiredimport: 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"requiredlate_syncbooleanrequiredAn offline clocking that reached Bizisy more than 10 minutes after its time.
correctedbooleanrequiredAdded by a correction.
voidedbooleanrequiredRemoved by a correction (kept for the history, never counted).
geofenceobject | nullrequiredGeofence mode: inside a company site or not (managers and HR).
2 fields
insidebooleanrequiredsitestring | nullrequired
geoobject | nullrequiredRecord mode: the position at the tap, ~100 m (HR in the app only; never machines or managers).
3 fields
latnumberrequiredlngnumberrequiredaccuracy_mnumber | nullrequired
geo_deniedbooleanrequired
overtime_approvalobjectOvertime 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
approvedintegerrequiredOvertime minutes approved for the day (before or after it was worked).
waitingintegerrequiredOf the unapproved minutes, those in a request still waiting for a decision.
not_overtimeintegerrequiredMinutes beyond plan an approver said are not overtime (kept as worked time, not paid as overtime).
unapprovedintegerrequiredOvertime worked beyond plan nobody approved yet (waiting included): blocks the month close.
payableintegerrequiredOvertime payroll counts: the worked overtime up to what was approved.
totalsobjectrequiredMinutes, and how many days carry each flag.
11 fields
workedintegerrequiredexpectedintegerrequiredbalanceintegerrequiredovertimeintegerrequirednightintegerrequiredholidayintegerrequiredbreaksintegerrequireddays_workedintegerrequiredflagsobjectrequiredovertime_payableintegerWhile overtime needs approval: the overtime payroll counts (approved).
overtime_unapprovedintegerWhile overtime needs approval: overtime worked beyond plan nobody approved yet.
correctionsobject[]required6 fields
daystringrequiredreasonstringrequiredrequested_asstringrequiredapplied_atstring | nullrequiredanywaybooleanrequireddisputedbooleanrequired
historyobject[]required4 fields
event"closed" | "reopened" | "acknowledged"requiredatstringrequiredreasonstring | nullrequireddigeststring | nullrequired
limitsobject[]requiredWorking-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"requiredaverage_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"requiredvalueintegerrequiredaverage_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.
limitintegerrequiredunit"minutes" | "days"requiredfromstringrequiredtostringrequiredlawstringrequiredThe legal basis, as cited.
notestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/months.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p3",
"month": "2026-10"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/months.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p3",
"month": "2026-10",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_closeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.person_idsstring[]1–120 characters. 1–5000 items.
Returns
closedstring[]requiredskippedobject[]required3 fields
person_idstringrequiredreason"open_shift" | "pending_correction" | "unapproved_overtime" | "already_closed" | "not_employed"requiredminutesintegerunapproved_overtime: the minutes waiting for approval.
remainingintegerrequiredPeople left to close (call again).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/timeclock/months.close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"month": "2026-09",
"person_ids": [
"p3"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/months.close",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"month": "2026-09",
"person_ids": [
"p3",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_reopenon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequired1–120 characters.
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.reasonstringrequired3–500 characters.
Returns
person_idstringrequiredmonthstringrequiredstatus"reopened"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/months.reopen', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p3",
"month": "2026-10",
"reason": "Payroll query"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/months.reopen",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p3",
"month": "2026-10",
"reason": "Payroll query",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_acknowledgeon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.
Returns
monthstringrequiredacknowledged_atstringrequireddigeststringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/months.acknowledge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"month": "2026-10"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/months.acknowledge",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"month": "2026-10",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_registroon HR Assistant- Preview
?dry_run=trueruns 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
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.person_idsstring[]1–120 characters. Up to 5000 items.
location_idstring1–120 characters.
format"csv" | "xlsx"Default
"xlsx".lang"en" | "es" | "pt" | "de" | "fr" | "it"Language of the headers (default en).
Returns
filesobject[]required6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
peopleintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/exports.registro', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"from": "2026-10-01",
"to": "2026-10-31",
"person_ids": [
"p3"
],
"location_id": "l1",
"format": "csv",
"lang": "es"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/exports.registro",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"from": "2026-10-01",
"to": "2026-10-31",
"person_ids": [
"p3",
],
"location_id": "l1",
"format": "csv",
"lang": "es",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_monthlyon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstring1–120 characters.
monthstringrequiredPattern
^\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
fileobjectrequired6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/exports.monthly', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p3",
"month": "2026-10",
"format": "csv",
"lang": "pt"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/exports.monthly",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p3",
"month": "2026-10",
"format": "csv",
"lang": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_payrollon HR Assistant- Preview
?dry_run=trueruns 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
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.location_idstring1–120 characters.
format"csv" | "xlsx"Default
"xlsx".lang"en" | "es" | "pt" | "de" | "fr" | "it"Language of the headers (default en).
Returns
filesobject[]required6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
peopleintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/exports.payroll', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"month": "2026-10",
"location_id": "l1",
"format": "csv",
"lang": "de"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/exports.payroll",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"month": "2026-10",
"location_id": "l1",
"format": "csv",
"lang": "de",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seton My Workplace, HR Assistant- Preview
?dry_run=trueruns 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
pinstringrequiredPattern
^\d{6}$.
Returns
pin_settruerequiredset_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/pin.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"pin": "482915"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/pin.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"pin": "482915",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_clearon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequired1–120 characters.
Returns
clearedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/pin.clear', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p3"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/pin.clear",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_importon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rowsobject[]required1–2000 items.
5 fields
person_idstring1–120 characters.
work_emailstringUp to 320 characters.
daystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.punchesobject[]required1–40 items.
5 fields
kind"in" | "out" | "break_start" | "break_end"requiredtimestringrequiredLocal time (HH:MM) in the person's time zone.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.next_daybooleanThe time is after midnight (a night shift).
place"site" | "remote"On a clock-in: on site or remote.
geoobjectWhere 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
latnumberrequiredFrom -90 to 90.
lngnumberrequiredFrom -180 to 180.
accuracy_mnumber | nullFrom 0 to 100000.
source_refstringrequiredThe record's id in the previous system: re-running the same row never records it twice.
1–200 characters.
Returns
8 fields
imported_daysintegerrequiredimported_punchesintegerrequiredpending_daysintegerrequiredDays waiting for the person to confirm them (company_edits_confirm).
pending_peopleintegerrequiredPeople asked to confirm days.
skippedintegerrequiredrefusedintegerrequiredremainingintegerrequiredRows left for another call (status later).
rowsobject[]required6 fields
indexintegerrequiredsource_refstringrequireddaystringrequiredstatus"imported" | "pending" | "skipped" | "refused" | "later"requiredimported (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)requiredOne 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 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
}
]
}
]
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/records.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}
]
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/records.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
},
],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_requeston My Workplace, HR Assistant- Preview
?dry_run=trueruns 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_idstring1–120 characters.
daystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.minutesintegerrequiredFrom 15 to 720.
reasonstringrequired3–500 characters.
Returns
16 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredminutesintegerrequiredreasonstringrequiredwhen"before" | "after"requiredbefore: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.
status"pending" | "approved" | "declined" | "cancelled"requireddeclined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).
stepsobject[]required7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredThe manager step's manager (anyone above them, or HR, may decide it too).
2 fields
idstringrequirednamestringrequired
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved without a separate decision: whoever asked could decide this step (or nobody else could).
waiting_for"manager" | "hr"requiredrequestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
capobject | nullrequiredThe 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"requiredprojectedintegerrequiredlimitintegerrequiredlawstringrequired
bulkbooleanrequiredApproved by HR with others at once (from the month close), with one reason.
can_decidebooleanrequiredcan_cancelbooleanrequiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/overtime.request', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p3",
"day": "2026-10-16",
"minutes": 60,
"reason": "Release night"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/overtime.request",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p3",
"day": "2026-10-16",
"minutes": 60,
"reason": "Release night",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"pending" | "approved" | "declined" | "cancelled"person_idstring1–120 characters.
waiting_for_mebooleanfromstringPattern
^\d{4}-\d{2}-\d{2}$.tostringPattern
^\d{4}-\d{2}-\d{2}$.
Returns
itemsobject[]required16 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredminutesintegerrequiredreasonstringrequiredwhen"before" | "after"requiredbefore: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.
status"pending" | "approved" | "declined" | "cancelled"requireddeclined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).
stepsobject[]required7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredThe manager step's manager (anyone above them, or HR, may decide it too).
2 fields
idstringrequirednamestringrequired
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved without a separate decision: whoever asked could decide this step (or nobody else could).
waiting_for"manager" | "hr"requiredrequestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
capobject | nullrequiredThe 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"requiredprojectedintegerrequiredlimitintegerrequiredlawstringrequired
bulkbooleanrequiredApproved by HR with others at once (from the month close), with one reason.
can_decidebooleanrequiredcan_cancelbooleanrequiredcreated_atstringrequiredclosed_atstring | nullrequired
waiting_for_meintegerrequiredapprovalbooleanrequiredThe company asks for overtime approval now.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/overtime.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "approved",
"person_id": "p3",
"waiting_for_me": true,
"from": "2026-10-01",
"to": "2026-10-31"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/overtime.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "approved",
"person_id": "p3",
"waiting_for_me": True,
"from": "2026-10-01",
"to": "2026-10-31",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_decideon My Workplace, HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–120 characters.
decision"approve" | "decline"requiredcommentstring | nullUp to 500 characters.
Returns
16 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredminutesintegerrequiredreasonstringrequiredwhen"before" | "after"requiredbefore: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.
status"pending" | "approved" | "declined" | "cancelled"requireddeclined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).
stepsobject[]required7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredThe manager step's manager (anyone above them, or HR, may decide it too).
2 fields
idstringrequirednamestringrequired
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved without a separate decision: whoever asked could decide this step (or nobody else could).
waiting_for"manager" | "hr"requiredrequestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
capobject | nullrequiredThe 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"requiredprojectedintegerrequiredlimitintegerrequiredlawstringrequired
bulkbooleanrequiredApproved by HR with others at once (from the month close), with one reason.
can_decidebooleanrequiredcan_cancelbooleanrequiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/overtime.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"overtime_id": "ot1",
"decision": "decline",
"comment": "Not this week"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/overtime.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"overtime_id": "ot1",
"decision": "decline",
"comment": "Not this week",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_cancelon My Workplace, HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–120 characters.
Returns
16 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
daystringrequiredminutesintegerrequiredreasonstringrequiredwhen"before" | "after"requiredbefore: asked for a day before it is worked; after: a decision on minutes already worked beyond plan.
status"pending" | "approved" | "declined" | "cancelled"requireddeclined on an after decision: the minutes are not overtime (kept as worked time, not paid as overtime).
stepsobject[]required7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredThe manager step's manager (anyone above them, or HR, may decide it too).
2 fields
idstringrequirednamestringrequired
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved without a separate decision: whoever asked could decide this step (or nobody else could).
waiting_for"manager" | "hr"requiredrequestedobjectrequired3 fields
as"self" | "manager" | "hr"requiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
atstringrequired
capobject | nullrequiredThe 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"requiredprojectedintegerrequiredlimitintegerrequiredlawstringrequired
bulkbooleanrequiredApproved by HR with others at once (from the month close), with one reason.
can_decidebooleanrequiredcan_cancelbooleanrequiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/overtime.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"overtime_id": "ot1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/overtime.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"overtime_id": "ot1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_unapprovedon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.person_idstring1–120 characters.
unit_idstring1–120 characters.
Returns
monthstringrequiredapprovalbooleanrequireditemsobject[]required9 fields
personobjectrequired3 fields
idstringrequirednamestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
daystringrequiredworkedintegerrequiredexpectedintegerrequiredovertimeintegerrequiredWorked beyond plan (minutes).
approvedintegerrequiredwaitingintegerrequiredOf unapproved, in a request still waiting.
unapprovedintegerrequiredcan_settlebooleanrequiredThe caller may approve these minutes (or say they are not overtime) with timeclock_overtime_settle.
totalsobjectrequired4 fields
daysintegerrequiredpeopleintegerrequiredminutesintegerrequiredwaitingintegerrequired
truncatedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/overtime.unapproved', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"month": "2026-10",
"person_id": "p3",
"unit_id": "u1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/overtime.unapproved",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"month": "2026-10",
"person_id": "p3",
"unit_id": "u1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_settleon My Workplace, HR Assistant- Preview
?dry_run=trueruns 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"requiredreasonstringrequired3–500 characters.
itemsobject[]1–100 items.
2 fields
person_idstringrequired1–120 characters.
daystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
monthstringPattern
^\d{4}-(0[1-9]|1[0-2])$.person_idsstring[]1–120 characters. 1–5000 items.
Returns
settledintegerrequiredDays decided.
minutesintegerrequiredMinutes approved or marked not overtime.
waitingintegerrequiredDays now waiting for a later approver (manager then HR, or HR only).
skippedobject[]required3 fields
person_idstringrequireddaystringrequiredreason"nothing_to_settle" | "not_yours" | "closed_month"required
remainingintegerrequiredDays left (call again).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/overtime.settle', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"decision": "not_overtime",
"reason": "Stayed for the party",
"items": [
{
"person_id": "p3",
"day": "2026-10-14"
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/overtime.settle",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"decision": "not_overtime",
"reason": "Stayed for the party",
"items": [
{
"person_id": "p3",
"day": "2026-10-14",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_puncheson My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required8 fields
idstringrequiredterminalstringrequiredatstringrequireddaystringrequiredtimestringrequiredstatus"held" | "dismissed"requiredreasonstring (enum)requiredOne 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 https://api.bizisy.com/v1/timeclock/my.terminal_punches \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeclock/my.terminal_punches', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/my.terminal_punches",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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.