Skip to content

API reference

Time off settings

Leave types, allowance policies per location with country defaults, working weeks, public holidays and company days, rules and approvals.

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

Time off settings#

POST/v1/timeoff/settings.getRead

The company's time off settings: approval mode, leave year start, whether colleagues see who is away, retention, chat and calendar outputs, and first-run setup progress. Owners, admins and HR.

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

Input

No input: send {}.

Returns

7 fields
  • approvals"off" | "manager" | "hr" | "manager_then_hr"required

    off (booked at once within the rules), manager, hr, manager_then_hr. Types may set their own.

  • year_startobjectrequired
    2 fields
    • monthintegerrequired
    • dayintegerrequired
  • colleagues_see_awaybooleanrequired

    Colleagues see who is away (dates only). Off: only managers and HR do.

  • retention_yearsintegerrequired

    Years time-off records are kept after a person's last day.

  • chat_away_todaybooleanrequired

    Post "who's away today" to the company's Slack or Teams channel (names only).

  • calendar_awaybooleanrequired

    Put out-of-office "Away" events in people's Google or Outlook calendars (with a connected calendar).

  • setupobjectrequired

    First-run setup: 1 locations and holidays, 2 allowance, 3 approvals (defaults pre-filled; each step is confirmed by HR).

    2 fields
    • stepsobject[]required
      2 fields
      • id"places" | "allowance" | "approvals"required
      • donebooleanrequired
    • completebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "approvals": "manager",
    "year_start": {
      "month": 1,
      "day": 1
    },
    "colleagues_see_away": true,
    "retention_years": 5,
    "chat_away_today": false,
    "calendar_away": false,
    "setup": {
      "steps": [
        {
          "id": "places",
          "done": true
        },
        {
          "id": "allowance",
          "done": true
        },
        {
          "id": "approvals",
          "done": false
        }
      ],
      "complete": false
    }
  }
}

Change time off settings#

POST/v1/timeoff/settings.updateWrite

Changes time off settings: approvals (off, manager, hr, manager_then_hr), year_start {month, day} (the leave year's first day; changing it moves every balance's year), colleagues_see_away, retention_years (1–10), chat_away_today, calendar_away, and setup_done (first-run steps confirmed: places, allowance, approvals). Pending requests keep their steps. Owners, admins and HR.

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

Input

  • approvals"off" | "manager" | "hr" | "manager_then_hr"
  • year_startobject
    2 fields
    • monthintegerrequired

      From 1 to 12.

    • dayintegerrequired

      From 1 to 28.

  • colleagues_see_awayboolean
  • retention_yearsinteger

    From 1 to 10.

  • chat_away_todayboolean
  • calendar_awayboolean
  • setup_done"places" | "allowance" | "approvals"[]

    Up to 3 items.

Returns

7 fields
  • approvals"off" | "manager" | "hr" | "manager_then_hr"required

    off (booked at once within the rules), manager, hr, manager_then_hr. Types may set their own.

  • year_startobjectrequired
    2 fields
    • monthintegerrequired
    • dayintegerrequired
  • colleagues_see_awaybooleanrequired

    Colleagues see who is away (dates only). Off: only managers and HR do.

  • retention_yearsintegerrequired

    Years time-off records are kept after a person's last day.

  • chat_away_todaybooleanrequired

    Post "who's away today" to the company's Slack or Teams channel (names only).

  • calendar_awaybooleanrequired

    Put out-of-office "Away" events in people's Google or Outlook calendars (with a connected calendar).

  • setupobjectrequired

    First-run setup: 1 locations and holidays, 2 allowance, 3 approvals (defaults pre-filled; each step is confirmed by HR).

    2 fields
    • stepsobject[]required
      2 fields
      • id"places" | "allowance" | "approvals"required
      • donebooleanrequired
    • completebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "year_start": {
    "month": 4,
    "day": 1
  },
  "colleagues_see_away": false,
  "retention_years": 3,
  "chat_away_today": true,
  "calendar_away": true,
  "setup_done": [
    "places",
    "allowance",
    "approvals"
  ]
}'
Response
{
  "data": {
    "approvals": "off",
    "year_start": {
      "month": 1,
      "day": 1
    },
    "colleagues_see_away": false,
    "retention_years": 3,
    "chat_away_today": true,
    "calendar_away": true,
    "setup": {
      "steps": [
        {
          "id": "places",
          "done": true
        },
        {
          "id": "allowance",
          "done": true
        },
        {
          "id": "approvals",
          "done": false
        }
      ],
      "complete": false
    }
  }
}

List leave types#

POST/v1/timeoff/types.listRead

The company's leave types (vacation, sick leave, parental, unpaid, training, other, and its own): whether each uses the balance, needs approval, who books it (self or HR), whether managers see it (health types never), colour and icon. include_archived for retired ones. Everyone.

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

Input

  • include_archivedboolean

Returns

An array of objects with 17 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • colorstringrequired
  • iconstringrequired
  • builtinbooleanrequired

    A built-in type (its name is translated in the app).

  • uses_balancebooleanrequired
  • approval"company" | "off" | "manager" | "hr" | "manager_then_hr"required
  • who_can_book"self" | "hr"required
  • visibility"away_only" | "type_visible"required

    away_only: managers see "Away" only. Health types are always away_only; colleagues and machines always see "Away".

  • healthbooleanrequired

    Health-related (special-category data, GDPR art. 9): away_only, never shown to managers or colleagues.

  • familybooleanrequired

    Protected family leave (maternity, paternity, parental, adoption; the built-in parental type always is): salary reviews give people on it the raise as if they had been at work.

  • work_accidentbooleanrequired

    Leave for a work accident: statutory safety reports count these absences as accidents and days lost (Portugal: Relatório Único Anexo D).

  • paidbooleanrequired
  • archivedbooleanrequired
  • positionintegerrequired
  • hoursbooleanrequired

    People can book some hours of a day too (timeoff_book hours), not only whole and half days.

  • hours_min_minutesinteger | nullrequired

    With hours: the shortest booking, in minutes (15-minute steps); null without hours.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/types.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_archived":true}'
Response
{
  "data": [
    {
      "id": "vacation",
      "name": "Vacation",
      "color": "teal",
      "icon": "sun",
      "builtin": true,
      "uses_balance": true,
      "approval": "company",
      "who_can_book": "self",
      "visibility": "type_visible",
      "health": false,
      "family": false,
      "work_accident": false,
      "paid": true,
      "archived": false,
      "position": 0,
      "hours": true,
      "hours_min_minutes": 60
    },
    {
      "id": "sick",
      "name": "Sick leave",
      "color": "rose",
      "icon": "thermometer",
      "builtin": true,
      "uses_balance": false,
      "approval": "company",
      "who_can_book": "hr",
      "visibility": "away_only",
      "health": true,
      "family": false,
      "work_accident": false,
      "paid": true,
      "archived": false,
      "position": 1,
      "hours": false,
      "hours_min_minutes": null
    }
  ]
}

Add a leave type#

POST/v1/timeoff/types.createWrite

