Skip to content

API reference

Work schedules and work calendars

Fixed, flexible and rotating schedules, who follows which from when, a person's schedule history, and each workplace's work calendar with its export (the Spanish calendario laboral).

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

Work schedules#

POST/v1/timeoff/schedules.listRead

The company's work schedules (spec time-clock S1): fixed (a start, end and break per weekday), flexible (expected hours per weekday, optional core hours) or rotating (2–8 weekly patterns from an anchor Monday), each with its average weekly minutes, how many people follow it through their own assignment today and where it is the default (locations, or the company). include_archived for retired ones. Owners, admins, HR and roles with Time off at Edit.

Who can call it
Manage key owner admin hr
MCP tool
timeoff_schedules_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • include_archivedboolean

Returns

  • itemsobject[]required
    11 fields
    • idstringrequired
    • namestringrequired
    • kind"fixed" | "flexible" | "rotating"required
    • anchorstringrequired

      Rotations: the Monday its first week starts (weeks before it count backwards).

    • weeksobject | null[][]required

      One week (fixed, flexible) or 2–8 (rotating), Monday first; null = day off.

      6 fields
      • startstring | nullrequired

        Fixed and rotating days: HH:MM. An end at or before the start crosses midnight.

      • endstring | nullrequired
      • break_minutesintegerrequired
      • minutesintegerrequired

        Expected work minutes that day.

      • core_startstring | nullrequired

        Flexible days: core hours when the person is expected in (optional).

      • core_endstring | nullrequired
    • weekly_minutesintegerrequired

      Average expected minutes a week.

    • archivedbooleanrequired
    • peopleintegerrequired

      People following it today through their own assignment.

    • locationsobject[]required

      Where it is the default today (id null: the company default).

      2 fields
      • idstring | nullrequired
      • namestringrequired
    • created_atstringrequired
    • updated_atstringrequired
  • defaultsobject[]required
    3 fields
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • scheduleobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • fromstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/schedules.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_archived":true}'
Response
{
  "data": {
    "items": [
      {
        "id": "sch1",
        "name": "Office 40 h",
        "kind": "fixed",
        "anchor": "2026-10-12",
        "weeks": [
          [
            {
              "start": "09:00",
              "end": "18:00",
              "break_minutes": 60,
              "minutes": 480,
              "core_start": null,
              "core_end": null
            },
            {
              "start": "09:00",
              "end": "18:00",
              "break_minutes": 60,
              "minutes": 480,
              "core_start": null,
              "core_end": null
            },
            {
              "start": "09:00",
              "end": "18:00",
              "break_minutes": 60,
              "minutes": 480,
              "core_start": null,
              "core_end": null
            },
            {
              "start": "09:00",
              "end": "18:00",
              "break_minutes": 60,
              "minutes": 480,
              "core_start": null,
              "core_end": null
            },
            {
              "start": "09:00",
              "end": "14:00",
              "break_minutes": 0,
              "minutes": 300,
              "core_start": null,
              "core_end": null
            },
            null,
            null
          ]
        ],
        "weekly_minutes": 2220,
        "archived": false,
        "people": 4,
        "locations": [
          {
            "id": "l1",
            "name": "Lisbon HQ"
          }
        ],
        "created_at": "2026-10-01T09:00:00.000Z",
        "updated_at": "2026-10-01T09:00:00.000Z"
      }
    ],
    "defaults": [
      {
        "location": null,
        "schedule": null,
        "from": null
      },
      {
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "schedule": {
          "id": "sch1",
          "name": "Office 40 h"
        },
        "from": "2026-01-01"
      }
    ]
  }
}

Create a work schedule#

POST/v1/timeoff/schedules.createWrite

Creates a work schedule: name, kind (fixed, flexible, rotating), weeks (one week of seven days Monday first, or 2–8 for a rotation; a day is null for a day off, {start, end, break_minutes} for fixed and rotating days — an end at or before the start crosses midnight — or {minutes, core_start?, core_end?} for flexible days) and anchor (the Monday a rotation's first week starts; default this week's Monday). At most 60. Assign it with timeoff_schedules_assign. Owners, admins, HR and roles with Time off at Edit.

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

