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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
7 fields
approvals"off" | "manager" | "hr" | "manager_then_hr"requiredoff (booked at once within the rules), manager, hr, manager_then_hr. Types may set their own.
year_startobjectrequired2 fields
monthintegerrequireddayintegerrequired
colleagues_see_awaybooleanrequiredColleagues see who is away (dates only). Off: only managers and HR do.
retention_yearsintegerrequiredYears time-off records are kept after a person's last day.
chat_away_todaybooleanrequiredPost "who's away today" to the company's Slack or Teams channel (names only).
calendar_awaybooleanrequiredPut out-of-office "Away" events in people's Google or Outlook calendars (with a connected calendar).
setupobjectrequiredFirst-run setup: 1 locations and holidays, 2 allowance, 3 approvals (defaults pre-filled; each step is confirmed by HR).
2 fields
stepsobject[]required2 fields
id"places" | "allowance" | "approvals"requireddonebooleanrequired
completebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
approvals"off" | "manager" | "hr" | "manager_then_hr"year_startobject2 fields
monthintegerrequiredFrom 1 to 12.
dayintegerrequiredFrom 1 to 28.
colleagues_see_awaybooleanretention_yearsintegerFrom 1 to 10.
chat_away_todaybooleancalendar_awaybooleansetup_done"places" | "allowance" | "approvals"[]Up to 3 items.
Returns
7 fields
approvals"off" | "manager" | "hr" | "manager_then_hr"requiredoff (booked at once within the rules), manager, hr, manager_then_hr. Types may set their own.
year_startobjectrequired2 fields
monthintegerrequireddayintegerrequired
colleagues_see_awaybooleanrequiredColleagues see who is away (dates only). Off: only managers and HR do.
retention_yearsintegerrequiredYears time-off records are kept after a person's last day.
chat_away_todaybooleanrequiredPost "who's away today" to the company's Slack or Teams channel (names only).
calendar_awaybooleanrequiredPut out-of-office "Away" events in people's Google or Outlook calendars (with a connected calendar).
setupobjectrequiredFirst-run setup: 1 locations and holidays, 2 allowance, 3 approvals (defaults pre-filled; each step is confirmed by HR).
2 fields
stepsobject[]required2 fields
id"places" | "allowance" | "approvals"requireddonebooleanrequired
completebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"
]
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedboolean
Returns
An array of objects with 17 fields
An array of objects:
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
uses_balancebooleanrequiredapproval"company" | "off" | "manager" | "hr" | "manager_then_hr"requiredwho_can_book"self" | "hr"requiredvisibility"away_only" | "type_visible"requiredaway_only: managers see "Away" only. Health types are always away_only; colleagues and machines always see "Away".
healthbooleanrequiredHealth-related (special-category data, GDPR art. 9): away_only, never shown to managers or colleagues.
familybooleanrequiredProtected 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_accidentbooleanrequiredLeave for a work accident: statutory safety reports count these absences as accidents and days lost (Portugal: Relatório Único Anexo D).
paidbooleanrequiredarchivedbooleanrequiredpositionintegerrequiredhoursbooleanrequiredPeople can book some hours of a day too (timeoff_book hours), not only whole and half days.
hours_min_minutesinteger | nullrequiredWith 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 https://api.bizisy.com/v1/timeoff/types.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/timeoff/types.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/types.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–60 characters.
uses_balancebooleanapproval"company" | "off" | "manager" | "hr" | "manager_then_hr"who_can_book"self" | "hr"visibility"away_only" | "type_visible"healthbooleanpaidbooleanfamilybooleanProtected 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_accidentbooleanLeave 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.positionintegerFrom 0 to 100.
hoursbooleanLet people book some hours of a day (spec hourly leave). Turning it off keeps hourly bookings already made.
hours_min_minutesintegerThe shortest hourly booking in minutes (15–480, 15-minute steps; default 60).
From 15 to 480.
Returns
17 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
uses_balancebooleanrequiredapproval"company" | "off" | "manager" | "hr" | "manager_then_hr"requiredwho_can_book"self" | "hr"requiredvisibility"away_only" | "type_visible"requiredaway_only: managers see "Away" only. Health types are always away_only; colleagues and machines always see "Away".
healthbooleanrequiredHealth-related (special-category data, GDPR art. 9): away_only, never shown to managers or colleagues.
familybooleanrequiredProtected 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_accidentbooleanrequiredLeave for a work accident: statutory safety reports count these absences as accidents and days lost (Portugal: Relatório Único Anexo D).
paidbooleanrequiredarchivedbooleanrequiredpositionintegerrequiredhoursbooleanrequiredPeople can book some hours of a day too (timeoff_book hours), not only whole and half days.
hours_min_minutesinteger | nullrequiredWith 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 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
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/types.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/types.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
type_idstringrequired1–120 characters.
namestring | null1–60 characters.
uses_balancebooleanapproval"company" | "off" | "manager" | "hr" | "manager_then_hr"who_can_book"self" | "hr"visibility"away_only" | "type_visible"healthbooleanpaidbooleanfamilybooleanProtected 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_accidentbooleanLeave 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.positionintegerFrom 0 to 100.
hoursbooleanLet people book some hours of a day (spec hourly leave). Turning it off keeps hourly bookings already made.
hours_min_minutesintegerThe shortest hourly booking in minutes (15–480, 15-minute steps; default 60).
From 15 to 480.
archivedboolean
Returns
17 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
uses_balancebooleanrequiredapproval"company" | "off" | "manager" | "hr" | "manager_then_hr"requiredwho_can_book"self" | "hr"requiredvisibility"away_only" | "type_visible"requiredaway_only: managers see "Away" only. Health types are always away_only; colleagues and machines always see "Away".
healthbooleanrequiredHealth-related (special-category data, GDPR art. 9): away_only, never shown to managers or colleagues.
familybooleanrequiredProtected 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_accidentbooleanrequiredLeave for a work accident: statutory safety reports count these absences as accidents and days lost (Portugal: Relatório Único Anexo D).
paidbooleanrequiredarchivedbooleanrequiredpositionintegerrequiredhoursbooleanrequiredPeople can book some hours of a day too (timeoff_book hours), not only whole and half days.
hours_min_minutesinteger | nullrequiredWith 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 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"
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/types.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"type_id": "vacation",
"name": null,
"approval": "off",
"color": "teal",
"icon": "plane"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/types.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"type_id": "vacation",
"name": None,
"approval": "off",
"color": "teal",
"icon": "plane",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects with 10 fields
An array of objects:
locationobject | nullrequirednull: the company default.
4 fields
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequired
custombooleanrequiredfalse: the country default (not saved yet).
annual_daysnumberrequiredaccrual"upfront" | "monthly"requiredcarry_overobjectrequired3 fields
mode"none" | "all" | "limited"requiredmax_daysnumberrequiredexpires_monthsinteger | nullrequired
negative_capnumberrequiredweekinteger[]requireddefaultobjectrequiredThe country rule this default comes from.
3 fields
daysnumberrequiredsourcestringrequiredbasisstringrequired
minimumobjectrequiredThe 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
daysnumberrequiredThe minimum for this working week (days a year, full-time).
per_5_daysnumberrequiredThe minimum on a 5-day week (prorate: per_5_days × working days a week ÷ 5, to half days).
countrystring | nullrequirednull: the EU rule (no country row).
sourcestringrequiredbasisstringrequiredurlstringrequiredrefusebooleanrequiredThe country's rule refuses an allowance under it (otherwise a warning).
below_minimumbooleanrequiredannual_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 https://api.bizisy.com/v1/timeoff/policies.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/policies.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/policies.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"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_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
location_idstring | nullrequired1–120 characters.
annual_daysnumberFrom 0 to 60.
accrual"upfront" | "monthly"carry_overobject3 fields
mode"none" | "all" | "limited"requiredmax_daysnumberrequiredFrom 0 to 60.
expires_monthsinteger | nullrequiredFrom 1 to 24.
negative_capnumberFrom 0 to 30.
weekinteger[]From 1 to 7. 1–7 items.
Returns
10 fields
locationobject | nullrequirednull: the company default.
4 fields
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequired
custombooleanrequiredfalse: the country default (not saved yet).
annual_daysnumberrequiredaccrual"upfront" | "monthly"requiredcarry_overobjectrequired3 fields
mode"none" | "all" | "limited"requiredmax_daysnumberrequiredexpires_monthsinteger | nullrequired
negative_capnumberrequiredweekinteger[]requireddefaultobjectrequiredThe country rule this default comes from.
3 fields
daysnumberrequiredsourcestringrequiredbasisstringrequired
minimumobjectrequiredThe 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
daysnumberrequiredThe minimum for this working week (days a year, full-time).
per_5_daysnumberrequiredThe minimum on a 5-day week (prorate: per_5_days × working days a week ÷ 5, to half days).
countrystring | nullrequirednull: the EU rule (no country row).
sourcestringrequiredbasisstringrequiredurlstringrequiredrefusebooleanrequiredThe country's rule refuses an allowance under it (otherwise a warning).
below_minimumbooleanrequiredannual_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 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
]
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/policies.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/policies.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects:
personobjectrequired2 fields
idstringrequirednamestringrequired
annual_daysnumber | nullrequiredweekinteger[] | nullrequiredbelow_minimumobject | nullrequiredTheir own allowance is under the legal minimum of their location's country (else the EU 4 weeks): a warning; null otherwise.
6 fields
annual_daysnumberrequiredminimumnumberrequiredcountrystring | nullrequiredsourcestringrequiredbasisstringrequiredrefusebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/patterns.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/patterns.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/patterns.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"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_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
person_idstringrequired1–120 characters.
weekinteger[] | nullFrom 1 to 7. 1–7 items.
annual_daysnumber | nullFrom 0 to 60.
Returns
personobjectrequired2 fields
idstringrequirednamestringrequired
annual_daysnumber | nullrequiredweekinteger[] | nullrequiredbelow_minimumobject | nullrequiredTheir own allowance is under the legal minimum of their location's country (else the EU 4 weeks): a warning; null otherwise.
6 fields
annual_daysnumberrequiredminimumnumberrequiredcountrystring | nullrequiredsourcestringrequiredbasisstringrequiredrefusebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/timeoff/patterns.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p8",
"week": null,
"annual_days": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/patterns.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p8",
"week": None,
"annual_days": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
yearintegerFrom 2000 to 2100.
lang"en" | "pt" | "es" | "de" | "fr" | "it"Language of holiday names (default en).
Returns
yearintegerrequiredlocationsobject[]required3 fields
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequired
knownbooleanrequiredfalse: no public holiday data for its country or region.
daysobject[]required3 fields
datestringrequirednamestringrequiredworkedbooleanrequiredThe location works this public holiday.
company_daysobject[]required5 fields
idstringrequireddatestringrequirednamestringrequiredlocation_idstring | nullrequiredkind"company" | "worked"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/holidays.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"year": 2026,
"lang": "pt"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/holidays.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"year": 2026,
"lang": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_regionson HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
countrystringPattern
^[A-Z]{2}$.
Returns
An array of objects:
codestringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/holidays.regions \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"ES"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/holidays.regions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"country": "ES"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/holidays.regions",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"country": "ES",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_dayon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
datestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.namestringrequired1–80 characters.
location_idstring | null1–120 characters.
kind"company" | "worked"
Returns
idstringrequireddatestringrequirednamestringrequiredlocation_idstring | nullrequiredkind"company" | "worked"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/holidays.set_day', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"date": "2026-06-13",
"name": "Santo António",
"location_id": "l1",
"kind": "company"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/holidays.set_day",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"date": "2026-06-13",
"name": "Santo António",
"location_id": "l1",
"kind": "company",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_dayon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idstringrequired1–120 characters.
Returns
idstringrequireddeletedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/holidays.delete_day', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "do1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/holidays.delete_day",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "do1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects:
countrystringrequireddaysnumberrequiredsourcestringrequiredbasisstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/defaults.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/defaults.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/defaults.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"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_templateson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects with 7 fields
An array of objects:
idstringrequirednamestringrequireddescriptionstringrequiredcategorystringrequiredapplies_to"booking" | "cancellation"requiredparamsobject[]required7 fields
namestringrequiredlabelstringrequireddescriptionstringrequiredtypestringrequireddefaultanyminnumbermaxnumber
variablesobject[]requiredNumbers the rule reads per team (e.g. minimum staff): set them in params.
4 fields
namestringrequiredlabelstringrequireddescriptionstringrequireddefaultnumberrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/rules.templates \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.templates', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.templates",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"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_referenceon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
7 fields
variablesobject[]required5 fields
pathstringrequiredtypestringrequiredunit"day" | "booking" | "year" | "cancellation"requireddescriptionstringrequiredapplies_to"booking" | "cancellation"[]required
elementsobject[]required2 fields
collectionstringrequiredfieldsobject[]required3 fields
namestringrequiredtypestringrequireddescriptionstringrequired
functionsobject[]required3 fields
namestringrequiredsignaturestringrequireddescriptionstringrequired
macrosobject[]required3 fields
namestringrequiredsignaturestringrequireddescriptionstringrequired
placeholdersobject[]required4 fields
pathstringrequireddescriptionstringrequiredapplies_to"booking" | "cancellation"[]requiredper_day_onlybooleanrequired
limitsobjectrequired5 fields
condition_charsnumberrequiredmessage_charsnumberrequiredmacro_callsnumberrequiredparamsnumberrequiredbudget_msnumberrequired
examplesobject[]required5 fields
titlestringrequiredapplies_to"booking" | "cancellation"requiredconditionstringrequiredmessagestringrequiredparamsobjectrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/rules.reference \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.reference', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.reference",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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_validateon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
conditionstringrequiredUp to 4000 characters.
applies_to"booking" | "cancellation"booking (default) or cancellation.
paramsobjectThe rule's named parameters (rule.params.<name>).
messagestring | nullUp to 1000 characters.
Returns
validbooleanrequiredissuesobject[]required4 fields
field"condition" | "message" | "params"requiredcodestringrequiredmessagestringrequiredrefstring | nullrequired
unit"day" | "booking" | "year" | "cancellation"requiredWhat it checks: each day, the whole booking, the leave year, or the booking being cancelled.
variablesstring[]requiredThe variables it reads.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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}."
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.validate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"condition": "cancellation.daysUntilStart < rule.params.days",
"applies_to": "cancellation",
"params": {
"days": 7
},
"message": "Too late to cancel ${cancellation.startDate}."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.validate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"condition": "cancellation.daysUntilStart < rule.params.days",
"applies_to": "cancellation",
"params": {
"days": 7,
},
"message": "Too late to cancel ${cancellation.startDate}.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects with 16 fields
An array of objects:
idstringrequiredtemplate_idstringrequiredA quick template's id, or "custom" for a condition the company wrote.
kind"template" | "custom"requirednamestringrequiredparamsobjectrequiredoutcome"block" | "warn" | "needs_approval"requiredapplies_to"booking" | "cancellation"requiredscopeobjectrequired3 fields
location_idsstring[]requiredunit_idsstring[]requiredperson_idsstring[]required
type_idsstring[]requiredactivebooleanrequiredmessagestring | nullrequiredThe company's own message (null: the template's).
conditionstring | nullrequiredCustom rules: the CEL condition (true: the rule applies). Templates: null.
unit"day" | "booking" | "year" | "cancellation"requiredWhat it checks: each day booked, the whole booking, the leave year, or the booking being cancelled.
summarystringrequiredIn plain words (English).
updated_atstringrequiredaffected_90dnumberrequiredSaved 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 https://api.bizisy.com/v1/timeoff/rules.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"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_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequired1–120 characters.
namestring1–100 characters.
paramsobjectoutcome"block" | "warn" | "needs_approval"scopeobject3 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.
activebooleanmessagestring | nullWhat 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.
conditionstringCustom 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
idstringrequiredtemplate_idstringrequiredA quick template's id, or "custom" for a condition the company wrote.
kind"template" | "custom"requirednamestringrequiredparamsobjectrequiredoutcome"block" | "warn" | "needs_approval"requiredapplies_to"booking" | "cancellation"requiredscopeobjectrequired3 fields
location_idsstring[]requiredunit_idsstring[]requiredperson_idsstring[]required
type_idsstring[]requiredactivebooleanrequiredmessagestring | nullrequiredThe company's own message (null: the template's).
conditionstring | nullrequiredCustom rules: the CEL condition (true: the rule applies). Templates: null.
unit"day" | "booking" | "year" | "cancellation"requiredWhat it checks: each day booked, the whole booking, the leave year, or the booking being cancelled.
summarystringrequiredIn plain words (English).
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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."
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rule_idstringrequired1–120 characters.
namestring1–100 characters.
paramsobjectoutcome"block" | "warn" | "needs_approval"scopeobject3 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.
activebooleanmessagestring | nullWhat 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.
conditionstringCustom 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
idstringrequiredtemplate_idstringrequiredA quick template's id, or "custom" for a condition the company wrote.
kind"template" | "custom"requirednamestringrequiredparamsobjectrequiredoutcome"block" | "warn" | "needs_approval"requiredapplies_to"booking" | "cancellation"requiredscopeobjectrequired3 fields
location_idsstring[]requiredunit_idsstring[]requiredperson_idsstring[]required
type_idsstring[]requiredactivebooleanrequiredmessagestring | nullrequiredThe company's own message (null: the template's).
conditionstring | nullrequiredCustom rules: the CEL condition (true: the rule applies). Templates: null.
unit"day" | "booking" | "year" | "cancellation"requiredWhat it checks: each day booked, the whole booking, the leave year, or the booking being cancelled.
summarystringrequiredIn plain words (English).
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rule_id": "r1",
"params": {
"noticeDays": 7
},
"outcome": "block",
"scope": {
"location_ids": [
"l1"
],
"unit_ids": [],
"person_ids": []
},
"message": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rule_id": "r1",
"params": {
"noticeDays": 7,
},
"outcome": "block",
"scope": {
"location_ids": [
"l1",
],
"unit_ids": [],
"person_ids": [],
},
"message": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_deleteon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rule_idstringrequired1–120 characters.
Returns
idstringrequireddeletedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rule_id": "r1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rule_id": "r1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_tryon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
ruleobjectrequired11 fields
template_idstring1–120 characters.
namestring1–100 characters.
paramsobjectoutcome"block" | "warn" | "needs_approval"scopeobject3 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.
activebooleanmessagestring | nullWhat 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.
conditionstringCustom 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_idstringA saved rule to start from.
1–120 characters.
person_idstringrequired1–120 characters.
type_idstringDefault: the first leave type the rule covers, else vacation.
1–120 characters.
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.endstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.start_part"full" | "am" | "pm"end_part"full" | "am" | "pm"
Returns
11 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
type_idstringrequiredin_scopebooleanrequiredout_of_scope"person" | "team" | "location" | "type"requiredWhy it wouldn't apply to them.
state"pass" | "fail" | "unknown"requiredoutcome"block" | "warn" | "needs_approval"requiredmessagestring | nullrequireddaysstring[]requiredunit"day" | "booking" | "year" | "cancellation"requiredreasonstring | nullrequiredworking_daysnumberrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/rules.try', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"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"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/rules.try",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"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",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
countriesstring[]Up to 30 items. Pattern
^[A-Z]{2}$.
Returns
countriesobject[]required5 fields
countrystringrequiredISO code; rules of countries without their own row are the EU Directive floor.
sourcestringrequiredlawobjectrequiredThe law's values (minutes; notice in days; null where the law sets none).
11 fields
restintegerrequiredday_maxinteger | nullrequiredweek_maxintegerrequiredaverage_weeksintegerrequirednotice_daysinteger | nullrequiredmicro_notice_daysinteger | nullrequiredweekly_restobjectrequired4 fields
minutesintegerrequiredwindow_daysintegerrequiredaverage_daysinteger | nullrequiredrest_daysinteger | nullrequired
breaksobjectrequired2 fields
afterany[][]requiredmax_stretchinteger | nullrequired
nightobjectrequired2 fields
startstringrequiredendstringrequired
shift_change_after_restbooleanrequiredlawobjectrequired7 fields
reststringrequiredweekly_reststringrequiredday_maxstring | nullrequiredweek_maxstringrequiredbreaksstringrequirednoticestringrequiredshift_changestring | nullrequired
companyobjectrequiredWhat applies: the law with the company's own values on top.
11 fields
restintegerrequiredday_maxinteger | nullrequiredweek_maxintegerrequiredaverage_weeksintegerrequirednotice_daysinteger | nullrequiredmicro_notice_daysinteger | nullrequiredweekly_restobjectrequired4 fields
minutesintegerrequiredwindow_daysintegerrequiredaverage_daysinteger | nullrequiredrest_daysinteger | nullrequired
breaksobjectrequired2 fields
afterany[][]requiredmax_stretchinteger | nullrequired
nightobjectrequired2 fields
startstringrequiredendstringrequired
shift_change_after_restbooleanrequiredlawobjectrequired7 fields
reststringrequiredweekly_reststringrequiredday_maxstring | nullrequiredweek_maxstringrequiredbreaksstringrequirednoticestringrequiredshift_changestring | nullrequired
overridesobjectrequired5 fields
restintegerday_maxinteger | nullweek_maxintegernotice_daysintegerlegal_basisstringWhy 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 https://api.bizisy.com/v1/timeoff/working_time.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countries":["FR"]}'const res = await fetch('https://api.bizisy.com/v1/timeoff/working_time.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"countries": [
"FR"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/working_time.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"countries": [
"FR",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
countrystringrequiredPattern
^[A-Z]{2}$.restinteger | nullFrom 0 to 1440.
day_maxinteger | nullFrom 60 to 1440.
week_maxinteger | nullFrom 60 to 10080.
notice_daysinteger | nullFrom 0 to 60.
legal_basisstring | nullThe 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[]required5 fields
countrystringrequiredISO code; rules of countries without their own row are the EU Directive floor.
sourcestringrequiredlawobjectrequiredThe law's values (minutes; notice in days; null where the law sets none).
11 fields
restintegerrequiredday_maxinteger | nullrequiredweek_maxintegerrequiredaverage_weeksintegerrequirednotice_daysinteger | nullrequiredmicro_notice_daysinteger | nullrequiredweekly_restobjectrequired4 fields
minutesintegerrequiredwindow_daysintegerrequiredaverage_daysinteger | nullrequiredrest_daysinteger | nullrequired
breaksobjectrequired2 fields
afterany[][]requiredmax_stretchinteger | nullrequired
nightobjectrequired2 fields
startstringrequiredendstringrequired
shift_change_after_restbooleanrequiredlawobjectrequired7 fields
reststringrequiredweekly_reststringrequiredday_maxstring | nullrequiredweek_maxstringrequiredbreaksstringrequirednoticestringrequiredshift_changestring | nullrequired
companyobjectrequiredWhat applies: the law with the company's own values on top.
11 fields
restintegerrequiredday_maxinteger | nullrequiredweek_maxintegerrequiredaverage_weeksintegerrequirednotice_daysinteger | nullrequiredmicro_notice_daysinteger | nullrequiredweekly_restobjectrequired4 fields
minutesintegerrequiredwindow_daysintegerrequiredaverage_daysinteger | nullrequiredrest_daysinteger | nullrequired
breaksobjectrequired2 fields
afterany[][]requiredmax_stretchinteger | nullrequired
nightobjectrequired2 fields
startstringrequiredendstringrequired
shift_change_after_restbooleanrequiredlawobjectrequired7 fields
reststringrequiredweekly_reststringrequiredday_maxstring | nullrequiredweek_maxstringrequiredbreaksstringrequirednoticestringrequiredshift_changestring | nullrequired
overridesobjectrequired5 fields
restintegerday_maxinteger | nullweek_maxintegernotice_daysintegerlegal_basisstringWhy 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 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
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/working_time.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"country": "PT",
"rest": 720,
"week_max": null,
"notice_days": 10,
"legal_basis": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/working_time.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"country": "PT",
"rest": 720,
"week_max": None,
"notice_days": 10,
"legal_basis": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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.