Adds a leave type of the company's own (e.g. "Moving day", "Volunteering"): name, uses_balance, approval (company or a mode of its own), who_can_book (self or hr), visibility (away_only or type_visible to managers), health (health-related: forced away_only), family (protected family leave such as maternity or adoption: salary reviews treat people on it as if at work), work_accident (leave for a work accident: counted in statutory safety reports such as Portugal's Relatório Único Anexo D), paid, color, icon, hours (people can book some hours of a day; hours_min_minutes the shortest). At most 40. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
timeoff_types_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–60 characters.

  • uses_balanceboolean
  • approval"company" | "off" | "manager" | "hr" | "manager_then_hr"
  • who_can_book"self" | "hr"
  • visibility"away_only" | "type_visible"
  • healthboolean
  • paidboolean
  • familyboolean

    Protected family leave (maternity, paternity, parental, adoption): salary reviews give people on it the raise as if at work. The built-in parental type always is.

  • work_accidentboolean

    Leave for a work accident: statutory safety reports (Portugal: Relatório Único Anexo D) count these absences as accidents and days lost.

  • colorstring (enum)

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • iconstring (enum)

    One of: sun, thermometer, baby, pause, book, circle, plane, heart, home, star, briefcase, calendar.

  • positioninteger

    From 0 to 100.

  • hoursboolean

    Let people book some hours of a day (spec hourly leave). Turning it off keeps hourly bookings already made.

  • hours_min_minutesinteger

    The shortest hourly booking in minutes (15–480, 15-minute steps; default 60).

    From 15 to 480.

Returns

17 fields
  • idstringrequired
  • namestringrequired
  • colorstringrequired
  • iconstringrequired
  • builtinbooleanrequired

    A built-in type (its name is translated in the app).

  • uses_balancebooleanrequired
  • approval"company" | "off" | "manager" | "hr" | "manager_then_hr"required
  • who_can_book"self" | "hr"required
  • visibility"away_only" | "type_visible"required

    away_only: managers see "Away" only. Health types are always away_only; colleagues and machines always see "Away".

  • healthbooleanrequired

    Health-related (special-category data, GDPR art. 9): away_only, never shown to managers or colleagues.

  • familybooleanrequired

    Protected family leave (maternity, paternity, parental, adoption; the built-in parental type always is): salary reviews give people on it the raise as if they had been at work.

  • work_accidentbooleanrequired

    Leave for a work accident: statutory safety reports count these absences as accidents and days lost (Portugal: Relatório Único Anexo D).

  • paidbooleanrequired
  • archivedbooleanrequired
  • positionintegerrequired
  • hoursbooleanrequired

    People can book some hours of a day too (timeoff_book hours), not only whole and half days.

  • hours_min_minutesinteger | nullrequired

    With hours: the shortest booking, in minutes (15-minute steps); null without hours.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/types.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Volunteering",
  "uses_balance": false,
  "approval": "manager",
  "who_can_book": "self",
  "visibility": "type_visible",
  "health": false,
  "family": false,
  "paid": true,
  "color": "green",
  "icon": "heart",
  "position": 6
}'
Response
{
  "data": {
    "id": "c_01k0000000",
    "name": "Volunteering",
    "color": "green",
    "icon": "heart",
    "builtin": false,
    "uses_balance": false,
    "approval": "manager",
    "who_can_book": "self",
    "visibility": "type_visible",
    "health": false,
    "family": false,
    "work_accident": false,
    "paid": true,
    "archived": false,
    "position": 6,
    "hours": false,
    "hours_min_minutes": null
  }
}

Change a leave type#

POST/v1/timeoff/types.updateWrite

Changes a leave type (built-in or the company's own): name (built-ins: null keeps the translated name), uses_balance, approval, who_can_book, visibility, health, family (protected family leave; the built-in parental type always is), work_accident (counted in statutory safety reports), paid, color, icon, position, hours and hours_min_minutes (hourly bookings); archived true retires it (existing bookings keep it; nobody can book it), false brings it back. Vacation keeps using the balance. Health types stay away_only. Owners, admins and HR.

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

Input

  • type_idstringrequired

    1–120 characters.

  • namestring | null

    1–60 characters.

  • uses_balanceboolean
  • approval"company" | "off" | "manager" | "hr" | "manager_then_hr"
  • who_can_book"self" | "hr"
  • visibility"away_only" | "type_visible"
  • healthboolean
  • paidboolean
  • familyboolean

    Protected family leave (maternity, paternity, parental, adoption): salary reviews give people on it the raise as if at work. The built-in parental type always is.

  • work_accidentboolean

    Leave for a work accident: statutory safety reports (Portugal: Relatório Único Anexo D) count these absences as accidents and days lost.

  • colorstring (enum)

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • iconstring (enum)

    One of: sun, thermometer, baby, pause, book, circle, plane, heart, home, star, briefcase, calendar.

  • positioninteger

    From 0 to 100.

  • hoursboolean

    Let people book some hours of a day (spec hourly leave). Turning it off keeps hourly bookings already made.

  • hours_min_minutesinteger

    The shortest hourly booking in minutes (15–480, 15-minute steps; default 60).

    From 15 to 480.

  • archivedboolean

Returns

17 fields
  • idstringrequired
  • namestringrequired
  • colorstringrequired
  • iconstringrequired
  • builtinbooleanrequired

    A built-in type (its name is translated in the app).

  • uses_balancebooleanrequired
  • approval"company" | "off" | "manager" | "hr" | "manager_then_hr"required
  • who_can_book"self" | "hr"required
  • visibility"away_only" | "type_visible"required

    away_only: managers see "Away" only. Health types are always away_only; colleagues and machines always see "Away".

  • healthbooleanrequired

    Health-related (special-category data, GDPR art. 9): away_only, never shown to managers or colleagues.

  • familybooleanrequired

    Protected family leave (maternity, paternity, parental, adoption; the built-in parental type always is): salary reviews give people on it the raise as if they had been at work.

  • work_accidentbooleanrequired

    Leave for a work accident: statutory safety reports count these absences as accidents and days lost (Portugal: Relatório Único Anexo D).

  • paidbooleanrequired
  • archivedbooleanrequired
  • positionintegerrequired
  • hoursbooleanrequired

    People can book some hours of a day too (timeoff_book hours), not only whole and half days.

  • hours_min_minutesinteger | nullrequired

    With hours: the shortest booking, in minutes (15-minute steps); null without hours.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/types.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "type_id": "vacation",
  "name": null,
  "approval": "off",
  "color": "teal",
  "icon": "plane"
}'
Response
{
  "data": {
    "id": "vacation",
    "name": null,
    "color": "teal",
    "icon": "plane",
    "builtin": true,
    "uses_balance": true,
    "approval": "off",
    "who_can_book": "self",
    "visibility": "type_visible",
    "health": false,
    "family": false,
    "work_accident": false,
    "paid": true,
    "archived": false,
    "position": 0,
    "hours": true,
    "hours_min_minutes": 60
  }
}

List allowance policies#

POST/v1/timeoff/policies.listRead

The allowance policy of each location and the company default: days per leave year for a full-time person (prorated by working time and time employed), accrual (upfront or monthly), carry-over (none, all or limited, with its cap and how many months carried days last), how far below zero a balance may go, and the working week. Locations without a saved policy show their country's default (with the law it comes from; the EU minimum of 4 weeks where Bizisy has no country rule). Owners, admins and HR.

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

Input

No input: send {}.

Returns

An array of objects with 10 fields