Input

  • namestringrequired

    1–80 characters.

  • kind"fixed" | "flexible" | "rotating"required
  • weeksobject | null[][]required

    Seven days, Monday first; null is a day off.

    1–8 items.

    6 fields
    • startstring | null

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

    • endstring | null

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

    • break_minutesinteger

      From 0 to 240.

    • minutesinteger

      From 1 to 1200.

    • core_startstring | null

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

    • core_endstring | null

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

  • anchorstring

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

Returns

11 fields
  • idstringrequired
  • namestringrequired
  • kind"fixed" | "flexible" | "rotating"required
  • anchorstringrequired

    Rotations: the Monday its first week starts (weeks before it count backwards).

  • weeksobject | null[][]required

    One week (fixed, flexible) or 2–8 (rotating), Monday first; null = day off.

    6 fields
    • startstring | nullrequired

      Fixed and rotating days: HH:MM. An end at or before the start crosses midnight.

    • endstring | nullrequired
    • break_minutesintegerrequired
    • minutesintegerrequired

      Expected work minutes that day.

    • core_startstring | nullrequired

      Flexible days: core hours when the person is expected in (optional).

    • core_endstring | nullrequired
  • weekly_minutesintegerrequired

    Average expected minutes a week.

  • archivedbooleanrequired
  • peopleintegerrequired

    People following it today through their own assignment.

  • locationsobject[]required

    Where it is the default today (id null: the company default).

    2 fields
    • idstring | nullrequired
    • namestringrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/schedules.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Rota",
  "kind": "rotating",
  "anchor": "2026-10-12",
  "weeks": [
    [
      {
        "start": "06:00",
        "end": "14:00",
        "break_minutes": 30
      },
      null,
      null,
      null,
      null,
      null,
      null
    ],
    [
      null,
      {
        "start": "22:00",
        "end": "06:00",
        "break_minutes": 30
      },
      null,
      null,
      null,
      null,
      null
    ]
  ]
}'
Response
{
  "data": {
    "id": "sch1",
    "name": "Rota",
    "kind": "rotating",
    "anchor": "2026-10-12",
    "weeks": [
      [
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "14:00",
          "break_minutes": 0,
          "minutes": 300,
          "core_start": null,
          "core_end": null
        },
        null,
        null
      ]
    ],
    "weekly_minutes": 2220,
    "archived": false,
    "people": 4,
    "locations": [
      {
        "id": "l1",
        "name": "Lisbon HQ"
      }
    ],
    "created_at": "2026-10-01T09:00:00.000Z",
    "updated_at": "2026-10-01T09:00:00.000Z"
  }
}

Change a work schedule#

POST/v1/timeoff/schedules.updateWrite

Changes a schedule's name, kind, weeks or anchor (same shapes as timeoff_schedules_create). The change applies to every day it covers that is not closed in the time clock: to change hours from a date, create a new schedule and assign it from that date instead. Owners, admins, HR and roles with Time off at Edit.

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

Input

  • schedule_idstringrequired

    1–120 characters.

  • namestring

    1–80 characters.

  • kind"fixed" | "flexible" | "rotating"
  • weeksobject | null[][]

    Seven days, Monday first; null is a day off.

    1–8 items.

    6 fields
    • startstring | null

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

    • endstring | null

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

    • break_minutesinteger

      From 0 to 240.

    • minutesinteger

      From 1 to 1200.

    • core_startstring | null

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

    • core_endstring | null

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

  • anchorstring

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

Returns

11 fields
  • idstringrequired
  • namestringrequired
  • kind"fixed" | "flexible" | "rotating"required
  • anchorstringrequired

    Rotations: the Monday its first week starts (weeks before it count backwards).

  • weeksobject | null[][]required

    One week (fixed, flexible) or 2–8 (rotating), Monday first; null = day off.

    6 fields
    • startstring | nullrequired

      Fixed and rotating days: HH:MM. An end at or before the start crosses midnight.

    • endstring | nullrequired
    • break_minutesintegerrequired
    • minutesintegerrequired

      Expected work minutes that day.

    • core_startstring | nullrequired

      Flexible days: core hours when the person is expected in (optional).

    • core_endstring | nullrequired
  • weekly_minutesintegerrequired

    Average expected minutes a week.

  • archivedbooleanrequired
  • peopleintegerrequired

    People following it today through their own assignment.

  • locationsobject[]required

    Where it is the default today (id null: the company default).

    2 fields
    • idstring | nullrequired
    • namestringrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/schedules.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"schedule_id":"sch1","name":"Office 39 h"}'
