API reference
Door terminals
Door terminals that send punches: ZKTeco terminals over ADMS/PUSH on their own address (attendance logs only; never fingerprints, faces or photos), other brands and middleware through timeclock.punches.ingest (duplicate-safe, clock-skew tolerant, at most 100 events a call). Badge numbers mapped to people (CSV in batches of 500), and the To match list of unknown badges and punches a rule held back.
13 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Terminals#
POST/v1/timeclock/terminals.listRead
The company's door terminals: name, vendor, serial number, place, direction mode, allowed addresses, the last 4 characters of the server address, when Bizisy last heard from it and whether it is offline (no contact for 60 minutes; offline_hours computed now), punches waiting in To match and punches dropped. Revoked ones last. Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required18 fields
idstringrequirednamestringrequiredvendor"zkteco" | "other"requiredserialstring | nullrequiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
directions"auto" | "device"requiredauto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.
allowed_ipsstring[]requiredAddresses the terminal may call from; empty: any.
address_last4string | nullrequiredThe last 4 characters of its server address (ZKTeco), to tell addresses apart.
status"never" | "online" | "offline" | "revoked"requiredoffline: no contact for 60 minutes.
offline_hoursinteger | nullrequiredWhole hours since the last contact, when offline.
last_contact_atstring | nullrequiredlast_event_atstring | nullrequiredheldintegerrequiredIts punches waiting in To match.
droppedintegerrequiredPunches not kept: To match was full, or a request had more lines than Bizisy reads.
connectionobjectrequired4 fields
ipstring | nullrequiredThe internet address of its last request (ZKTeco).
protocol"http" | "https"requiredprevious_ipstring | nullrequiredip_changed_atstring | nullrequired
warnings"plain_http" | "ip_changed"[]requiredplain_http: it calls over unencrypted HTTP with no allowed addresses set (anyone on the network path could read its address); ip_changed: it called from a new internet address in the last 7 days (check it is still your office's).
created_atstringrequiredrevokedbooleanrequired
heldintegerrequiredPunches waiting in To match, all terminals.
limitintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.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/terminals.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": "t1",
"name": "Front door",
"vendor": "zkteco",
"serial": "CQZ7232260123",
"location": {
"id": "l1",
"name": "Madrid"
},
"directions": "auto",
"allowed_ips": [],
"address_last4": "q7xa",
"status": "online",
"offline_hours": null,
"last_contact_at": "2026-10-13T07:00:00.000Z",
"last_event_at": "2026-10-13T07:00:00.000Z",
"held": 2,
"dropped": 0,
"connection": {
"ip": "203.0.113.9",
"protocol": "https",
"previous_ip": null,
"ip_changed_at": null
},
"warnings": [],
"created_at": "2026-10-01T09:00:00.000Z",
"revoked": false
},
{
"id": "t2",
"name": "Warehouse",
"vendor": "other",
"serial": null,
"location": {
"id": "l1",
"name": "Madrid"
},
"directions": "auto",
"allowed_ips": [],
"address_last4": null,
"status": "offline",
"offline_hours": 5,
"last_contact_at": "2026-10-13T07:00:00.000Z",
"last_event_at": "2026-10-13T07:00:00.000Z",
"held": 0,
"dropped": 0,
"connection": {
"ip": "203.0.113.9",
"protocol": "https",
"previous_ip": null,
"ip_changed_at": null
},
"warnings": [],
"created_at": "2026-10-01T09:00:00.000Z",
"revoked": false
}
],
"held": 2,
"limit": 10
}
}Add a terminal#
POST/v1/timeclock/terminals.createWrite
Adds a door terminal (spec hcm-gaps §8): name, vendor (zkteco: it calls Bizisy itself over ADMS/PUSH, serial required; other: punches come through timeclock.punches.ingest), place, direction mode (auto, default; or device keys) and optional allowed IP addresses. ZKTeco: returns the terminal's own server address once — put it in the terminal's cloud server (ADMS) settings with domain name on; anyone with the address and serial could send punches, so keep it private (rotate it if it leaks). At most 10 terminals plus one per 25 people. In the app only.
- Web app only
- Refused for API keys and connected apps. Terminals are added in the app only (the result holds the terminal's one-time server address).
- MCP tool
timeclock_terminals_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.
vendor"zkteco" | "other"Default
"zkteco".serialstringZKTeco: the serial number (Menu → System info → Device info).
Up to 40 characters.
location_idstring | null1–120 characters.
directions"auto" | "device"Default
"auto".allowed_ipsstring[]Up to 60 characters. Up to 10 items.
Returns
terminalobjectrequired18 fields
idstringrequirednamestringrequiredvendor"zkteco" | "other"requiredserialstring | nullrequiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
directions"auto" | "device"requiredauto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.
allowed_ipsstring[]requiredAddresses the terminal may call from; empty: any.
address_last4string | nullrequiredThe last 4 characters of its server address (ZKTeco), to tell addresses apart.
status"never" | "online" | "offline" | "revoked"requiredoffline: no contact for 60 minutes.
offline_hoursinteger | nullrequiredWhole hours since the last contact, when offline.
last_contact_atstring | nullrequiredlast_event_atstring | nullrequiredheldintegerrequiredIts punches waiting in To match.
droppedintegerrequiredPunches not kept: To match was full, or a request had more lines than Bizisy reads.
connectionobjectrequired4 fields
ipstring | nullrequiredThe internet address of its last request (ZKTeco).
protocol"http" | "https"requiredprevious_ipstring | nullrequiredip_changed_atstring | nullrequired
warnings"plain_http" | "ip_changed"[]requiredplain_http: it calls over unencrypted HTTP with no allowed addresses set (anyone on the network path could read its address); ip_changed: it called from a new internet address in the last 7 days (check it is still your office's).
created_atstringrequiredrevokedbooleanrequired
setupobjectrequired2 fields
terminal_idstringrequiredFor timeclock.punches.ingest.
server_addressstring | nullrequiredZKTeco: the terminal's own server address (shown once). Port 80 (HTTP) or 443 (HTTPS, where the terminal supports it).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Suprema gate",
"vendor": "other",
"directions": "device",
"allowed_ips": [
"203.0.113.0/24"
]
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Suprema gate",
"vendor": "other",
"directions": "device",
"allowed_ips": [
"203.0.113.0/24"
]
}),
});
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/terminals.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Suprema gate",
"vendor": "other",
"directions": "device",
"allowed_ips": [
"203.0.113.0/24",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"terminal": {
"id": "t1",
"name": "Front door",
"vendor": "zkteco",
"serial": "CQZ7232260123",
"location": {
"id": "l1",
"name": "Madrid"
},
"directions": "auto",
"allowed_ips": [],
"address_last4": "q7xa",
"status": "never",
"offline_hours": null,
"last_contact_at": null,
"last_event_at": null,
"held": 0,
"dropped": 0,
"connection": {
"ip": "203.0.113.9",
"protocol": "https",
"previous_ip": null,
"ip_changed_at": null
},
"warnings": [],
"created_at": "2026-10-01T09:00:00.000Z",
"revoked": false
},
"setup": {
"terminal_id": "t1",
"server_address": "tkabcdefghijklmnopqrstuvwxyz234567.bizisy.com"
}
}
}Change a terminal#
POST/v1/timeclock/terminals.updateWrite
Changes a terminal's name, place, direction mode, allowed IP addresses or serial number (a replaced device keeps its server address). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
terminal_idstringrequired1–120 characters.
namestring1–60 characters.
location_idstring | null1–120 characters.
directions"auto" | "device"allowed_ipsstring[]Up to 60 characters. Up to 10 items.
serialstringUp to 40 characters.
Returns
terminalobjectrequired18 fields
idstringrequirednamestringrequiredvendor"zkteco" | "other"requiredserialstring | nullrequiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
directions"auto" | "device"requiredauto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.
allowed_ipsstring[]requiredAddresses the terminal may call from; empty: any.
address_last4string | nullrequiredThe last 4 characters of its server address (ZKTeco), to tell addresses apart.
status"never" | "online" | "offline" | "revoked"requiredoffline: no contact for 60 minutes.
offline_hoursinteger | nullrequiredWhole hours since the last contact, when offline.
last_contact_atstring | nullrequiredlast_event_atstring | nullrequiredheldintegerrequiredIts punches waiting in To match.
droppedintegerrequiredPunches not kept: To match was full, or a request had more lines than Bizisy reads.
connectionobjectrequired4 fields
ipstring | nullrequiredThe internet address of its last request (ZKTeco).
protocol"http" | "https"requiredprevious_ipstring | nullrequiredip_changed_atstring | nullrequired
warnings"plain_http" | "ip_changed"[]requiredplain_http: it calls over unencrypted HTTP with no allowed addresses set (anyone on the network path could read its address); ip_changed: it called from a new internet address in the last 7 days (check it is still your office's).
created_atstringrequiredrevokedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"terminal_id": "t1",
"allowed_ips": [],
"directions": "device",
"location_id": null
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"terminal_id": "t1",
"allowed_ips": [],
"directions": "device",
"location_id": null
}),
});
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/terminals.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"terminal_id": "t1",
"allowed_ips": [],
"directions": "device",
"location_id": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"terminal": {
"id": "t1",
"name": "Front door",
"vendor": "zkteco",
"serial": "CQZ7232260123",
"location": {
"id": "l1",
"name": "Madrid"
},
"directions": "auto",
"allowed_ips": [],
"address_last4": "q7xa",
"status": "online",
"offline_hours": null,
"last_contact_at": "2026-10-13T07:00:00.000Z",
"last_event_at": "2026-10-13T07:00:00.000Z",
"held": 2,
"dropped": 0,
"connection": {
"ip": "203.0.113.9",
"protocol": "https",
"previous_ip": null,
"ip_changed_at": null
},
"warnings": [],
"created_at": "2026-10-01T09:00:00.000Z",
"revoked": false
}
}
}New server address for a terminal#
POST/v1/timeclock/terminals.rotateWrite
Gives a ZKTeco terminal a new server address, shown once; the old one stops working at once (a leaked address). Put the new one in the terminal. In the app only.
- Web app only
- Refused for API keys and connected apps. A new terminal address is made in the app only (it is shown once).
- MCP tool
timeclock_terminals_rotateon 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
terminal_idstringrequired1–120 characters.
Returns
terminalobjectrequired18 fields
idstringrequirednamestringrequiredvendor"zkteco" | "other"requiredserialstring | nullrequiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
directions"auto" | "device"requiredauto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.
allowed_ipsstring[]requiredAddresses the terminal may call from; empty: any.
address_last4string | nullrequiredThe last 4 characters of its server address (ZKTeco), to tell addresses apart.
status"never" | "online" | "offline" | "revoked"requiredoffline: no contact for 60 minutes.
offline_hoursinteger | nullrequiredWhole hours since the last contact, when offline.
last_contact_atstring | nullrequiredlast_event_atstring | nullrequiredheldintegerrequiredIts punches waiting in To match.
droppedintegerrequiredPunches not kept: To match was full, or a request had more lines than Bizisy reads.
connectionobjectrequired4 fields
ipstring | nullrequiredThe internet address of its last request (ZKTeco).
protocol"http" | "https"requiredprevious_ipstring | nullrequiredip_changed_atstring | nullrequired
warnings"plain_http" | "ip_changed"[]requiredplain_http: it calls over unencrypted HTTP with no allowed addresses set (anyone on the network path could read its address); ip_changed: it called from a new internet address in the last 7 days (check it is still your office's).
created_atstringrequiredrevokedbooleanrequired
setupobjectrequired2 fields
terminal_idstringrequiredFor timeclock.punches.ingest.
server_addressstring | nullrequiredZKTeco: the terminal's own server address (shown once). Port 80 (HTTP) or 443 (HTTPS, where the terminal supports it).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.rotate \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"terminal_id":"t1"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.rotate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"terminal_id": "t1"
}),
});
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/terminals.rotate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"terminal_id": "t1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"terminal": {
"id": "t1",
"name": "Front door",
"vendor": "zkteco",
"serial": "CQZ7232260123",
"location": {
"id": "l1",
"name": "Madrid"
},
"directions": "auto",
"allowed_ips": [],
"address_last4": "q7xa",
"status": "online",
"offline_hours": null,
"last_contact_at": "2026-10-13T07:00:00.000Z",
"last_event_at": "2026-10-13T07:00:00.000Z",
"held": 2,
"dropped": 0,
"connection": {
"ip": "203.0.113.9",
"protocol": "https",
"previous_ip": null,
"ip_changed_at": null
},
"warnings": [],
"created_at": "2026-10-01T09:00:00.000Z",
"revoked": false
},
"setup": {
"terminal_id": "t1",
"server_address": "tkabcdefghijklmnopqrstuvwxyz234567.bizisy.com"
}
}
}Revoke a terminal#
POST/v1/timeclock/terminals.revokeWrite
Stops a terminal at once: its address and id no longer work. Clockings it sent stay in the records; its punches waiting in To match stay until matched or dismissed. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_revokeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
terminal_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/terminals.revoke \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"terminal_id":"t1"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"terminal_id": "t1"
}),
});
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/terminals.revoke",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"terminal_id": "t1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"revoked": true
}
}Terminal badges#
POST/v1/timeclock/badges.listRead
Badge numbers (terminal user ids) and whose they are: search by badge or name (q), or one person's (person_id). At most 200 rows a call, from `offset`; total is the count matching. A badge number is job-tier data (like a work email): HR's API keys and apps see it without the private-data consent, as other job data. Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_badges_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringUp to 80 characters.
person_idstring1–120 characters.
offsetintegerAt least 0. Default
0.limitintegerFrom 1 to 200. Default
100.
Returns
itemsobject[]required3 fields
badgestringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
created_atstringrequired
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/badges.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"carl","offset":100,"limit":100}'const res = await fetch('https://api.bizisy.com/v1/timeclock/badges.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "carl",
"offset": 100,
"limit": 100
}),
});
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/badges.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "carl",
"offset": 100,
"limit": 100,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"badge": "0042",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"created_at": "2026-10-01T09:00:00.000Z"
}
],
"total": 1
}
}Map badges to people#
POST/v1/timeclock/badges.importWrite
Maps badge numbers (terminal user ids) to people: up to 480 rows {badge, person_id or work_email} a call (send a bigger CSV in several calls). A badge belongs to one person (a person may have several). A badge already mapped to someone else is refused (taken) unless replace is true. Per-row status added, unchanged, moved (replace), refused (unknown_person, ambiguous_email, not_employed, taken, duplicate_row). held_waiting: punches in To match whose badge is now mapped (apply them with timeclock_terminals_match). Dry run first. Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_badges_importon 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
rowsobject[]required1–480 items.
3 fields
badgestringrequiredPattern
^[A-Za-z0-9]{1,24}$.person_idstring1–120 characters.
work_emailstringUp to 320 characters.
replacebooleanDefault
false.
Returns
7 fields
addedintegerrequiredmovedintegerrequiredunchangedintegerrequiredrefusedintegerrequiredheld_waitingintegerrequiredrowsobject[]required4 fields
indexintegerrequiredbadgestringrequiredstatus"added" | "unchanged" | "moved" | "refused"requiredreason"unknown_person" | "ambiguous_email" | "not_employed" | "taken" | "duplicate_row"required
movesobject[]requiredBadges moved from one person to another (replace): both people are the Activity row's subjects; the earlier holder is kept in the badge's history.
3 fields
badgestringrequiredfrom_person_idstringrequiredto_person_idstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/badges.import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rows": [
{
"badge": "0042",
"work_email": "carl@acme.es"
},
{
"badge": "555",
"person_id": "p3"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/badges.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rows": [
{
"badge": "0042",
"work_email": "carl@acme.es"
},
{
"badge": "555",
"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/badges.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rows": [
{
"badge": "0042",
"work_email": "carl@acme.es",
},
{
"badge": "555",
"person_id": "p3",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"added": 1,
"moved": 0,
"unchanged": 0,
"refused": 1,
"held_waiting": 2,
"rows": [
{
"index": 0,
"badge": "0042",
"status": "added",
"reason": null
},
{
"index": 1,
"badge": "555",
"status": "refused",
"reason": "taken"
}
],
"moves": []
}
}Remove a badge#
POST/v1/timeclock/badges.removeWrite
Removes a badge number from its person (a lost or returned card): punches with it wait in To match again. Clockings already recorded stay. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_badges_removeon 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
badgestringrequiredPattern
^[A-Za-z0-9]{1,24}$.
Returns
removedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/badges.remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"badge":"0042"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/badges.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"badge": "0042"
}),
});
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/badges.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"badge": "0042",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"removed": true
}
}Terminal punches to match#
POST/v1/timeclock/terminals.heldRead
Terminal punches waiting in To match (spec hcm-gaps §8): unknown badges (reason unmatched; person is whom the badge is mapped to now, if anyone) and punches a rule refused (future, too_old, not_employed, open_shift, sequence, later_exists, closed_month, day_cap), oldest first, at most 200 a call (total is the count). Kept 92 days. Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_heldon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
terminal_idstring1–120 characters.
reasonstring (enum)One of:
unmatched,future,too_old,not_employed,open_shift,sequence,later_exists,closed_month,day_cap,off.badgestringPattern
^[A-Za-z0-9]{1,24}$.offsetintegerAt least 0. Default
0.
Returns
itemsobject[]required11 fields
idstringrequiredterminalobjectrequired2 fields
idstringrequirednamestringrequired
badgestring | nullrequiredpersonobject | nullrequiredWhose punch it is (a known badge refused by a rule), or the person the badge is now mapped to.
2 fields
idstringrequirednamestringrequired
atstringrequireddaystringrequiredtimestringrequiredLocal time at the terminal (HH:MM).
direction"auto" | "in" | "out" | "break_start" | "break_end"requiredreasonstring (enum)requiredOne of:
unmatched,future,too_old,not_employed,open_shift,sequence,later_exists,closed_month,day_cap,off.reason_textstringrequiredreceived_atstringrequired
totalintegerrequiredbadgesobject[]requiredUnknown badges with how many punches each (all of them, not only this page).
5 fields
badgestringrequiredcountintegerrequiredfirst_atstringrequiredlast_atstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.held \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"unmatched","badge":"555"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.held', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"reason": "unmatched",
"badge": "555"
}),
});
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/terminals.held",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"reason": "unmatched",
"badge": "555",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "ev1",
"terminal": {
"id": "t1",
"name": "Front door"
},
"badge": "555",
"person": null,
"at": "2026-10-13T07:01:00.000Z",
"day": "2026-10-13",
"time": "09:01",
"direction": "auto",
"reason": "unmatched",
"reason_text": "No person has this badge number yet.",
"received_at": "2026-10-13T07:01:02.000Z"
},
{
"id": "ev2",
"terminal": {
"id": "t1",
"name": "Front door"
},
"badge": "0042",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"at": "2026-10-13T07:01:00.000Z",
"day": "2026-10-13",
"time": "09:01",
"direction": "auto",
"reason": "sequence",
"reason_text": "It is out of order (for example a clock-in while already clocked in).",
"received_at": "2026-10-13T07:01:02.000Z"
}
],
"total": 2,
"badges": [
{
"badge": "555",
"count": 1,
"first_at": "2026-10-13T07:01:00.000Z",
"last_at": "2026-10-13T07:01:00.000Z",
"person": null
}
]
}
}Match a terminal badge#
POST/v1/timeclock/terminals.matchWrite
Maps an unknown badge to a person and applies its punches waiting in To match (oldest first, at most 100 a call; remaining says how many are left), through the same rules as a live punch: the ones a rule refuses stay in To match with the reason. Their age counts from when Bizisy received them. Punches older than 15 minutes are HR attributing records to the person: when the company has people confirm HR's changes (company_edits_confirm), they become a correction waiting for that person (pending) instead of being recorded. Refused when the badge already belongs to someone else (remove it first) or the person is the caller (another owner, admin or HR member matches your own badge). Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_matchon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
badgestringrequiredPattern
^[A-Za-z0-9]{1,24}$.person_idstringrequired1–120 characters.
Returns
recordedintegerrequiredpendingintegerrequiredPunches older than 15 minutes, waiting for the person to confirm them (company_edits_confirm): HR attributed them.
still_heldintegerrequiredduplicatesintegerrequiredremainingintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.match \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"badge":"555","person_id":"p3"}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.match', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"badge": "555",
"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/terminals.match",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"badge": "555",
"person_id": "p3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"recorded": 2,
"pending": 0,
"still_held": 0,
"duplicates": 0,
"remaining": 0
}
}Try terminal punches again#
POST/v1/timeclock/terminals.applyWrite
Tries punches waiting in To match again (after correcting the day, reopening the month or mapping the badge): up to 100 ids from timeclock_terminals_held, through the same rules as a live punch. Those still refused stay with the new reason. Never your own punches. Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_applyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idsstring[]required1–120 characters. 1–100 items.
Returns
recordedintegerrequiredstill_heldintegerrequiredduplicatesintegerrequiredresultsobject[]required5 fields
indexintegerrequiredstatusstring (enum)requiredrecorded; pending (sent long after its time: waits for the person to confirm it, as HR's corrections do); duplicate (already recorded, or a second tap within a minute); held (waits in To match: see reason); ignored (from before the terminal was added); dropped (To match is full); invalid (see reason: direction_needed, own_records, closed_month, correction_waiting, order, needs_confirmation, too_many).
One of:
recorded,pending,duplicate,held,ignored,dropped,invalid.reasonstring | nullrequiredpunch_idstring | nullrequiredperson_idstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.apply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["ev1"]}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.apply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"ids": [
"ev1"
]
}),
});
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/terminals.apply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"ids": [
"ev1",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"recorded": 1,
"still_held": 0,
"duplicates": 0,
"results": [
{
"index": 0,
"status": "recorded",
"reason": null,
"punch_id": "pu9",
"person_id": "p3"
}
]
}
}Dismiss terminal punches#
POST/v1/timeclock/terminals.dismissWrite
Removes punches from To match without recording them (a test card, a visitor): up to 200 ids. They are deleted after 92 days. Owners, admins and HR (also their API keys).
- Who can call it
- Manage key owner admin hr
- MCP tool
timeclock_terminals_dismisson HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idsstring[]required1–120 characters. 1–200 items.
Returns
dismissedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/terminals.dismiss \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["ev1"]}'const res = await fetch('https://api.bizisy.com/v1/timeclock/terminals.dismiss', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"ids": [
"ev1"
]
}),
});
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/terminals.dismiss",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"ids": [
"ev1",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"dismissed": 1
}
}Send terminal punches#
POST/v1/timeclock/punches.ingestWrite
Punches from a door terminal's own software or middleware (spec hcm-gaps §8), for a terminal added in Time clock → Terminals: up to 100 events {event_id?, badge, at (ISO with offset) or local (terminal wall time), direction auto|in|out|break_start|break_end}. Badges only: each must be mapped to a person under Terminals → Badges (unknown ones wait in To match). Events within 15 minutes of now are recorded at once through the same rules as phone and kiosk clockings, as "Terminal". Older ones are the company's edit of the person's record: they need a direction (invalid, direction_needed, otherwise), and when the company has people confirm HR's changes (company_edits_confirm, the default) each day's punches become one correction waiting for that person (status pending; refused with closed_month, correction_waiting, order, needs_confirmation or too_many); with the setting off they are recorded as the clock import would. Duplicate-safe (the same event_id, or badge and time, counts once; a second tap within a minute too); clocks up to 15 minutes ahead are tolerated; punches older than the company's offline window and punches a rule refuses wait in To match. Never for the caller's own badge (invalid, own_records). Only the app (a person signed in) and owners', admins' and HR's API keys; everything else (connected AI apps, MCP) is refused.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Only owners', admins' and HR's API keys (a terminal's software), never connected AI apps or MCP; punches sent over 15 minutes late wait for the person's confirmation.
- MCP tool
timeclock_punches_ingeston HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
terminal_idstringrequired1–120 characters.
eventsobject[]required1–100 items.
5 fields
event_idstringThe event's id on the terminal or middleware: the same id twice counts once.
1–100 characters.
badgestringrequiredThe badge number or terminal user id (mapped to a person under Terminals → Badges).
Pattern
^[A-Za-z0-9]{1,24}$.atdate-timeThe instant, with its offset (2026-10-13T09:00:12+02:00).
ISO 8601 date and time (UTC).
localstringOr the terminal's wall time, YYYY-MM-DD HH:MM:SS, in its place's time zone.
direction"auto" | "in" | "out" | "break_start" | "break_end"Default
"auto".
Returns
recordedintegerrequiredpendingintegerrequiredWaiting for the person to confirm them.
duplicatesintegerrequiredheldintegerrequiredignoredintegerrequiredresultsobject[]required5 fields
indexintegerrequiredstatusstring (enum)requiredrecorded; pending (sent long after its time: waits for the person to confirm it, as HR's corrections do); duplicate (already recorded, or a second tap within a minute); held (waits in To match: see reason); ignored (from before the terminal was added); dropped (To match is full); invalid (see reason: direction_needed, own_records, closed_month, correction_waiting, order, needs_confirmation, too_many).
One of:
recorded,pending,duplicate,held,ignored,dropped,invalid.reasonstring | nullrequiredpunch_idstring | nullrequiredperson_idstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeclock/punches.ingest \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"terminal_id": "t1",
"events": [
{
"event_id": "e1",
"badge": "0042",
"at": "2026-10-13T09:00:12+02:00",
"direction": "in"
},
{
"badge": "555",
"local": "2026-10-13 17:30:00"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/timeclock/punches.ingest', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"terminal_id": "t1",
"events": [
{
"event_id": "e1",
"badge": "0042",
"at": "2026-10-13T09:00:12+02:00",
"direction": "in"
},
{
"badge": "555",
"local": "2026-10-13 17:30:00"
}
]
}),
});
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/punches.ingest",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"terminal_id": "t1",
"events": [
{
"event_id": "e1",
"badge": "0042",
"at": "2026-10-13T09:00:12+02:00",
"direction": "in",
},
{
"badge": "555",
"local": "2026-10-13 17:30:00",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"recorded": 1,
"pending": 0,
"duplicates": 0,
"held": 1,
"ignored": 0,
"results": [
{
"index": 0,
"status": "recorded",
"reason": null,
"punch_id": "pu9",
"person_id": "p3"
},
{
"index": 1,
"status": "held",
"reason": "unmatched",
"punch_id": null,
"person_id": null
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.