An array of objects:

  • locationobject | nullrequired

    null: the company default.

    4 fields
    • idstringrequired
    • namestringrequired
    • countrystringrequired
    • regionstring | nullrequired
  • custombooleanrequired

    false: the country default (not saved yet).

  • annual_daysnumberrequired
  • accrual"upfront" | "monthly"required
  • carry_overobjectrequired
    3 fields
    • mode"none" | "all" | "limited"required
    • max_daysnumberrequired
    • expires_monthsinteger | nullrequired
  • negative_capnumberrequired
  • weekinteger[]required
  • defaultobjectrequired

    The country rule this default comes from.

    3 fields
    • daysnumberrequired
    • sourcestringrequired
    • basisstringrequired
  • minimumobjectrequired

    The legal minimum for this policy's working week (the country's, else the EU 4 weeks; for the company default, the highest among the locations that follow it).

    7 fields
    • daysnumberrequired

      The minimum for this working week (days a year, full-time).

    • per_5_daysnumberrequired

      The minimum on a 5-day week (prorate: per_5_days × working days a week ÷ 5, to half days).

    • countrystring | nullrequired

      null: the EU rule (no country row).

    • sourcestringrequired
    • basisstringrequired
    • urlstringrequired
    • refusebooleanrequired

      The country's rule refuses an allowance under it (otherwise a warning).

  • below_minimumbooleanrequired

    annual_days is under the legal minimum: saved, with this warning (refused only where the country's rule says so).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/policies.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": [
    {
      "location": null,
      "custom": false,
      "annual_days": 22,
      "accrual": "upfront",
      "carry_over": {
        "mode": "limited",
        "max_days": 5,
        "expires_months": 3
      },
      "negative_cap": 0,
      "week": [
        1,
        2,
        3,
        4,
        5
      ],
      "default": {
        "days": 22,
        "source": "Código do Trabalho, art. 238",
        "basis": "22 working days (dias úteis) a year"
      },
      "minimum": {
        "days": 22,
        "per_5_days": 22,
        "country": "PT",
        "source": "Código do Trabalho, art. 238",
        "basis": "22 working days (dias úteis) a year",
        "url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
        "refuse": false
      },
      "below_minimum": false
    },
    {
      "location": {
        "id": "l1",
        "name": "Lisbon HQ",
        "country": "PT",
        "region": null
      },
      "custom": true,
      "annual_days": 22,
      "accrual": "upfront",
      "carry_over": {
        "mode": "limited",
        "max_days": 5,
        "expires_months": 3
      },
      "negative_cap": 0,
      "week": [
        1,
        2,
        3,
        4,
        5
      ],
      "default": {
        "days": 22,
        "source": "Código do Trabalho, art. 238",
        "basis": "22 working days (dias úteis) a year"
      },
      "minimum": {
        "days": 22,
        "per_5_days": 22,
        "country": "PT",
        "source": "Código do Trabalho, art. 238",
        "basis": "22 working days (dias úteis) a year",
        "url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
        "refuse": false
      },
      "below_minimum": false
    }
  ]
}

Set an allowance policy#

POST/v1/timeoff/policies.setWrite

Saves the allowance policy of a location (location_id) or the company default (location_id null): annual_days (0–60; under the country's legal minimum it is saved with below_minimum true and the law in minimum, and refused only where the country's rule says so), accrual, carry_over {mode, max_days, expires_months|null}, negative_cap (0–30), week (ISO weekdays, 1 = Monday). Missing fields keep their current value (or the country default). Balances follow at once. Owners, admins and HR.

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

Input

  • location_idstring | nullrequired

    1–120 characters.

  • annual_daysnumber

    From 0 to 60.

  • accrual"upfront" | "monthly"
  • carry_overobject
    3 fields
    • mode"none" | "all" | "limited"required
    • max_daysnumberrequired

      From 0 to 60.

    • expires_monthsinteger | nullrequired

      From 1 to 24.

  • negative_capnumber

    From 0 to 30.

  • weekinteger[]

    From 1 to 7. 1–7 items.

Returns

10 fields
  • locationobject | nullrequired

    null: the company default.

    4 fields
    • idstringrequired
    • namestringrequired
    • countrystringrequired
    • regionstring | nullrequired
  • custombooleanrequired

    false: the country default (not saved yet).

  • annual_daysnumberrequired
  • accrual"upfront" | "monthly"required
  • carry_overobjectrequired
    3 fields
    • mode"none" | "all" | "limited"required
    • max_daysnumberrequired
    • expires_monthsinteger | nullrequired
  • negative_capnumberrequired
  • weekinteger[]required
  • defaultobjectrequired

    The country rule this default comes from.

    3 fields
    • daysnumberrequired
    • sourcestringrequired
    • basisstringrequired
  • minimumobjectrequired

    The legal minimum for this policy's working week (the country's, else the EU 4 weeks; for the company default, the highest among the locations that follow it).

    7 fields
    • daysnumberrequired

      The minimum for this working week (days a year, full-time).

    • per_5_daysnumberrequired

      The minimum on a 5-day week (prorate: per_5_days × working days a week ÷ 5, to half days).

    • countrystring | nullrequired

      null: the EU rule (no country row).

    • sourcestringrequired
    • basisstringrequired
    • urlstringrequired
    • refusebooleanrequired

      The country's rule refuses an allowance under it (otherwise a warning).

  • below_minimumbooleanrequired

    annual_days is under the legal minimum: saved, with this warning (refused only where the country's rule says so).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/policies.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "location_id": "l1",
  "annual_days": 25,
  "accrual": "monthly",
  "carry_over": {
    "mode": "limited",
    "max_days": 5,
    "expires_months": 3
  },
  "negative_cap": 2,
  "week": [
    1,
    2,
    3,
    4,
    5
  ]
}'
Response
{
  "data": {
    "location": {
      "id": "l1",
      "name": "Lisbon HQ",
      "country": "PT",
      "region": null
    },
    "custom": true,
    "annual_days": 25,
    "accrual": "monthly",
    "carry_over": {
      "mode": "limited",
      "max_days": 5,
      "expires_months": 3
    },
    "negative_cap": 2,
    "week": [
      1,
      2,
      3,
      4,
      5
    ],
    "default": {
      "days": 22,
      "source": "Código do Trabalho, art. 238",
      "basis": "22 working days (dias úteis) a year"
    },
    "minimum": {
      "days": 22,
      "per_5_days": 22,
      "country": "PT",
      "source": "Código do Trabalho, art. 238",
      "basis": "22 working days (dias úteis) a year",
      "url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
      "refuse": false
    },
    "below_minimum": false
  }
}

List personal working weeks and allowances#

POST/v1/timeoff/patterns.listRead

People with a working week or an allowance of their own (instead of their location's policy), e.g. part-timers on Monday to Wednesday. Owners, admins and HR.

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

Input

No input: send {}.

Returns

An array of objects:

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • annual_daysnumber | nullrequired
  • weekinteger[] | nullrequired
  • below_minimumobject | nullrequired

    Their own allowance is under the legal minimum of their location's country (else the EU 4 weeks): a warning; null otherwise.

    6 fields
    • annual_daysnumberrequired
    • minimumnumberrequired
    • countrystring | nullrequired
    • sourcestringrequired
    • basisstringrequired
    • refusebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/patterns.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": [
    {
      "person": {
        "id": "p8",
        "name": "Maria Antónia Vasconcelos de Albuquerque"
      },
      "annual_days": null,
      "week": [
        1,
        2,
        3
      ],
      "below_minimum": null
    }
  ]
}

