API reference
Time clock settings and kiosks
Switching the time clock on, who approves corrections, location (off, record, geofence) and workplaces, reminders, retention and acknowledgement per country, and shared kiosks.
5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Time clock settings#
POST/v1/timeclock/settings.getRead
The company's time clock settings: on or off, who approves corrections, whether company corrections wait for the person's confirmation, how far back people correct themselves, late grace, offline window, location rule and workplaces, clock-out reminders, the rules and retention for each country it has a location in, and first-run setup progress. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
16 fields
enabledbooleanrequiredThe company uses the time clock: people see the clock button; until then nobody is asked to clock.
corrections"off" | "manager" | "hr"requiredWho approves a person's own corrections: off (applied at once, still recorded), manager (HR when there is none), hr.
company_edits_confirmbooleanrequiredA manager's or HR's correction of someone's record waits for that person's confirmation (Spain's draft decree: both authorise).
self_daysintegerrequiredHow many days back people may ask for a correction themselves.
late_graceintegerrequiredMinutes after the scheduled start before a clock-in counts as late.
offline_hoursintegerrequiredOffline clockings are accepted up to this many hours after their time.
geolocation"off" | "record" | "geofence"requiredoff (default); record (the position at the tap, ~100 m, HR only); geofence (only inside or outside a workplace).
geofence_requiredbooleanrequiredgeofence: clocking outside every workplace is refused (the person can ask for a correction).
sitesobject[]required6 fields
idstringrequirednamestringrequiredlocation_idstring | nullrequiredlatnumberrequiredlngnumberrequiredradius_mintegerrequired
remind_clock_outbooleanrequiredRemind people still clocked in an hour after their day (in the app, and by push when they turned it on).
overtime_approvalbooleanrequiredOvertime needs approval before it's worked (spec 2026-11-17-hcm-gaps §10): requests go through Approval rules → Overtime, unapproved minutes worked beyond plan block the month close, and payroll counts only approved overtime. Off by default.
overtime_approval_sincestring | nullrequiredThe day approval was last switched on: days before it never need approval.
overtime_selfbooleanrequiredPeople may ask for their own overtime (else their manager or HR asks).
overtime_rule"manager" | "hr" | "manager_then_hr"requiredWho approves overtime (Approval rules → Overtime): manager — the manager approves their team's, HR a manager's own and anyone's without a manager (default); hr; manager_then_hr.
countriesobject[]requiredThe rules for each country the company has a location in (C8), with the company's overrides.
9 fields
countrystringrequiredsourcestringrequiredretention_yearsintegerrequireddefault_retention_yearsintegerrequiredacknowledgebooleanrequireddefault_acknowledgebooleanrequirednightobjectrequired2 fields
startstringrequiredendstringrequired
day_maxinteger | nullrequiredrestintegerrequired
setupobjectrequired2 fields
stepsobject[]required2 fields
id"turn_on" | "approvals" | "places" | "retention"requireddonebooleanrequired
completebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeclock/settings.get', {
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/settings.get",
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,
"corrections": "manager",
"company_edits_confirm": true,
"self_days": 31,
"late_grace": 10,
"offline_hours": 72,
"geolocation": "geofence",
"geofence_required": false,
"sites": [
{
"id": "s1",
"name": "Madrid office",
"location_id": "l1",
"lat": 40.4168,
"lng": -3.7038,
"radius_m": 200
}
],
"remind_clock_out": true,
"overtime_approval": true,
"overtime_approval_since": "2026-10-01",
"overtime_self": false,
"overtime_rule": "manager",
"countries": [
{
"country": "ES",
"source": "Estatuto de los Trabajadores arts. 34, 35, 36",
"retention_years": 4,
"default_retention_years": 4,
"acknowledge": true,
"default_acknowledge": true,
"night": {
"start": "22:00",
"end": "06:00"
},
"day_max": 540,
"rest": 720
}
],
"setup": {
"steps": [
{
"id": "turn_on",
"done": true
},
{
"id": "approvals",
"done": true
},
{
"id": "places",
"done": false
},
{
"id": "retention",
"done": false
}
],
"complete": false
}
}
}Change time clock settings#
POST/v1/timeclock/settings.updateWrite
Changes time clock settings (API keys and AI apps: not location, corrections, overtime approval or retention — those in the app only): enabled, overtime_approval (overtime needs approval before it's worked; switching it on applies from today), overtime_self (people ask for their own), overtime_rule (manager, hr, manager_then_hr), corrections (off, manager, hr), company_edits_confirm, self_days (0–92), late_grace (0–120), offline_hours (1–168), geolocation (off, record, geofence), geofence_required, sites (the whole list, at most 50: {id?, name, location_id?, lat, lng, radius_m 30–5000}), remind_clock_out, retention ({country: years 1–10}; a shorter period deletes older records at the next daily sweep), acknowledge ({country: true/false}), setup_done. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Location, corrections, overtime approval and retention settings are changed in the app only.
- MCP tool
timeclock_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
enabledbooleancorrections"off" | "manager" | "hr"company_edits_confirmbooleanself_daysintegerFrom 0 to 92.
late_graceintegerFrom 0 to 120.
offline_hoursintegerFrom 1 to 168.
geolocation"off" | "record" | "geofence"geofence_requiredbooleansitesobject[]Up to 50 items.
6 fields
idstring1–40 characters.
namestringrequired1–80 characters.
location_idstring | null1–120 characters.
latnumberrequiredFrom -90 to 90.
lngnumberrequiredFrom -180 to 180.
radius_mintegerrequiredFrom 30 to 5000.
remind_clock_outbooleanovertime_approvalbooleanovertime_selfbooleanovertime_rule"manager" | "hr" | "manager_then_hr"retentionobjectacknowledgeobjectsetup_done"turn_on" | "approvals" | "places" | "retention"[]Up to 4 items.
Returns
16 fields
enabledbooleanrequiredThe company uses the time clock: people see the clock button; until then nobody is asked to clock.
corrections"off" | "manager" | "hr"requiredWho approves a person's own corrections: off (applied at once, still recorded), manager (HR when there is none), hr.
company_edits_confirmbooleanrequiredA manager's or HR's correction of someone's record waits for that person's confirmation (Spain's draft decree: both authorise).
self_daysintegerrequiredHow many days back people may ask for a correction themselves.
late_graceintegerrequiredMinutes after the scheduled start before a clock-in counts as late.
offline_hoursintegerrequiredOffline clockings are accepted up to this many hours after their time.
geolocation"off" | "record" | "geofence"requiredoff (default); record (the position at the tap, ~100 m, HR only); geofence (only inside or outside a workplace).
geofence_requiredbooleanrequiredgeofence: clocking outside every workplace is refused (the person can ask for a correction).
sitesobject[]required6 fields
idstringrequirednamestringrequiredlocation_idstring | nullrequiredlatnumberrequiredlngnumberrequiredradius_mintegerrequired
remind_clock_outbooleanrequiredRemind people still clocked in an hour after their day (in the app, and by push when they turned it on).
overtime_approvalbooleanrequiredOvertime needs approval before it's worked (spec 2026-11-17-hcm-gaps §10): requests go through Approval rules → Overtime, unapproved minutes worked beyond plan block the month close, and payroll counts only approved overtime. Off by default.
overtime_approval_sincestring | nullrequiredThe day approval was last switched on: days before it never need approval.
overtime_selfbooleanrequiredPeople may ask for their own overtime (else their manager or HR asks).
overtime_rule"manager" | "hr" | "manager_then_hr"requiredWho approves overtime (Approval rules → Overtime): manager — the manager approves their team's, HR a manager's own and anyone's without a manager (default); hr; manager_then_hr.
countriesobject[]requiredThe rules for each country the company has a location in (C8), with the company's overrides.
9 fields
countrystringrequiredsourcestringrequiredretention_yearsintegerrequireddefault_retention_yearsintegerrequiredacknowledgebooleanrequireddefault_acknowledgebooleanrequirednightobjectrequired2 fields
startstringrequiredendstringrequired
day_maxinteger | nullrequiredrestintegerrequired
setupobjectrequired2 fields
stepsobject[]required2 fields
id"turn_on" | "approvals" | "places" | "retention"requireddonebooleanrequired
completebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"corrections": "hr",
"company_edits_confirm": false,
"self_days": 7,
"late_grace": 5,
"offline_hours": 48,
"geolocation": "geofence",
"geofence_required": true,
"sites": [
{
"name": "Madrid office",
"location_id": "l1",
"lat": 40.4168,
"lng": -3.7038,
"radius_m": 200
}
],
"remind_clock_out": false,
"retention": {
"ES": 4
},
"acknowledge": {
"PT": false
},
"setup_done": [
"turn_on",
"approvals"
]
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"corrections": "hr",
"company_edits_confirm": false,
"self_days": 7,
"late_grace": 5,
"offline_hours": 48,
"geolocation": "geofence",
"geofence_required": true,
"sites": [
{
"name": "Madrid office",
"location_id": "l1",
"lat": 40.4168,
"lng": -3.7038,
"radius_m": 200
}
],
"remind_clock_out": false,
"retention": {
"ES": 4
},
"acknowledge": {
"PT": false
},
"setup_done": [
"turn_on",
"approvals"
]
}),
});
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/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"corrections": "hr",
"company_edits_confirm": False,
"self_days": 7,
"late_grace": 5,
"offline_hours": 48,
"geolocation": "geofence",
"geofence_required": True,
"sites": [
{
"name": "Madrid office",
"location_id": "l1",
"lat": 40.4168,
"lng": -3.7038,
"radius_m": 200,
},
],
"remind_clock_out": False,
"retention": {
"ES": 4,
},
"acknowledge": {
"PT": False,
},
"setup_done": [
"turn_on",
"approvals",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"enabled": true,
"corrections": "hr",
"company_edits_confirm": false,
"self_days": 7,
"late_grace": 5,
"offline_hours": 48,
"geolocation": "geofence",
"geofence_required": true,
"sites": [
{
"id": "s1",
"name": "Madrid office",
"location_id": "l1",
"lat": 40.4168,
"lng": -3.7038,
"radius_m": 200
}
],
"remind_clock_out": false,
"overtime_approval": true,
"overtime_approval_since": "2026-10-01",
"overtime_self": false,
"overtime_rule": "manager",
"countries": [
{
"country": "ES",
"source": "Estatuto de los Trabajadores arts. 34, 35, 36",
"retention_years": 4,
"default_retention_years": 4,
"acknowledge": true,
"default_acknowledge": true,
"night": {
"start": "22:00",
"end": "06:00"
},
"day_max": 540,
"rest": 720
}
],
"setup": {
"steps": [
{
"id": "turn_on",
"done": true
},
{
"id": "approvals",
"done": true
},
{
"id": "places",
"done": false
},
{
"id": "retention",
"done": false
}
],
"complete": false
}
}
}Kiosks#
POST/v1/timeclock/kiosks.listRead
The company's clocking kiosks (shared tablets): name, location, when it was last used, revoked or paused (too many wrong PINs). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_kiosks_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required7 fields
idstringrequirednamestringrequiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
created_atstringrequiredlast_used_atstring | nullrequiredrevokedbooleanrequiredpaused_untilstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/kiosks.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeclock/kiosks.list', {
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/kiosks.list",
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": "k1",
"name": "Front desk",
"location": {
"id": "l1",
"name": "Madrid"
},
"created_at": "2026-10-01T09:00:00.000Z",
"last_used_at": "2026-10-13T07:00:00.000Z",
"revoked": false,
"paused_until": null
}
]
}
}Set up a kiosk#
POST/v1/timeclock/kiosks.createWrite
Creates a clocking kiosk for a location (spec time-clock C13) and returns its setup link, shown once: open it on the shared tablet (it keeps the device key; the key is in the link's #fragment, never sent to a server log). People at that location clock there with their own PIN. At most 50. In the app only.
- Web app only
- Refused for API keys and connected apps. Kiosks are set up in the app only (the result is a one-time device link).
- MCP tool
timeclock_kiosks_createon 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
namestringrequired1–60 characters.
location_idstring | null1–120 characters.
Returns
kioskobjectrequired7 fields
idstringrequirednamestringrequiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
created_atstringrequiredlast_used_atstring | nullrequiredrevokedbooleanrequiredpaused_untilstring | nullrequired
setup_pathstringrequired/kiosk#k=<device key>: open on the tablet at the company address.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/kiosks.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Front desk","location_id":"l1"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/kiosks.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Front desk",
"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, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeclock/kiosks.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Front desk",
"location_id": "l1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"kiosk": {
"id": "k1",
"name": "Front desk",
"location": {
"id": "l1",
"name": "Madrid"
},
"created_at": "2026-10-01T09:00:00.000Z",
"last_used_at": "2026-10-13T07:00:00.000Z",
"revoked": false,
"paused_until": null
},
"setup_path": "/kiosk#k=k1.abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQ"
}
}Revoke a kiosk#
POST/v1/timeclock/kiosks.revokeWrite
Stops a kiosk at once (a lost or replaced tablet): its device key no longer works. Clockings made there stay. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_kiosks_revokeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
kiosk_idstringrequired1–120 characters.
Returns
revokedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/kiosks.revoke \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"kiosk_id":"k1"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/kiosks.revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"kiosk_id": "k1"
}),
});
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/kiosks.revoke",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"kiosk_id": "k1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"revoked": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.