Response
{
  "data": {
    "id": "sch1",
    "name": "Office 39 h",
    "kind": "fixed",
    "anchor": "2026-10-12",
    "weeks": [
      [
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "14:00",
          "break_minutes": 0,
          "minutes": 300,
          "core_start": null,
          "core_end": null
        },
        null,
        null
      ]
    ],
    "weekly_minutes": 2220,
    "archived": false,
    "people": 4,
    "locations": [
      {
        "id": "l1",
        "name": "Lisbon HQ"
      }
    ],
    "created_at": "2026-10-01T09:00:00.000Z",
    "updated_at": "2026-10-01T09:00:00.000Z"
  }
}

Archive a work schedule#

POST/v1/timeoff/schedules.archiveWrite

Retires a schedule. Refused while anyone, a location or the company follows it today or from a later date: assign something else first. Its history stays. Owners, admins, HR and roles with Time off at Edit.

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

Input

  • schedule_idstringrequired

    1–120 characters.

Returns

11 fields
  • idstringrequired
  • namestringrequired
  • kind"fixed" | "flexible" | "rotating"required
  • anchorstringrequired

    Rotations: the Monday its first week starts (weeks before it count backwards).

  • weeksobject | null[][]required

    One week (fixed, flexible) or 2–8 (rotating), Monday first; null = day off.

    6 fields
    • startstring | nullrequired

      Fixed and rotating days: HH:MM. An end at or before the start crosses midnight.

    • endstring | nullrequired
    • break_minutesintegerrequired
    • minutesintegerrequired

      Expected work minutes that day.

    • core_startstring | nullrequired

      Flexible days: core hours when the person is expected in (optional).

    • core_endstring | nullrequired
  • weekly_minutesintegerrequired

    Average expected minutes a week.

  • archivedbooleanrequired
  • peopleintegerrequired

    People following it today through their own assignment.

  • locationsobject[]required

    Where it is the default today (id null: the company default).

    2 fields
    • idstring | nullrequired
    • namestringrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/schedules.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"schedule_id":"sch1"}'
Response
{
  "data": {
    "id": "sch1",
    "name": "Office 40 h",
    "kind": "fixed",
    "anchor": "2026-10-12",
    "weeks": [
      [
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "18:00",
          "break_minutes": 60,
          "minutes": 480,
          "core_start": null,
          "core_end": null
        },
        {
          "start": "09:00",
          "end": "14:00",
          "break_minutes": 0,
          "minutes": 300,
          "core_start": null,
          "core_end": null
        },
        null,
        null
      ]
    ],
    "weekly_minutes": 2220,
    "archived": true,
    "people": 0,
    "locations": [],
    "created_at": "2026-10-01T09:00:00.000Z",
    "updated_at": "2026-10-01T09:00:00.000Z"
  }
}

Assign a work schedule#

POST/v1/timeoff/schedules.assignWrite

Sets who follows a schedule from a date (spec time-clock S2), keeping the history: person_ids (up to 500: each their own schedule; schedule_id null sends them back to their location's default), location_id (that location's default) or company true (the default for locations without one; null: none). Exactly one target. A later assignment replaces an earlier one from its date; nothing is edited. Time off counts working days by the schedule of each date. Owners, admins, HR and roles with Time off at Edit.

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

Input

  • schedule_idstring | nullrequired

    1–120 characters.

  • fromstringrequired

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

  • person_idsstring[]

    1–120 characters. 1–500 items.

  • location_idstring

    1–120 characters.

  • companytrue

Returns

  • assignedintegerrequired
  • scheduleobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • fromstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/schedules.assign \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"schedule_id":"sch1","from":"2026-11-01","person_ids":["p1","p2"]}'