Set a personal working week or allowance#

POST/v1/timeoff/patterns.setWrite

Gives a person their own working week (ISO weekdays, 1 = Monday; days off on other days cost nothing) and/or their own annual allowance (days for a full year, prorated by time employed; under the legal minimum of their country it is saved with below_minimum, refused only where the country's rule says so). null goes back to their location's policy. A working week shorter than the policy's prorates the allowance (instead of FTE). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
timeoff_patterns_set 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

  • person_idstringrequired

    1–120 characters.

  • weekinteger[] | null

    From 1 to 7. 1–7 items.

  • annual_daysnumber | null

    From 0 to 60.

Returns

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • annual_daysnumber | nullrequired
  • weekinteger[] | nullrequired
  • below_minimumobject | nullrequired

    Their own allowance is under the legal minimum of their location's country (else the EU 4 weeks): a warning; null otherwise.

    6 fields
    • annual_daysnumberrequired
    • minimumnumberrequired
    • countrystring | nullrequired
    • sourcestringrequired
    • basisstringrequired
    • refusebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/patterns.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p8","week":null,"annual_days":null}'
Response
{
  "data": {
    "person": {
      "id": "p8",
      "name": "Maria Antónia Vasconcelos de Albuquerque"
    },
    "annual_days": null,
    "week": [
      1,
      2,
      3
    ],
    "below_minimum": null
  }
}

Public holidays and company days#

POST/v1/timeoff/holidays.listRead

Public holidays per location for a calendar year (from each location's country and region; names in lang), with the company days off and the public holidays a location works. Everyone (it is the company calendar).

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

Input

  • yearinteger

    From 2000 to 2100.

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

    Language of holiday names (default en).

Returns

  • yearintegerrequired
  • locationsobject[]required
    3 fields
    • locationobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • countrystringrequired
      • regionstring | nullrequired
    • knownbooleanrequired

      false: no public holiday data for its country or region.

    • daysobject[]required
      3 fields
      • datestringrequired
      • namestringrequired
      • workedbooleanrequired

        The location works this public holiday.

  • company_daysobject[]required
    5 fields
    • idstringrequired
    • datestringrequired
    • namestringrequired
    • location_idstring | nullrequired
    • kind"company" | "worked"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/holidays.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"lang":"pt"}'
Response
{
  "data": {
    "year": 2026,
    "locations": [
      {
        "location": {
          "id": "l1",
          "name": "Lisbon HQ",
          "country": "PT",
          "region": null
        },
        "known": true,
        "days": [
          {
            "date": "2026-12-25",
            "name": "Christmas Day",
            "worked": false
          }
        ]
      }
    ],
    "company_days": [
      {
        "id": "do1",
        "date": "2026-12-24",
        "name": "Christmas Eve",
        "location_id": null,
        "kind": "company"
      }
    ]
  }
}

Regions with their own public holidays#

POST/v1/timeoff/holidays.regionsRead

The regions (states, provinces) of a country that have their own public holidays, with their codes (set on a location as region). Without country: the countries Bizisy has public holidays for. Everyone.

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

Input

  • countrystring

    Pattern ^[A-Z]{2}$.

Returns

An array of objects:

  • codestringrequired
  • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/holidays.regions \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"ES"}'
Response
{
  "data": [
    {
      "code": "MD",
      "name": "Comunidad de Madrid"
    }
  ]
}

Add a company day off or a worked holiday#

POST/v1/timeoff/holidays.set_dayWrite

Adds a day off for the whole company or one location (kind company, e.g. 24 December), or marks a public holiday as worked at a location (kind worked). Nobody books those days (company) or they cost a day (worked). Bookings already made are re-costed when shown; balances follow. At most 400. Owners, admins and HR.

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

Input

  • datestringrequired

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

  • namestringrequired

    1–80 characters.

  • location_idstring | null

    1–120 characters.

  • kind"company" | "worked"

Returns

  • idstringrequired
  • datestringrequired
  • namestringrequired
  • location_idstring | nullrequired
  • kind"company" | "worked"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/holidays.set_day \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "date": "2026-06-13",
  "name": "Santo António",
  "location_id": "l1",
  "kind": "company"
}'
Response
{
  "data": {
    "id": "do1",
    "date": "2026-06-13",
    "name": "Santo António",
    "location_id": null,
    "kind": "company"
  }
}

Remove a company day off or a worked holiday#

POST/v1/timeoff/holidays.delete_dayDestructive

Removes a company day off or a worked public holiday. Owners, admins and HR.

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

Input

  • idstringrequired

    1–120 characters.

Returns

  • idstringrequired
  • deletedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/holidays.delete_day \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"do1"}'
Response
{
  "data": {
    "id": "do1",
    "deleted": true
  }
}

Allowance defaults by country#

POST/v1/timeoff/defaults.listRead

The legal minimum annual leave Bizisy pre-fills per country (days on a 5-day week, with the law it comes from), and the EU fallback (Working Time Directive 2003/88/EC art. 7: 4 weeks). Only defaults: the company sets its own allowance. Everyone.

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

Input

No input: send {}.

Returns

An array of objects:

  • countrystringrequired
  • daysnumberrequired
  • sourcestringrequired
  • basisstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/defaults.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": [
    {
      "country": "PT",
      "days": 22,
      "source": "Código do Trabalho, art. 238",
      "basis": "22 working days (dias úteis) a year"
    }
  ]
}

Rule templates#

POST/v1/timeoff/rules.templatesRead

The quick rules a company can turn on (anytimeoff's 17 templates in 10 categories): balance (minimum reserve), notice (minimum notice), duration (max consecutive, minimum length, whole days only), eligibility (probation, new joiners), staffing (minimum staff per team, max concurrent, max percentage off), compliance (a long break each year), blackout periods, and cancellation rules (no late cancellation, no cancelling started leave…). Each with its parameters and their defaults. For anything else write a custom rule (template_id "custom", see timeoff_rules_reference). Owners, admins and HR.

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

Input

No input: send {}.

Returns

An array of objects with 7 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • descriptionstringrequired
  • categorystringrequired
  • applies_to"booking" | "cancellation"required
  • paramsobject[]required
    7 fields
    • namestringrequired
    • labelstringrequired
    • descriptionstringrequired
    • typestringrequired
    • defaultany
    • minnumber
    • maxnumber
  • variablesobject[]required

    Numbers the rule reads per team (e.g. minimum staff): set them in params.

    4 fields
    • namestringrequired
    • labelstringrequired
    • descriptionstringrequired
    • defaultnumberrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.templates \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": [
    {
      "id": "minimum-notice",
      "name": "Minimum notice",
      "description": "Bookings must be made a number of days ahead.",
      "category": "notice",
      "applies_to": "booking",
      "params": [
        {
          "name": "noticeDays",
          "label": "Notice days",
          "description": "Days of notice.",
          "type": "number",
          "default": 14,
          "min": 0,
          "max": 365
        }
      ],
      "variables": []
    }
  ]
}

Rules language reference#

POST/v1/timeoff/rules.referenceRead

What a custom rule's condition (CEL) can use, from the engine itself: every variable with its type, what it is checked against (each day, the whole booking, the leave year, the booking being cancelled) and whether it exists when booking, cancelling or both; the fields of list items (period.runs); functions; list macros; the placeholders a message may use; the limits; and worked examples. Read it before writing a rule, then check the rule with timeoff_rules_validate. Owners, admins and HR.

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

