Skip to content

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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    18 fields
    • idstringrequired
    • namestringrequired
    • vendor"zkteco" | "other"required
    • serialstring | nullrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • directions"auto" | "device"required

      auto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.

    • allowed_ipsstring[]required

      Addresses the terminal may call from; empty: any.

    • address_last4string | nullrequired

      The last 4 characters of its server address (ZKTeco), to tell addresses apart.

    • status"never" | "online" | "offline" | "revoked"required

      offline: no contact for 60 minutes.

    • offline_hoursinteger | nullrequired

      Whole hours since the last contact, when offline.

    • last_contact_atstring | nullrequired
    • last_event_atstring | nullrequired
    • heldintegerrequired

      Its punches waiting in To match.

    • droppedintegerrequired

      Punches not kept: To match was full, or a request had more lines than Bizisy reads.

    • connectionobjectrequired
      4 fields
      • ipstring | nullrequired

        The internet address of its last request (ZKTeco).

      • protocol"http" | "https"required
      • previous_ipstring | nullrequired
      • ip_changed_atstring | nullrequired
    • warnings"plain_http" | "ip_changed"[]required

      plain_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_atstringrequired
    • revokedbooleanrequired
  • heldintegerrequired

    Punches waiting in To match, all terminals.

  • limitintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/terminals.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • namestringrequired

    1–60 characters.

  • vendor"zkteco" | "other"

    Default "zkteco".

  • serialstring

    ZKTeco: the serial number (Menu → System info → Device info).

    Up to 40 characters.

  • location_idstring | null

    1–120 characters.

  • directions"auto" | "device"

    Default "auto".

  • allowed_ipsstring[]

    Up to 60 characters. Up to 10 items.

Returns

  • terminalobjectrequired
    18 fields
    • idstringrequired
    • namestringrequired
    • vendor"zkteco" | "other"required
    • serialstring | nullrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • directions"auto" | "device"required

      auto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.

    • allowed_ipsstring[]required

      Addresses the terminal may call from; empty: any.

    • address_last4string | nullrequired

      The last 4 characters of its server address (ZKTeco), to tell addresses apart.

    • status"never" | "online" | "offline" | "revoked"required

      offline: no contact for 60 minutes.

    • offline_hoursinteger | nullrequired

      Whole hours since the last contact, when offline.

    • last_contact_atstring | nullrequired
    • last_event_atstring | nullrequired
    • heldintegerrequired

      Its punches waiting in To match.

    • droppedintegerrequired

      Punches not kept: To match was full, or a request had more lines than Bizisy reads.

    • connectionobjectrequired
      4 fields
      • ipstring | nullrequired

        The internet address of its last request (ZKTeco).

      • protocol"http" | "https"required
      • previous_ipstring | nullrequired
      • ip_changed_atstring | nullrequired
    • warnings"plain_http" | "ip_changed"[]required

      plain_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_atstringrequired
    • revokedbooleanrequired
  • setupobjectrequired
    2 fields
    • terminal_idstringrequired

      For timeclock.punches.ingest.

    • server_addressstring | nullrequired

      ZKTeco: 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
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"
  ]
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • terminal_idstringrequired

    1–120 characters.

  • namestring

    1–60 characters.

  • location_idstring | null

    1–120 characters.

  • directions"auto" | "device"
  • allowed_ipsstring[]

    Up to 60 characters. Up to 10 items.

  • serialstring

    Up to 40 characters.

Returns

  • terminalobjectrequired
    18 fields
    • idstringrequired
    • namestringrequired
    • vendor"zkteco" | "other"required
    • serialstring | nullrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • directions"auto" | "device"required

      auto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.

    • allowed_ipsstring[]required

      Addresses the terminal may call from; empty: any.

    • address_last4string | nullrequired

      The last 4 characters of its server address (ZKTeco), to tell addresses apart.

    • status"never" | "online" | "offline" | "revoked"required

      offline: no contact for 60 minutes.

    • offline_hoursinteger | nullrequired

      Whole hours since the last contact, when offline.

    • last_contact_atstring | nullrequired
    • last_event_atstring | nullrequired
    • heldintegerrequired

      Its punches waiting in To match.

    • droppedintegerrequired

      Punches not kept: To match was full, or a request had more lines than Bizisy reads.

    • connectionobjectrequired
      4 fields
      • ipstring | nullrequired

        The internet address of its last request (ZKTeco).

      • protocol"http" | "https"required
      • previous_ipstring | nullrequired
      • ip_changed_atstring | nullrequired
    • warnings"plain_http" | "ip_changed"[]required

      plain_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_atstringrequired
    • revokedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_rotate on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • terminal_idstringrequired

    1–120 characters.