Response
{
  "data": {
    "assigned": 2,
    "schedule": {
      "id": "sch1",
      "name": "Office 40 h"
    },
    "from": "2026-11-01"
  }
}

A person's work schedule history#

POST/v1/timeoff/schedules.historyRead

Which schedule a person follows today and since when, and every assignment of their own (oldest first): the person, their managers and owners, admins and HR. Days from a location or company default show source location or company.

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

Input

  • person_idstringrequired

    1–120 characters.

Returns

  • currentobjectrequired
    2 fields
    • scheduleobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • source"person" | "location" | "company"required
  • itemsobject[]required
    3 fields
    • fromstringrequired
    • scheduleobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/schedules.history \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p1"}'
Response
{
  "data": {
    "current": {
      "schedule": {
        "id": "sch1",
        "name": "Office 40 h"
      },
      "source": "location"
    },
    "items": [
      {
        "from": "2026-03-01",
        "schedule": {
          "id": "sch2",
          "name": "Mornings"
        },
        "created_at": "2026-02-20T09:00:00.000Z"
      },
      {
        "from": "2026-06-01",
        "schedule": null,
        "created_at": "2026-05-28T09:00:00.000Z"
      }
    ]
  }
}

Work calendar of a location#

POST/v1/timeoff/calendar.yearRead

A location's work calendar for a year (spec time-clock S3, the Spanish calendario laboral): every day with whether it is a working day and its hours under the location's default schedule, public holidays (with their names, regions included) and company days, plus totals (working days, working minutes, holidays, company days). location_id null: the company default. Everyone in the company can read it (it is displayed in each workplace).

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

Input

  • location_idstring | nullrequired

    null: the company default (people without a location).

    1–120 characters.

  • yearintegerrequired

    From 2000 to 2100.

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

    Language of holiday names (default en).

Returns

  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • countrystringrequired
    • regionstring | nullrequired
  • yearintegerrequired
  • scheduleobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • weekly_minutesintegerrequired
  • daysobject[]required
    5 fields
    • datestringrequired
    • workingbooleanrequired
    • minutesintegerrequired
    • holidaystring | nullrequired
    • company_daystring | nullrequired
  • totalsobjectrequired
    4 fields
    • working_daysintegerrequired
    • minutesintegerrequired
    • holidaysintegerrequired
    • company_daysintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/calendar.year \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location_id":null,"year":2027,"lang":"es"}'
Response
{
  "data": {
    "location": {
      "id": "l1",
      "name": "Madrid",
      "country": "ES",
      "region": "MD"
    },
    "year": 2027,
    "schedule": {
      "id": "sch1",
      "name": "Office 40 h",
      "weekly_minutes": 2220
    },
    "days": [
      {
        "date": "2026-10-12",
        "working": false,
        "minutes": 0,
        "holiday": "Fiesta Nacional de España",
        "company_day": null
      },
      {
        "date": "2026-10-13",
        "working": true,
        "minutes": 480,
        "holiday": null,
        "company_day": null
      }
    ],
    "totals": {
      "working_days": 247,
      "minutes": 109560,
      "holidays": 14,
      "company_days": 1
    }
  }
}

Export a work calendar#

POST/v1/timeoff/calendar.exportRead

Downloads a location's work calendar for a year as CSV or XLSX (the Spanish calendario laboral, art. 34.6 ET: displayed in each workplace): the workplace, schedule, hours a week and a year, then every day with whether it is worked, its hours, and any public holiday or company day. Headers in lang (default en). Everyone in the company.

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

Input

  • location_idstring | nullrequired

    null: the company default (people without a location).

    1–120 characters.

  • yearintegerrequired

    From 2000 to 2100.

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

    Language of holiday names (default en).

  • format"csv" | "xlsx"

    Default "xlsx".

Returns

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

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/calendar.export \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location_id":"l1","year":2026,"format":"xlsx","lang":"es"}'
Response
{
  "data": {
    "file": {
      "name": "work-calendar-madrid-2026.xlsx",
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "encoding": "base64",
      "content": "UEsDBA==",
      "bytes": 4,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

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

Developer docs