Input

No input: send {}.

Returns

7 fields
  • variablesobject[]required
    5 fields
    • pathstringrequired
    • typestringrequired
    • unit"day" | "booking" | "year" | "cancellation"required
    • descriptionstringrequired
    • applies_to"booking" | "cancellation"[]required
  • elementsobject[]required
    2 fields
    • collectionstringrequired
    • fieldsobject[]required
      3 fields
      • namestringrequired
      • typestringrequired
      • descriptionstringrequired
  • functionsobject[]required
    3 fields
    • namestringrequired
    • signaturestringrequired
    • descriptionstringrequired
  • macrosobject[]required
    3 fields
    • namestringrequired
    • signaturestringrequired
    • descriptionstringrequired
  • placeholdersobject[]required
    4 fields
    • pathstringrequired
    • descriptionstringrequired
    • applies_to"booking" | "cancellation"[]required
    • per_day_onlybooleanrequired
  • limitsobjectrequired
    5 fields
    • condition_charsnumberrequired
    • message_charsnumberrequired
    • macro_callsnumberrequired
    • paramsnumberrequired
    • budget_msnumberrequired
  • examplesobject[]required
    5 fields
    • titlestringrequired
    • applies_to"booking" | "cancellation"required
    • conditionstringrequired
    • messagestringrequired
    • paramsobjectrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.reference \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "variables": [
      {
        "path": "day.noticeDays",
        "type": "number",
        "unit": "day",
        "description": "Whole days from `now` to this day",
        "applies_to": [
          "booking"
        ]
      }
    ],
    "elements": [
      {
        "collection": "period.runs",
        "fields": [
          {
            "name": "workingDays",
            "type": "number",
            "description": "Working days in the run"
          }
        ]
      }
    ],
    "functions": [
      {
        "name": "between",
        "signature": "between(x, a, b) -> bool",
        "description": "True iff x is in [a, b] inclusive"
      }
    ],
    "macros": [
      {
        "name": "exists",
        "signature": "list.exists(x, condition) -> bool",
        "description": "True if at least one item meets the condition"
      }
    ],
    "placeholders": [
      {
        "path": "day.date",
        "description": "The day that breaks the rule (per-day rules)",
        "applies_to": [
          "booking"
        ],
        "per_day_only": true
      }
    ],
    "limits": {
      "condition_chars": 1000,
      "message_chars": 300,
      "macro_calls": 12,
      "params": 10,
      "budget_ms": 50
    },
    "examples": [
      {
        "title": "No cancelling in the last week",
        "applies_to": "cancellation",
        "condition": "cancellation.daysUntilStart < 7",
        "message": "Time off starting on ${cancellation.startDate} can no longer be cancelled: ask HR.",
        "params": {}
      }
    ]
  }
}

Check a custom rule#

POST/v1/timeoff/rules.validateRead

Checks a custom rule's condition (CEL) and message without saving anything: it must read, use only variables and functions from timeoff_rules_reference that exist for the rule's kind (booking or cancellation), not mix per-day and per-cancellation variables, stay within the limits (length, list macros, no macro inside another), give true or false on a sample booking, and the message may only use approved placeholders. Returns every problem with the field it is about. Saving refuses the same problems. Owners, admins and HR.

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

Input

  • conditionstringrequired

    Up to 4000 characters.

  • applies_to"booking" | "cancellation"

    booking (default) or cancellation.

  • paramsobject

    The rule's named parameters (rule.params.<name>).

  • messagestring | null

    Up to 1000 characters.

Returns

  • validbooleanrequired
  • issuesobject[]required
    4 fields
    • field"condition" | "message" | "params"required
    • codestringrequired
    • messagestringrequired
    • refstring | nullrequired
  • unit"day" | "booking" | "year" | "cancellation"required

    What it checks: each day, the whole booking, the leave year, or the booking being cancelled.

  • variablesstring[]required

    The variables it reads.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.validate \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "condition": "cancellation.daysUntilStart < rule.params.days",
  "applies_to": "cancellation",
  "params": {
    "days": 7
  },
  "message": "Too late to cancel ${cancellation.startDate}."
}'
Response
{
  "data": {
    "valid": false,
    "issues": [
      {
        "field": "condition",
        "code": "unknown_variable",
        "message": "There is no variable request.bookedWorkingDayz.",
        "ref": "request.bookedWorkingDayz"
      }
    ],
    "unit": "booking",
    "variables": [
      "request.bookedWorkingDayz"
    ]
  }
}

List time off rules#

POST/v1/timeoff/rules.listRead

The company's time off rules: template or custom, parameters, outcome (block, warn, needs_approval), what each checks (unit), scope (locations, teams, people; empty: everyone), leave types, on or off, a summary in plain words, and how many saved bookings each affected in the last 90 days. Owners, admins and HR.

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

Input

No input: send {}.

Returns

An array of objects with 16 fields

An array of objects:

  • idstringrequired
  • template_idstringrequired

    A quick template's id, or "custom" for a condition the company wrote.

  • kind"template" | "custom"required
  • namestringrequired
  • paramsobjectrequired
  • outcome"block" | "warn" | "needs_approval"required
  • applies_to"booking" | "cancellation"required
  • scopeobjectrequired
    3 fields
    • location_idsstring[]required
    • unit_idsstring[]required
    • person_idsstring[]required
  • type_idsstring[]required
  • activebooleanrequired
  • messagestring | nullrequired

    The company's own message (null: the template's).

  • conditionstring | nullrequired

    Custom rules: the CEL condition (true: the rule applies). Templates: null.

  • unit"day" | "booking" | "year" | "cancellation"required

    What it checks: each day booked, the whole booking, the leave year, or the booking being cancelled.

  • summarystringrequired

    In plain words (English).

  • updated_atstringrequired
  • affected_90dnumberrequired

    Saved bookings in the last 90 days it warned about, sent for approval, or that HR recorded despite it (refused bookings aren't saved).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": [
    {
      "id": "r1",
      "template_id": "minimum-notice",
      "name": "Minimum notice",
      "params": {
        "noticeDays": 14
      },
      "outcome": "warn",
      "applies_to": "booking",
      "scope": {
        "location_ids": [],
        "unit_ids": [],
        "person_ids": []
      },
      "type_ids": [
        "vacation"
      ],
      "active": true,
      "message": null,
      "updated_at": "2026-09-01T10:00:00.000Z",
      "kind": "template",
      "condition": null,
      "unit": "day",
      "summary": "Warns about bookings of vacation for everyone: Bookings must be made a number of days ahead (Minimum Notice (Days): 14).",
      "affected_90d": 3
    },
    {
      "id": "r2",
      "template_id": "custom",
      "name": "No Fridays in summer",
      "params": {},
      "outcome": "block",
      "applies_to": "booking",
      "scope": {
        "location_ids": [],
        "unit_ids": [],
        "person_ids": []
      },
      "type_ids": [],
      "active": true,
      "message": "${day.date} is a Friday in the summer rota.",
      "updated_at": "2026-09-01T10:00:00.000Z",
      "kind": "custom",
      "condition": "day.dayOfWeek == 5 && between(day.date, \"2026-07-01\", \"2026-08-31\")",
      "unit": "day",
      "summary": "Refuses bookings for everyone: when day.dayOfWeek == 5 && between(day.date, \"2026-07-01\", \"2026-08-31\").",
      "affected_90d": 0
    }
  ]
}