Returns

  • terminalobjectrequired
    18 fields
    • idstringrequired
    • namestringrequired
    • vendor"zkteco" | "other"required
    • serialstring | nullrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • directions"auto" | "device"required

      auto: each punch toggles in/out (and ends a break); device: the terminal's in/out/break keys decide.

    • allowed_ipsstring[]required

      Addresses the terminal may call from; empty: any.

    • address_last4string | nullrequired

      The last 4 characters of its server address (ZKTeco), to tell addresses apart.

    • status"never" | "online" | "offline" | "revoked"required

      offline: no contact for 60 minutes.

    • offline_hoursinteger | nullrequired

      Whole hours since the last contact, when offline.

    • last_contact_atstring | nullrequired
    • last_event_atstring | nullrequired
    • heldintegerrequired

      Its punches waiting in To match.

    • droppedintegerrequired

      Punches not kept: To match was full, or a request had more lines than Bizisy reads.

    • connectionobjectrequired
      4 fields
      • ipstring | nullrequired

        The internet address of its last request (ZKTeco).

      • protocol"http" | "https"required
      • previous_ipstring | nullrequired
      • ip_changed_atstring | nullrequired
    • warnings"plain_http" | "ip_changed"[]required

      plain_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_atstringrequired
    • revokedbooleanrequired
  • setupobjectrequired
    2 fields
    • terminal_idstringrequired

      For timeclock.punches.ingest.

    • server_addressstring | nullrequired

      ZKTeco: 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
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"}'
Response
{
  "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_revoke on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • terminal_idstringrequired

    1–120 characters.

Returns

  • revokedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeclock/terminals.revoke \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"terminal_id":"t1"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • qstring

    Up to 80 characters.

  • person_idstring

    1–120 characters.

  • offsetinteger

    At least 0. Default 0.

  • limitinteger

    From 1 to 200. Default 100.

Returns

  • itemsobject[]required
    3 fields
    • badgestringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • created_atstringrequired
  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_import on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • rowsobject[]required

    1–480 items.

    3 fields
    • badgestringrequired

      Pattern ^[A-Za-z0-9]{1,24}$.

    • person_idstring

      1–120 characters.

    • work_emailstring

      Up to 320 characters.

  • replaceboolean

    Default false.

Returns

7 fields
  • addedintegerrequired
  • movedintegerrequired
  • unchangedintegerrequired
  • refusedintegerrequired
  • held_waitingintegerrequired
  • rowsobject[]required
    4 fields
    • indexintegerrequired
    • badgestringrequired
    • status"added" | "unchanged" | "moved" | "refused"required
    • reason"unknown_person" | "ambiguous_email" | "not_employed" | "taken" | "duplicate_row"required
  • movesobject[]required

    Badges 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
    • badgestringrequired
    • from_person_idstringrequired
    • to_person_idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
    }
  ]
}'
Response
{
  "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_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • badgestringrequired

    Pattern ^[A-Za-z0-9]{1,24}$.

Returns

  • removedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_held on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • terminal_idstring

    1–120 characters.

  • reasonstring (enum)

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

  • badgestring

    Pattern ^[A-Za-z0-9]{1,24}$.

  • offsetinteger

    At least 0. Default 0.

Returns

  • itemsobject[]required
    11 fields
    • idstringrequired
    • terminalobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • badgestring | nullrequired
    • personobject | nullrequired

      Whose punch it is (a known badge refused by a rule), or the person the badge is now mapped to.

      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • daystringrequired
    • timestringrequired

      Local time at the terminal (HH:MM).

    • direction"auto" | "in" | "out" | "break_start" | "break_end"required
    • reasonstring (enum)required

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

    • reason_textstringrequired
    • received_atstringrequired
  • totalintegerrequired
  • badgesobject[]required

    Unknown badges with how many punches each (all of them, not only this page).

    5 fields
    • badgestringrequired
    • countintegerrequired
    • first_atstringrequired
    • last_atstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_match on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • badgestringrequired

    Pattern ^[A-Za-z0-9]{1,24}$.

  • person_idstringrequired

    1–120 characters.

Returns

  • recordedintegerrequired
  • pendingintegerrequired

    Punches older than 15 minutes, waiting for the person to confirm them (company_edits_confirm): HR attributed them.

  • still_heldintegerrequired
  • duplicatesintegerrequired
  • remainingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_apply on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idsstring[]required

    1–120 characters. 1–100 items.

Returns

  • recordedintegerrequired
  • still_heldintegerrequired
  • duplicatesintegerrequired
  • resultsobject[]required
    5 fields
    • indexintegerrequired
    • statusstring (enum)required

      recorded; 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 | nullrequired
    • punch_idstring | nullrequired
    • person_idstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_dismiss on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idsstring[]required

    1–120 characters. 1–200 items.

Returns

  • dismissedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_ingest on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • terminal_idstringrequired

    1–120 characters.

  • eventsobject[]required

    1–100 items.

    5 fields
    • event_idstring

      The event's id on the terminal or middleware: the same id twice counts once.

      1–100 characters.

    • badgestringrequired

      The badge number or terminal user id (mapped to a person under Terminals → Badges).

      Pattern ^[A-Za-z0-9]{1,24}$.

    • atdate-time

      The instant, with its offset (2026-10-13T09:00:12+02:00).

      ISO 8601 date and time (UTC).

    • localstring

      Or 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

  • recordedintegerrequired
  • pendingintegerrequired

    Waiting for the person to confirm them.

  • duplicatesintegerrequired
  • heldintegerrequired
  • ignoredintegerrequired
  • resultsobject[]required
    5 fields
    • indexintegerrequired
    • statusstring (enum)required

      recorded; 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 | nullrequired
    • punch_idstring | nullrequired
    • person_idstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
    }
  ]
}'
Response
{
  "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.

Developer docs