Add a time off rule#

POST/v1/timeoff/rules.createWrite

Turns on a rule: a template (timeoff_rules_templates) with its parameters, or a custom rule (template_id "custom") with a CEL condition, applies_to and a message (check it first with timeoff_rules_validate; save refuses the same problems). outcome: block (refused), warn (allowed, shown), needs_approval (sent to the manager, then HR, even when approvals are off). Optional scope (locations, teams, people) and type_ids; a message in your own words (approved placeholders only). Try it on a person first with timeoff_rules_try. At most 60. Owners, admins and HR.

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

Input

  • template_idstringrequired

    1–120 characters.

  • namestring

    1–100 characters.

  • paramsobject
  • outcome"block" | "warn" | "needs_approval"
  • scopeobject
    3 fields
    • location_idsstring[]

      1–120 characters. Up to 100 items.

    • unit_idsstring[]

      1–120 characters. Up to 200 items.

    • person_idsstring[]

      1–120 characters. Up to 500 items.

  • type_idsstring[]

    1–120 characters. Up to 40 items.

  • activeboolean
  • messagestring | null

    What people read when it applies, in your words: text with ${…} placeholders from timeoff_rules_reference (dates and day counts of the booking or cancellation, and ${rule.params.<name>}). At most 300 characters. Required for custom rules; templates default to their English message.

    1–1000 characters.

  • conditionstring

    Custom rules only: the CEL condition, true when the rule applies (at most 1000 characters). Check it with timeoff_rules_validate first.

    Up to 4000 characters.

  • applies_to"booking" | "cancellation"

    Custom rules only: booking (default) or cancellation.

Returns

15 fields
  • idstringrequired
  • template_idstringrequired

    A quick template's id, or "custom" for a condition the company wrote.

  • kind"template" | "custom"required
  • namestringrequired
  • paramsobjectrequired
  • outcome"block" | "warn" | "needs_approval"required
  • applies_to"booking" | "cancellation"required
  • scopeobjectrequired
    3 fields
    • location_idsstring[]required
    • unit_idsstring[]required
    • person_idsstring[]required
  • type_idsstring[]required
  • activebooleanrequired
  • messagestring | nullrequired

    The company's own message (null: the template's).

  • conditionstring | nullrequired

    Custom rules: the CEL condition (true: the rule applies). Templates: null.

  • unit"day" | "booking" | "year" | "cancellation"required

    What it checks: each day booked, the whole booking, the leave year, or the booking being cancelled.

  • summarystringrequired

    In plain words (English).

  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "template_id": "max-concurrent-leave",
  "name": "Two away at most",
  "params": {
    "max_concurrent_leave": 2
  },
  "outcome": "block",
  "scope": {
    "unit_ids": [
      "u1"
    ]
  },
  "type_ids": [
    "vacation"
  ],
  "active": true,
  "message": "At most two people in Engineering can be away at once."
}'
Response
{
  "data": {
    "id": "r1",
    "template_id": "minimum-notice",
    "name": "Two away at most",
    "params": {
      "noticeDays": 14
    },
    "outcome": "block",
    "applies_to": "booking",
    "scope": {
      "location_ids": [],
      "unit_ids": [],
      "person_ids": []
    },
    "type_ids": [
      "vacation"
    ],
    "active": true,
    "message": "At most two people in Engineering can be away at once.",
    "updated_at": "2026-09-01T10:00:00.000Z",
    "kind": "template",
    "condition": null,
    "unit": "day",
    "summary": "Warns about bookings of vacation for everyone: Bookings must be made a number of days ahead (Minimum Notice (Days): 14)."
  }
}

Change a time off rule#

POST/v1/timeoff/rules.updateWrite

Changes a rule's name, parameters, outcome, scope, types, message, or turns it off (active false); a custom rule's condition and applies_to too (checked like timeoff_rules_validate). Owners, admins and HR.

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

Input

  • rule_idstringrequired

    1–120 characters.

  • namestring

    1–100 characters.

  • paramsobject
  • outcome"block" | "warn" | "needs_approval"
  • scopeobject
    3 fields
    • location_idsstring[]

      1–120 characters. Up to 100 items.

    • unit_idsstring[]

      1–120 characters. Up to 200 items.

    • person_idsstring[]

      1–120 characters. Up to 500 items.

  • type_idsstring[]

    1–120 characters. Up to 40 items.

  • activeboolean
  • messagestring | null

    What people read when it applies, in your words: text with ${…} placeholders from timeoff_rules_reference (dates and day counts of the booking or cancellation, and ${rule.params.<name>}). At most 300 characters. Required for custom rules; templates default to their English message.

    1–1000 characters.

  • conditionstring

    Custom rules only: the CEL condition, true when the rule applies (at most 1000 characters). Check it with timeoff_rules_validate first.

    Up to 4000 characters.

  • applies_to"booking" | "cancellation"

    Custom rules only: booking (default) or cancellation.

Returns

15 fields
  • idstringrequired
  • template_idstringrequired

    A quick template's id, or "custom" for a condition the company wrote.

  • kind"template" | "custom"required
  • namestringrequired
  • paramsobjectrequired
  • outcome"block" | "warn" | "needs_approval"required
  • applies_to"booking" | "cancellation"required
  • scopeobjectrequired
    3 fields
    • location_idsstring[]required
    • unit_idsstring[]required
    • person_idsstring[]required
  • type_idsstring[]required
  • activebooleanrequired
  • messagestring | nullrequired

    The company's own message (null: the template's).

  • conditionstring | nullrequired

    Custom rules: the CEL condition (true: the rule applies). Templates: null.

  • unit"day" | "booking" | "year" | "cancellation"required

    What it checks: each day booked, the whole booking, the leave year, or the booking being cancelled.

  • summarystringrequired

    In plain words (English).

  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "rule_id": "r1",
  "params": {
    "noticeDays": 7
  },
  "outcome": "block",
  "scope": {
    "location_ids": [
      "l1"
    ],
    "unit_ids": [],
    "person_ids": []
  },
  "message": null
}'
Response
{
  "data": {
    "id": "r1",
    "template_id": "minimum-notice",
    "name": "Minimum notice",
    "params": {
      "noticeDays": 14
    },
    "outcome": "block",
    "applies_to": "booking",
    "scope": {
      "location_ids": [],
      "unit_ids": [],
      "person_ids": []
    },
    "type_ids": [
      "vacation"
    ],
    "active": false,
    "message": null,
    "updated_at": "2026-09-01T10:00:00.000Z",
    "kind": "template",
    "condition": null,
    "unit": "day",
    "summary": "Warns about bookings of vacation for everyone: Bookings must be made a number of days ahead (Minimum Notice (Days): 14)."
  }
}

Delete a time off rule#

POST/v1/timeoff/rules.deleteDestructive

Deletes a rule. Bookings already made keep their warnings. Owners, admins and HR.

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

Input

  • rule_idstringrequired

    1–120 characters.

Returns

  • idstringrequired
  • deletedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.delete \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rule_id":"r1"}'
Response
{
  "data": {
    "id": "r1",
    "deleted": true
  }
}

Try a time off rule#

POST/v1/timeoff/rules.tryRead

Tries a rule before saving it (nothing is saved): the same input as timeoff_rules_create (or rule_id for a saved rule, with any changes), checked against a person, a leave type and days. A booking rule as if they booked those days; a cancellation rule as if those days were booked and then cancelled. Returns whether the person is in the rule's scope (it is checked either way), the verdict (pass, fail, or unknown when it can't be decided — that never blocks — with the reason), the message they would read and the days that broke it. Owners, admins and HR.

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

Input

  • ruleobjectrequired
    11 fields
    • template_idstring

      1–120 characters.

    • namestring

      1–100 characters.

    • paramsobject
    • outcome"block" | "warn" | "needs_approval"
    • scopeobject
      3 fields
      • location_idsstring[]

        1–120 characters. Up to 100 items.

      • unit_idsstring[]

        1–120 characters. Up to 200 items.

      • person_idsstring[]

        1–120 characters. Up to 500 items.

    • type_idsstring[]

      1–120 characters. Up to 40 items.

    • activeboolean
    • messagestring | null

      What people read when it applies, in your words: text with ${…} placeholders from timeoff_rules_reference (dates and day counts of the booking or cancellation, and ${rule.params.<name>}). At most 300 characters. Required for custom rules; templates default to their English message.

      1–1000 characters.

    • conditionstring

      Custom rules only: the CEL condition, true when the rule applies (at most 1000 characters). Check it with timeoff_rules_validate first.

      Up to 4000 characters.

    • applies_to"booking" | "cancellation"

      Custom rules only: booking (default) or cancellation.

    • rule_idstring

      A saved rule to start from.

      1–120 characters.

  • person_idstringrequired

    1–120 characters.

  • type_idstring

    Default: the first leave type the rule covers, else vacation.

    1–120 characters.

  • startstringrequired

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

  • endstringrequired

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

  • start_part"full" | "am" | "pm"
  • end_part"full" | "am" | "pm"

Returns

11 fields
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • type_idstringrequired
  • in_scopebooleanrequired
  • out_of_scope"person" | "team" | "location" | "type"required

    Why it wouldn't apply to them.

  • state"pass" | "fail" | "unknown"required
  • outcome"block" | "warn" | "needs_approval"required
  • messagestring | nullrequired
  • daysstring[]required
  • unit"day" | "booking" | "year" | "cancellation"required
  • reasonstring | nullrequired
  • working_daysnumberrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/rules.try \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rule": {
    "rule_id": "r2",
    "template_id": "custom",
    "condition": "day.dayOfWeek == 5",
    "message": "Not on Fridays (${day.date}).",
    "outcome": "warn",
    "scope": {
      "unit_ids": [
        "u1"
      ]
    }
  },
  "person_id": "p3",
  "type_id": "vacation",
  "start": "2026-07-03",
  "end": "2026-07-03",
  "start_part": "am",
  "end_part": "am"
}'
Response
{
  "data": {
    "person": {
      "id": "p3",
      "name": "Sofia Martins"
    },
    "type_id": "vacation",
    "in_scope": true,
    "out_of_scope": null,
    "state": "fail",
    "outcome": "block",
    "message": "Not on Fridays (2026-07-03).",
    "days": [
      "2026-07-03"
    ],
    "unit": "day",
    "reason": null,
    "working_days": 0.5
  }
}

Working-time rules#

POST/v1/timeoff/working_time.getRead

The working-time rules per country, for the countries of the company's locations (and any asked in countries): daily rest, longest day, weekly rest, the 48-hour week and its average, breaks, the night period and the notice of a schedule change, each with the law it comes from, and the company's own values where it set them (a collective agreement or an adaptability regime). The time clock and shift rotas check against these. Portugal, Spain and Germany have their own rows; other countries the EU Working Time Directive floor. Anyone in the company may read them.

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

Input

  • countriesstring[]

    Up to 30 items. Pattern ^[A-Z]{2}$.

Returns

  • countriesobject[]required
    5 fields
    • countrystringrequired

      ISO code; rules of countries without their own row are the EU Directive floor.

    • sourcestringrequired
    • lawobjectrequired

      The law's values (minutes; notice in days; null where the law sets none).

      11 fields
      • restintegerrequired
      • day_maxinteger | nullrequired
      • week_maxintegerrequired
      • average_weeksintegerrequired
      • notice_daysinteger | nullrequired
      • micro_notice_daysinteger | nullrequired
      • weekly_restobjectrequired
        4 fields
        • minutesintegerrequired
        • window_daysintegerrequired
        • average_daysinteger | nullrequired
        • rest_daysinteger | nullrequired
      • breaksobjectrequired
        2 fields
        • afterany[][]required
        • max_stretchinteger | nullrequired
      • nightobjectrequired
        2 fields
        • startstringrequired
        • endstringrequired
      • shift_change_after_restbooleanrequired
      • lawobjectrequired
        7 fields
        • reststringrequired
        • weekly_reststringrequired
        • day_maxstring | nullrequired
        • week_maxstringrequired
        • breaksstringrequired
        • noticestringrequired
        • shift_changestring | nullrequired
    • companyobjectrequired

      What applies: the law with the company's own values on top.

      11 fields
      • restintegerrequired
      • day_maxinteger | nullrequired
      • week_maxintegerrequired
      • average_weeksintegerrequired
      • notice_daysinteger | nullrequired
      • micro_notice_daysinteger | nullrequired
      • weekly_restobjectrequired
        4 fields
        • minutesintegerrequired
        • window_daysintegerrequired
        • average_daysinteger | nullrequired
        • rest_daysinteger | nullrequired
      • breaksobjectrequired
        2 fields
        • afterany[][]required
        • max_stretchinteger | nullrequired
      • nightobjectrequired
        2 fields
        • startstringrequired
        • endstringrequired
      • shift_change_after_restbooleanrequired
      • lawobjectrequired
        7 fields
        • reststringrequired
        • weekly_reststringrequired
        • day_maxstring | nullrequired
        • week_maxstringrequired
        • breaksstringrequired
        • noticestringrequired
        • shift_changestring | nullrequired
    • overridesobjectrequired
      5 fields
      • restinteger
      • day_maxinteger | null
      • week_maxinteger
      • notice_daysinteger
      • legal_basisstring

        Why a value is weaker than the law (e.g. a collective agreement reference).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/working_time.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries":["FR"]}'
Response
{
  "data": {
    "countries": [
      {
        "country": "PT",
        "source": "Código do Trabalho arts. 202, 203, 211, 213, 214, 217, 221, 223, 231, 232",
        "law": {
          "rest": 660,
          "day_max": 480,
          "week_max": 2880,
          "average_weeks": 17,
          "notice_days": 7,
          "micro_notice_days": 3,
          "weekly_rest": {
            "minutes": 1440,
            "window_days": 7,
            "average_days": null,
            "rest_days": 1
          },
          "breaks": {
            "after": [],
            "max_stretch": 300
          },
          "night": {
            "start": "22:00",
            "end": "07:00"
          },
          "shift_change_after_rest": true,
          "law": {
            "rest": "Código do Trabalho art. 214",
            "weekly_rest": "Código do Trabalho art. 232",
            "day_max": "Código do Trabalho art. 203",
            "week_max": "Código do Trabalho art. 211",
            "breaks": "Código do Trabalho art. 213",
            "notice": "Código do Trabalho art. 217 n.º 2",
            "shift_change": "Código do Trabalho art. 221 n.º 4"
          }
        },
        "company": {
          "rest": 660,
          "day_max": 600,
          "week_max": 2880,
          "average_weeks": 17,
          "notice_days": 7,
          "micro_notice_days": 3,
          "weekly_rest": {
            "minutes": 1440,
            "window_days": 7,
            "average_days": null,
            "rest_days": 1
          },
          "breaks": {
            "after": [],
            "max_stretch": 300
          },
          "night": {
            "start": "22:00",
            "end": "07:00"
          },
          "shift_change_after_rest": true,
          "law": {
            "rest": "Código do Trabalho art. 214",
            "weekly_rest": "Código do Trabalho art. 232",
            "day_max": "Código do Trabalho art. 203",
            "week_max": "Código do Trabalho art. 211",
            "breaks": "Código do Trabalho art. 213",
            "notice": "Código do Trabalho art. 217 n.º 2",
            "shift_change": "Código do Trabalho art. 221 n.º 4"
          }
        },
        "overrides": {
          "day_max": 600,
          "legal_basis": "CCT hotelaria, cl. 12"
        }
      }
    ]
  }
}

Change working-time rules#

POST/v1/timeoff/working_time.updateWrite

Sets the company's own working-time values for one country, on top of the law (a collective agreement, an adaptability regime or a stricter company rule): rest (minutes between two working days, 660–1440), day_max (longest day in minutes, null: no daily limit), week_max (minutes, at most 2880), notice_days (days' notice of a schedule change, 0–60). null for a field (except day_max) or reset: true goes back to the law. Never below the EU Working Time Directive (11 h daily rest, a 48 h average week) nor below the country's notice of a schedule change. A value weaker than the country's law (less rest, a longer or unlimited day) needs legal_basis: the collective agreement or regime that allows it (at most 300 characters, no personal data); it is shown to rota editors next to the findings. An API key or AI app may only make values stricter. The time clock flags and shift rota checks follow at once. Owners, admins and HR.

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

Input

  • countrystringrequired

    Pattern ^[A-Z]{2}$.

  • restinteger | null

    From 0 to 1440.

  • day_maxinteger | null

    From 60 to 1440.

  • week_maxinteger | null

    From 60 to 10080.

  • notice_daysinteger | null

    From 0 to 60.

  • legal_basisstring | null

    The collective agreement or regime that allows a value weaker than the law, e.g. "CCT hotelaria, cl. 12". No personal data. null clears it.

    1–300 characters.

  • resetboolean

Returns

  • countriesobject[]required
    5 fields
    • countrystringrequired

      ISO code; rules of countries without their own row are the EU Directive floor.

    • sourcestringrequired
    • lawobjectrequired

      The law's values (minutes; notice in days; null where the law sets none).

      11 fields
      • restintegerrequired
      • day_maxinteger | nullrequired
      • week_maxintegerrequired
      • average_weeksintegerrequired
      • notice_daysinteger | nullrequired
      • micro_notice_daysinteger | nullrequired
      • weekly_restobjectrequired
        4 fields
        • minutesintegerrequired
        • window_daysintegerrequired
        • average_daysinteger | nullrequired
        • rest_daysinteger | nullrequired
      • breaksobjectrequired
        2 fields
        • afterany[][]required
        • max_stretchinteger | nullrequired
      • nightobjectrequired
        2 fields
        • startstringrequired
        • endstringrequired
      • shift_change_after_restbooleanrequired
      • lawobjectrequired
        7 fields
        • reststringrequired
        • weekly_reststringrequired
        • day_maxstring | nullrequired
        • week_maxstringrequired
        • breaksstringrequired
        • noticestringrequired
        • shift_changestring | nullrequired
    • companyobjectrequired

      What applies: the law with the company's own values on top.

      11 fields
      • restintegerrequired
      • day_maxinteger | nullrequired
      • week_maxintegerrequired
      • average_weeksintegerrequired
      • notice_daysinteger | nullrequired
      • micro_notice_daysinteger | nullrequired
      • weekly_restobjectrequired
        4 fields
        • minutesintegerrequired
        • window_daysintegerrequired
        • average_daysinteger | nullrequired
        • rest_daysinteger | nullrequired
      • breaksobjectrequired
        2 fields
        • afterany[][]required
        • max_stretchinteger | nullrequired
      • nightobjectrequired
        2 fields
        • startstringrequired
        • endstringrequired
      • shift_change_after_restbooleanrequired
      • lawobjectrequired
        7 fields
        • reststringrequired
        • weekly_reststringrequired
        • day_maxstring | nullrequired
        • week_maxstringrequired
        • breaksstringrequired
        • noticestringrequired
        • shift_changestring | nullrequired
    • overridesobjectrequired
      5 fields
      • restinteger
      • day_maxinteger | null
      • week_maxinteger
      • notice_daysinteger
      • legal_basisstring

        Why a value is weaker than the law (e.g. a collective agreement reference).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/working_time.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "country": "PT",
  "rest": 720,
  "week_max": null,
  "notice_days": 10,
  "legal_basis": null
}'
Response
{
  "data": {
    "countries": [
      {
        "country": "PT",
        "source": "Código do Trabalho arts. 202, 203, 211, 213, 214, 217, 221, 223, 231, 232",
        "law": {
          "rest": 660,
          "day_max": 480,
          "week_max": 2880,
          "average_weeks": 17,
          "notice_days": 7,
          "micro_notice_days": 3,
          "weekly_rest": {
            "minutes": 1440,
            "window_days": 7,
            "average_days": null,
            "rest_days": 1
          },
          "breaks": {
            "after": [],
            "max_stretch": 300
          },
          "night": {
            "start": "22:00",
            "end": "07:00"
          },
          "shift_change_after_rest": true,
          "law": {
            "rest": "Código do Trabalho art. 214",
            "weekly_rest": "Código do Trabalho art. 232",
            "day_max": "Código do Trabalho art. 203",
            "week_max": "Código do Trabalho art. 211",
            "breaks": "Código do Trabalho art. 213",
            "notice": "Código do Trabalho art. 217 n.º 2",
            "shift_change": "Código do Trabalho art. 221 n.º 4"
          }
        },
        "company": {
          "rest": 660,
          "day_max": 600,
          "week_max": 2880,
          "average_weeks": 17,
          "notice_days": 7,
          "micro_notice_days": 3,
          "weekly_rest": {
            "minutes": 1440,
            "window_days": 7,
            "average_days": null,
            "rest_days": 1
          },
          "breaks": {
            "after": [],
            "max_stretch": 300
          },
          "night": {
            "start": "22:00",
            "end": "07:00"
          },
          "shift_change_after_rest": true,
          "law": {
            "rest": "Código do Trabalho art. 214",
            "weekly_rest": "Código do Trabalho art. 232",
            "day_max": "Código do Trabalho art. 203",
            "week_max": "Código do Trabalho art. 211",
            "breaks": "Código do Trabalho art. 213",
            "notice": "Código do Trabalho art. 217 n.º 2",
            "shift_change": "Código do Trabalho art. 221 n.º 4"
          }
        },
        "overrides": {
          "day_max": 600,
          "legal_basis": "CCT hotelaria, cl. 12"
        }
      }
    ]
  }
}

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

Developer docs