API reference
Time off
Booking (preview, book, cancel), who's away, requests and approvals, balances, adjustments and imports, calendar feeds and the absence report. Others are "Away" only over API keys.
21 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Preview time off#
POST/v1/timeoff/previewRead
Shows what booking some days would do, without booking: the working days it costs (weekends, public holidays and company days cost nothing), each day with its holiday, the balance before and after per leave year, the company rules that would warn or block, whether it needs approval and who decides, and any problem (already booked, not enough days, a rule). Same input as timeoff_book. Anyone for themselves; HR for anyone.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_previewon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringWhom it is for; omit for yourself. Booking for someone else is HR's, in the app or with an API key acting as HR is refused (machines book only for their own person).
1–120 characters.
type_idstringrequiredA leave type id (timeoff_types_list), e.g. vacation.
1–120 characters.
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.endstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.start_part"full" | "am" | "pm"One day: full (default), am (morning) or pm (afternoon). Several days: full, or pm to start in the afternoon.
end_part"full" | "am" | "pm"Several days: full (default), or am to end at noon.
hoursnumberSome hours of one day instead of a day-part (e.g. 2.5), in steps of 15 minutes, on a type that allows hours (hours and hours_min_minutes in timeoff_types_list): start and end are the same day; leave start_part and end_part out. It costs hours ÷ the person's scheduled hours that day.
From 0 to 24.
start_timestringWith hours: when they start (HH:MM), optional.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.notestring | nullSeen by the person and HR only (never managers, colleagues or machines). Never write health details here.
Up to 500 characters.
override_rulestrueHR only: record it although a rule blocks it (the rule is noted on the booking).
Returns
11 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
typeobjectrequired5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
daysnumberrequiredWorking days it costs.
partsobject[]required8 fields
datestringrequiredsegment"full" | "am" | "pm" | "hours"requiredminutesinteger | nullHours: the minutes booked.
start_timestring | nullday_minutesinteger | nullHours: the minutes scheduled that day (the cost is minutes ÷ day_minutes).
workingbooleanrequiredholidaystring | nullrequiredcompany_daystring | nullrequired
balancesobject[]requiredTypes that use the balance: available before and after, per leave year.
4 fields
year_startstringrequiredbeforenumberrequiredafternumberrequirednegative_capnumberrequired
rulesobject[]requiredThe company rules that warn, block or send it for approval.
6 fields
rule_idstringrequirednamestringrequiredoutcome"block" | "warn" | "needs_approval"requiredmessagestringrequireddaysstring[]requiredThe days that broke it (rules checked per day); empty when it is about the whole booking, the leave year or the cancellation.
unit"day" | "booking" | "year" | "cancellation"requiredWhat the rule checks: each day, the whole booking, the leave year, or the booking being cancelled.
checkedobject[]requiredEvery company rule that applies to this booking, with its verdict: pass, fail, or unknown (couldn't be decided: it never blocks).
4 fields
rule_idstringrequirednamestringrequiredoutcome"block" | "warn" | "needs_approval"requiredstate"pass" | "fail" | "unknown"required
approvalobjectrequired2 fields
neededbooleanrequiredstepsobject[]required2 fields
role"manager" | "hr"requiredapproverobject | nullrequired2 fields
idstringrequirednamestringrequired
problemsobject[]requiredWhy it can't be booked as it is; empty: it can.
3 fields
codestringrequiredmessagestringrequiredhintstringrequired
can_bookbooleanrequiredreturnsobject | nullrequiredSickness during annual leave (HR booking a health type such as sick leave over booked leave that uses the balance): the bookings it takes days from and the days that go back to the balance; null otherwise.
5 fields
daysnumberrequiredWorking days that go back to the balance.
lawstringrequiredThe country's rule (the EU rule, CJEU C-78/11, where Bizisy has no row of its own).
urlstringrequiredevidence"certificate" | "notice"requiredWhat the person owes under that rule: a medical certificate, or telling the employer.
requestsobject[]required4 fields
request_idstringrequiredtypeobjectrequired5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
datesstring[]requireddaysnumberrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "p3",
"type_id": "sick",
"start": "2026-10-12",
"end": "2026-10-12",
"start_part": "am",
"note": null
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p3",
"type_id": "sick",
"start": "2026-10-12",
"end": "2026-10-12",
"start_part": "am",
"note": null
}),
});
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/preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p3",
"type_id": "sick",
"start": "2026-10-12",
"end": "2026-10-12",
"start_part": "am",
"note": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"days": 4.5,
"parts": [
{
"date": "2026-11-02",
"segment": "full",
"working": true,
"holiday": null,
"company_day": null
},
{
"date": "2026-11-03",
"segment": "full",
"working": true,
"holiday": null,
"company_day": null
},
{
"date": "2026-12-08",
"segment": "full",
"working": false,
"holiday": "Immaculate Conception",
"company_day": null
},
{
"date": "2026-12-24",
"segment": "pm",
"working": true,
"holiday": null,
"company_day": null
}
],
"balances": [
{
"year_start": "2026-01-01",
"before": 9,
"after": 4.5,
"negative_cap": 0
}
],
"rules": [
{
"rule_id": "r1",
"name": "Minimum notice",
"outcome": "warn",
"message": "Book at least 14 days ahead.",
"days": [
"2026-11-02",
"2026-11-03"
],
"unit": "day"
}
],
"checked": [
{
"rule_id": "r1",
"name": "Minimum notice",
"outcome": "warn",
"state": "fail"
},
{
"rule_id": "r2",
"name": "No Fridays in summer",
"outcome": "block",
"state": "pass"
}
],
"approval": {
"needed": true,
"steps": [
{
"role": "manager",
"approver": {
"id": "p2",
"name": "Tomás Silva"
}
},
{
"role": "hr",
"approver": null
}
]
},
"problems": [],
"can_book": true,
"returns": null
}
}Book time off#
POST/v1/timeoff/bookWrite
Books days off: whole days, a morning (am) or afternoon (pm), or some hours of one day (hours, optional start_time) on types that allow hours. For yourself (any type you may book; days from today on) — booked at once, or sent for approval when the company or the type asks for it (or a rule does). HR books for anyone (past days too, and types only HR records such as sick leave); booking for someone else needs a person signed in (API keys and AI apps book only for their own person). Sickness during annual leave: HR recording a health type (sick leave) over booked leave that uses the balance takes those days from it and gives them back to the balance, per the country's rule (CJEU C-78/11; the preview's returns says which days and the law), and the person is told; cancelling that sick leave later does not book the leave again. Otherwise refused with the reason when the days are already booked, aren't working days, the balance is short, or a company rule blocks it — run timeoff_preview first to see all of that. The note is seen by the person and HR only.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Only for the key's or app's own person; booking for someone else needs a person signed in.
- MCP tool
timeoff_bookon My Workplace, 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_idstringWhom it is for; omit for yourself. Booking for someone else is HR's, in the app or with an API key acting as HR is refused (machines book only for their own person).
1–120 characters.
type_idstringrequiredA leave type id (timeoff_types_list), e.g. vacation.
1–120 characters.
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.endstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.start_part"full" | "am" | "pm"One day: full (default), am (morning) or pm (afternoon). Several days: full, or pm to start in the afternoon.
end_part"full" | "am" | "pm"Several days: full (default), or am to end at noon.
hoursnumberSome hours of one day instead of a day-part (e.g. 2.5), in steps of 15 minutes, on a type that allows hours (hours and hours_min_minutes in timeoff_types_list): start and end are the same day; leave start_part and end_part out. It costs hours ÷ the person's scheduled hours that day.
From 0 to 24.
start_timestringWith hours: when they start (HH:MM), optional.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.notestring | nullSeen by the person and HR only (never managers, colleagues or machines). Never write health details here.
Up to 500 characters.
override_rulestrueHR only: record it although a rule blocks it (the rule is noted on the booking).
Returns
21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/book \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p3",
"type_id": "vacation",
"start": "2026-11-02",
"end": "2026-11-04",
"start_part": "pm",
"end_part": "am",
"note": "Moving house",
"override_rules": true
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/book', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p3",
"type_id": "vacation",
"start": "2026-11-02",
"end": "2026-11-04",
"start_part": "pm",
"end_part": "am",
"note": "Moving house",
"override_rules": true
}),
});
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/book",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p3",
"type_id": "vacation",
"start": "2026-11-02",
"end": "2026-11-04",
"start_part": "pm",
"end_part": "am",
"note": "Moving house",
"override_rules": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tr1",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-04",
"start_part": "pm",
"end_part": "am",
"minutes": null,
"start_time": null,
"days": 5,
"status": "pending",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": "Moving house",
"steps": [
{
"role": "manager",
"state": "pending",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": null,
"at": null,
"comment": null
}
],
"booked_by": "self",
"warnings": [
"Book at least 14 days ahead."
],
"can_cancel": true,
"can_decide": true,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": null,
"cancelled_at": null,
"returned": null
}
}Book time off for several people#
POST/v1/timeoff/book_manyWrite
HR books the same days and type for up to 100 people at once (e.g. a training, or days off for a team). Each person runs the same checks as timeoff_book: people whose days are already booked, aren't working days, lack balance or are blocked by a rule are skipped with the reason (override_rules records blocked ones anyway). Run it as a dry run first to see each person's outcome. Owners, admins and HR, signed in.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_book_manyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idsstring[]required1–120 characters. 1–100 items.
type_idstringrequired1–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"notestring | nullSeen by the person and HR only (never managers, colleagues or machines). Never write health details here.
Up to 500 characters.
override_rulestrue
Returns
bookedintegerrequiredskippedintegerrequiredrowsobject[]required5 fields
person_idstringrequiredokbooleanrequiredrequest_idstring | nullrequireddaysnumberrequiredproblemstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/book_many \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_ids": [
"p4"
],
"type_id": "vacation",
"start": "2026-12-24",
"end": "2026-12-24",
"start_part": "pm",
"note": null,
"override_rules": true
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/book_many', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_ids": [
"p4"
],
"type_id": "vacation",
"start": "2026-12-24",
"end": "2026-12-24",
"start_part": "pm",
"note": null,
"override_rules": true
}),
});
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/book_many",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_ids": [
"p4",
],
"type_id": "vacation",
"start": "2026-12-24",
"end": "2026-12-24",
"start_part": "pm",
"note": None,
"override_rules": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"booked": 1,
"skipped": 1,
"rows": [
{
"person_id": "p2",
"ok": true,
"request_id": "tr9",
"days": 1,
"problem": null
},
{
"person_id": "p3",
"ok": false,
"request_id": null,
"days": 1,
"problem": "Already booked on these days."
}
]
}
}Cancel time off#
POST/v1/timeoff/cancelWrite
Cancels a booking or a pending request. Your own: any that hasn't started yet. One that has started or passed, or someone else's: HR, or a manager in their chain on a request they approve. Company rules on cancelling (e.g. no late cancellation) apply to your own. The days return to the balance. reason (optional) is told to the person.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_cancelon My Workplace, 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
request_idstringrequired1–120 characters.
reasonstring | nullUp to 300 characters.
Returns
21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"request_id":"tr1","reason":"Plans changed."}'const res = await fetch('https://api.bizisy.com/v1/timeoff/cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "tr1",
"reason": "Plans changed."
}),
});
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/cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "tr1",
"reason": "Plans changed.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tr1",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-06",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 5,
"status": "cancelled",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": null,
"steps": [
{
"role": "manager",
"state": "approved",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": {
"id": "p2",
"name": "Tomás Silva"
},
"at": "2026-10-10T08:00:00.000Z",
"comment": null
}
],
"booked_by": "self",
"warnings": [],
"can_cancel": false,
"can_decide": false,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": "2026-10-10T08:00:00.000Z",
"cancelled_at": "2026-10-11T10:00:00.000Z",
"returned": null
}
}List time off requests#
POST/v1/timeoff/requests.listRead
Time off bookings and requests the caller may see: their own; their reports' (managers, with the type only when the type is shown to managers — never sick or other health leave); everyone's (owners, admins, HR). Notes only for the person and HR. Colleagues and machines see none here (use timeoff_away_list for who is away). Filters: status (pending, approved, declined, cancelled), person_id, waiting_for_me (pending requests the caller can decide), from/to (days overlapping), unit_id. Newest first; at most 500.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_requests_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"pending" | "approved" | "declined" | "cancelled"person_idstring1–120 characters.
waiting_for_mebooleanfromstringPattern
^\d{4}-\d{2}-\d{2}$.tostringPattern
^\d{4}-\d{2}-\d{2}$.unit_idstring1–120 characters.
limitintegerFrom 1 to 500.
Returns
itemsobject[]required21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
waiting_for_meintegerrequiredtotalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/requests.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "p3",
"from": "2026-01-01",
"to": "2026-12-31",
"unit_id": "u2",
"limit": 50
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/requests.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p3",
"from": "2026-01-01",
"to": "2026-12-31",
"unit_id": "u2",
"limit": 50
}),
});
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/requests.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p3",
"from": "2026-01-01",
"to": "2026-12-31",
"unit_id": "u2",
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "tr1",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-06",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 5,
"status": "pending",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": "Family trip to the Azores.",
"steps": [
{
"role": "manager",
"state": "pending",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": null,
"at": null,
"comment": null
}
],
"booked_by": "self",
"warnings": [
"Book at least 14 days ahead."
],
"can_cancel": true,
"can_decide": true,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": null,
"cancelled_at": null,
"returned": null
},
{
"id": "tr2",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-06",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 5,
"status": "approved",
"type": null,
"note": null,
"steps": [
{
"role": "manager",
"state": "approved",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": {
"id": "p2",
"name": "Tomás Silva"
},
"at": "2026-10-10T08:00:00.000Z",
"comment": null
}
],
"booked_by": "self",
"warnings": [],
"can_cancel": true,
"can_decide": false,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": "2026-10-10T08:00:00.000Z",
"cancelled_at": null,
"returned": null
}
],
"waiting_for_me": 1,
"total": 2
}
}Get a time off request#
POST/v1/timeoff/requests.getRead
One booking or request, as the caller may see it (see timeoff_requests_list). Not found for anyone who can't see it.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_requests_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
request_idstringrequired1–120 characters.
Returns
21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/requests.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"request_id":"tr1"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/requests.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"request_id": "tr1"
}),
});
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/requests.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"request_id": "tr1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tr1",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-06",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 5,
"status": "pending",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": "Family trip to the Azores.",
"steps": [
{
"role": "manager",
"state": "pending",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": null,
"at": null,
"comment": null
}
],
"booked_by": "self",
"warnings": [
"Book at least 14 days ahead."
],
"can_cancel": true,
"can_decide": true,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": null,
"cancelled_at": null,
"returned": null
}
}Approve or decline time off#
POST/v1/timeoff/requests.decideWrite
Approves or declines the pending step of a time off request. Who decides: the manager asked (or anyone above them in the chain) for a manager step; owners, admins and HR for any step. Never your own request. A decline needs no reason but a comment is told to the person. Approving the last step books the days; declining releases them. In the app only (approvals need a person signed in).
- Web app only
- Refused for API keys and connected apps. Approving or declining time off needs a person signed in to Bizisy.
- MCP tool
timeoff_requests_decideon HR Assistant, My Workplace- 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
request_idstringrequired1–120 characters.
decision"approve" | "decline"requiredcommentstring | nullUp to 500 characters.
whystring | nullOptional: why, in one line about the case (never the person), kept as a decision record when your company records decisions (Ask HR). Refused if it mentions health, names or ratings.
Up to 300 characters.
why_source"person" | "ai"ai: the "Why?" is as Ask HR prefilled it.
Returns
21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/requests.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"request_id": "tr1",
"decision": "decline",
"comment": "Release week.",
"why": "Release week: the team needs everyone",
"why_source": "ai"
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/requests.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "tr1",
"decision": "decline",
"comment": "Release week.",
"why": "Release week: the team needs everyone",
"why_source": "ai"
}),
});
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/requests.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "tr1",
"decision": "decline",
"comment": "Release week.",
"why": "Release week: the team needs everyone",
"why_source": "ai",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tr1",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-06",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 5,
"status": "approved",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": null,
"steps": [
{
"role": "manager",
"state": "approved",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": {
"id": "p2",
"name": "Tomás Silva"
},
"at": "2026-10-10T08:00:00.000Z",
"comment": null
}
],
"booked_by": "self",
"warnings": [],
"can_cancel": true,
"can_decide": false,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": "2026-10-10T08:00:00.000Z",
"cancelled_at": null,
"returned": null
}
}My time off#
POST/v1/timeoff/my.overviewRead
Your time off: balance for this leave year (and the next once it is near or booked into) — entitlement, carried, adjustments, taken, booked, available; your upcoming and pending bookings; the leave types you can book yourself (and whether they need approval). Your own data only.
- Who can call it
- Me key anyone
- MCP tool
timeoff_my_overviewon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
7 fields
todaystringrequiredbalancesobject[]required11 fields
yearobjectrequiredThe leave year.
2 fields
startstringrequiredendstringrequired
entitlementnumberrequiredDays for the whole leave year (prorated by working time and time employed).
allowancenumberrequiredAccrued so far (monthly accrual), else the entitlement.
carriednumberrequiredDays carried over from the year before.
carried_expires_onstring | nullrequiredUnused carried days lapse after this day.
adjustmentsnumberrequiredHR adjustments (corrections, imports, restored days).
takennumberrequiredbookednumberrequiredBooked or requested days still ahead (and requests waiting for a decision).
availablenumberrequiredlapsingnumberrequiredCarried days that lapse unless taken before carried_expires_on.
day_minutesintegerrequiredTheir typical working day in minutes: a day of balance is worth this much in hours (hourly bookings cost minutes ÷ that day's scheduled minutes).
upcomingobject[]requiredPending and booked days from today on, soonest first.
21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
pastobject[]requiredThe last 20 past, declined or cancelled ones, newest first.
21 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredfull, or pm: the first day starts in the afternoon (one-day bookings: full, am or pm). hours: some hours of one day (see minutes).
end_part"full" | "am" | "pm" | "hours"requiredfull, or am: the last day ends at noon; hours with start_part hours.
minutesinteger | nullrequiredSome hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").
start_timestring | nullrequiredHours: when they start (HH:MM), if given; the person, their managers and HR only.
daysnumberrequiredWorking days it costs (hours: minutes ÷ the day's scheduled minutes).
status"pending" | "approved" | "declined" | "cancelled"requiredtypeobject | nullrequirednull: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
notestring | nullrequiredThe person and HR only.
stepsobject[]requiredApproval steps ([] when booked at once). Only the person, their managers and HR see them.
7 fields
role"manager" | "hr"requiredstate"waiting" | "pending" | "approved" | "declined"requiredapproverobject | nullrequiredmanager steps: who is asked; null for HR (anyone in HR decides).
2 fields
idstringrequirednamestringrequired
decided_byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredcommentstring | nullrequiredby_rulestring | nullApproved at once by the company's rule (Ask HR decision records): the rule, in its words.
booked_by"self" | "hr" | "import" | "company_day"requiredself, hr, import or company_day; null when the viewer does not see the type.
warningsstring[]requiredRule warnings when it was booked (the person, managers and HR).
can_cancelbooleanrequiredcan_decidebooleanrequiredcreated_atstringrequireddecided_atstring | nullrequiredcancelled_atstring | nullrequiredreturnedobject | nullrequiredSickness during annual leave: on leave that uses the balance, the days sick leave took back to the balance; on the sick leave, the days it gave back. The person and HR only (health data); null otherwise.
4 fields
daysnumberrequireddatesstring[]requiredlawstringrequiredside"leave" | "sickness"requiredleave: this booking lost the days; sickness: this sick leave gave them back.
pendingintegerrequiredtypesobject[]required9 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
uses_balancebooleanrequiredbookablebooleanrequiredfalse: HR records it (e.g. sick leave).
needs_approvalbooleanrequiredhours_min_minutesinteger | nullrequiredSome hours of a day can be booked, at least this many minutes; null: whole and half days only.
colleagues_see_awaybooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/my.overview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/my.overview', {
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/my.overview",
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": {
"today": "2026-10-11",
"balances": [
{
"year": {
"start": "2026-01-01",
"end": "2026-12-31"
},
"entitlement": 22,
"allowance": 22,
"carried": 3,
"carried_expires_on": "2026-03-31",
"adjustments": 1,
"taken": 12,
"booked": 5,
"available": 9,
"lapsing": 0,
"day_minutes": 480
}
],
"upcoming": [
{
"id": "tr1",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-11-02",
"end": "2026-11-06",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 5,
"status": "pending",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": "Family trip to the Azores.",
"steps": [
{
"role": "manager",
"state": "pending",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": null,
"at": null,
"comment": null
}
],
"booked_by": "self",
"warnings": [
"Book at least 14 days ahead."
],
"can_cancel": true,
"can_decide": true,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": null,
"cancelled_at": null,
"returned": null
}
],
"past": [
{
"id": "tr3",
"person": {
"id": "p3",
"name": "Sofia Costa"
},
"start": "2026-08-03",
"end": "2026-08-14",
"start_part": "full",
"end_part": "full",
"minutes": null,
"start_time": null,
"days": 10,
"status": "approved",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"note": null,
"steps": [
{
"role": "manager",
"state": "approved",
"approver": {
"id": "p2",
"name": "Tomás Silva"
},
"decided_by": {
"id": "p2",
"name": "Tomás Silva"
},
"at": "2026-10-10T08:00:00.000Z",
"comment": null
}
],
"booked_by": "self",
"warnings": [],
"can_cancel": false,
"can_decide": false,
"created_at": "2026-10-09T09:12:00.000Z",
"decided_at": "2026-10-10T08:00:00.000Z",
"cancelled_at": null,
"returned": null
}
],
"pending": 1,
"types": [
{
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true,
"uses_balance": true,
"bookable": true,
"needs_approval": true,
"hours_min_minutes": 60
},
{
"id": "sick",
"name": "Sick leave",
"color": "rose",
"icon": "thermometer",
"builtin": true,
"uses_balance": false,
"bookable": false,
"needs_approval": true,
"hours_min_minutes": null
}
],
"colleagues_see_away": true
}
}My calendar#
POST/v1/timeoff/my.calendarRead
Your days between from and to (at most 400): working day or not, public holiday or company day (named in your language), and what you booked on each (day-part, status, type). For picking days to book.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_my_calendaron My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.person_idstringHR: someone else's calendar, to book for them.
1–120 characters.
lang"en" | "pt" | "es" | "de" | "fr" | "it"Language of holiday names (default en).
Returns
daysobject[]required7 fields
datestringrequiredworkingbooleanrequiredholidaystring | nullrequiredcompany_daystring | nullrequiredminutesintegerrequiredMinutes scheduled that day (0 when not a working day): what some hours are measured against.
startstring | nullrequiredA fixed schedule's start that day (HH:MM).
endstring | nullrequired
bookedobject[]required7 fields
datestringrequiredsegment"full" | "am" | "pm" | "hours"requiredstatus"pending" | "approved"requiredrequest_idstringrequiredtypeobject | nullrequired5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
minutesinteger | nullrequiredhours: the minutes booked.
start_timestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/my.calendar \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"2026-10-01","to":"2026-10-31","person_id":"p3"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/my.calendar', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"from": "2026-10-01",
"to": "2026-10-31",
"person_id": "p3"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/my.calendar",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"from": "2026-10-01",
"to": "2026-10-31",
"person_id": "p3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"days": [
{
"date": "2026-10-05",
"working": false,
"holiday": "Implantação da República",
"company_day": null,
"minutes": 0,
"start": null,
"end": null
},
{
"date": "2026-10-06",
"working": true,
"holiday": null,
"company_day": null,
"minutes": 480,
"start": "09:00",
"end": "18:00"
}
],
"booked": [
{
"date": "2026-10-06",
"segment": "am",
"status": "approved",
"request_id": "tr4",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"minutes": null,
"start_time": null
},
{
"date": "2026-10-07",
"segment": "hours",
"status": "approved",
"request_id": "tr5",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
},
"minutes": 120,
"start_time": "14:00"
}
]
}
}Who's away#
POST/v1/timeoff/away.listRead
Who is away between from and to (at most 400 days), with the people in scope, public holidays and company days per location, and coverage per day (how many of the people in scope are away). Everyone sees colleagues' booked days as "Away" (dates and half days only — never the type, note or status) unless the company hides them; their own days and their reports' (pending ones too, with the type when it is shown to managers — never sick or other health leave) in full; owners, admins and HR everything. API keys and AI apps see "Away" only for others. Filters: unit_id (a team), location_id, person_id, mine (true: your team, or your reports when you manage people).
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Other people's days come as "Away" only (dates and half days; never the type, note or status).
- MCP tool
timeoff_away_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.unit_idstring1–120 characters.
location_idstring1–120 characters.
person_idstring1–120 characters.
minebooleanlang"en" | "pt" | "es" | "de" | "fr" | "it"Language of holiday names (default en).
Returns
8 fields
fromstringrequiredtostringrequiredtodaystringrequiredpeopleobject[]required4 fields
idstringrequirednamestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
location_idstring | nullrequired
itemsobject[]required10 fields
personobjectrequired3 fields
idstringrequirednamestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
request_idstring | nullrequiredOnly for the person, their managers and HR.
startstringrequiredendstringrequiredstart_part"full" | "am" | "pm" | "hours"requiredhours: away part of the day.
end_part"full" | "am" | "pm" | "hours"requiredminutesinteger | nullHours: the minutes (the person, their managers and HR only).
start_timestring | nullHours: when they start (the person, their managers and HR only).
status"pending" | "approved"requiredColleagues and machines only ever see approved days.
typeobject | nullrequirednull: "Away".
5 fields
idstringrequirednamestringrequiredcolorstringrequirediconstringrequiredbuiltinbooleanrequiredA built-in type (its name is translated in the app).
holidaysobject[]required4 fields
datestringrequirednamestringrequiredlocation_idstring | nullrequiredkind"public" | "company"required
coverageobject[]required3 fields
datestringrequiredawayintegerrequiredtotalintegerrequired
hiddenbooleanrequiredtrue: the company hides colleagues' days from you (managers and HR still see their people).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/away.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "2026-10-01",
"to": "2026-10-31",
"unit_id": "u1",
"location_id": "l1",
"person_id": "p2",
"mine": true
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/away.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"from": "2026-10-01",
"to": "2026-10-31",
"unit_id": "u1",
"location_id": "l1",
"person_id": "p2",
"mine": 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/away.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"from": "2026-10-01",
"to": "2026-10-31",
"unit_id": "u1",
"location_id": "l1",
"person_id": "p2",
"mine": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"from": "2026-10-01",
"to": "2026-10-31",
"today": "2026-10-11",
"people": [
{
"id": "p2",
"name": "Tomás Silva",
"unit": {
"id": "u1",
"name": "Engineering"
},
"location_id": "l2"
},
{
"id": "p3",
"name": "Sofia Costa",
"unit": {
"id": "u2",
"name": "Product"
},
"location_id": "l4"
}
],
"items": [
{
"person": {
"id": "p2",
"name": "Tomás Silva",
"unit": {
"id": "u1",
"name": "Engineering"
}
},
"request_id": null,
"start": "2026-10-12",
"end": "2026-10-16",
"start_part": "full",
"end_part": "full",
"status": "approved",
"type": null
},
{
"person": {
"id": "p3",
"name": "Sofia Costa",
"unit": {
"id": "u2",
"name": "Product"
}
},
"request_id": "tr1",
"start": "2026-10-14",
"end": "2026-10-14",
"start_part": "pm",
"end_part": "pm",
"status": "pending",
"type": {
"id": "vacation",
"name": "Vacation",
"color": "teal",
"icon": "sun",
"builtin": true
}
}
],
"holidays": [
{
"date": "2026-10-12",
"name": "Fiesta Nacional de España",
"location_id": "l6",
"kind": "public"
}
],
"coverage": [
{
"date": "2026-10-12",
"away": 1,
"total": 2
}
],
"hidden": false
}
}List time off balances#
POST/v1/timeoff/balances.listRead
Everyone's balance for a leave year (year: its first calendar year, default the current one): entitlement (prorated by working time and time employed), carried, adjustments, taken, booked, available, and carried days about to lapse. Filters: unit_id, location_id, q (name). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_balances_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
yearintegerFrom 2000 to 2100.
unit_idstring1–120 characters.
location_idstring1–120 characters.
qstringUp to 100 characters.
Returns
yearobjectrequired2 fields
startstringrequiredendstringrequired
rowsobject[]required2 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
location_idstring | nullrequired
balanceobjectrequired11 fields
yearobjectrequiredThe leave year.
2 fields
startstringrequiredendstringrequired
entitlementnumberrequiredDays for the whole leave year (prorated by working time and time employed).
allowancenumberrequiredAccrued so far (monthly accrual), else the entitlement.
carriednumberrequiredDays carried over from the year before.
carried_expires_onstring | nullrequiredUnused carried days lapse after this day.
adjustmentsnumberrequiredHR adjustments (corrections, imports, restored days).
takennumberrequiredbookednumberrequiredBooked or requested days still ahead (and requests waiting for a decision).
availablenumberrequiredlapsingnumberrequiredCarried days that lapse unless taken before carried_expires_on.
day_minutesintegerrequiredTheir typical working day in minutes: a day of balance is worth this much in hours (hourly bookings cost minutes ÷ that day's scheduled minutes).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/balances.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"year":2026,"unit_id":"u1","location_id":"l1","q":"sofia"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/balances.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"year": 2026,
"unit_id": "u1",
"location_id": "l1",
"q": "sofia"
}),
});
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/balances.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"year": 2026,
"unit_id": "u1",
"location_id": "l1",
"q": "sofia",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"year": {
"start": "2026-01-01",
"end": "2026-12-31"
},
"rows": [
{
"person": {
"id": "p3",
"name": "Sofia Costa",
"unit": {
"id": "u2",
"name": "Product"
},
"location_id": "l4"
},
"balance": {
"year": {
"start": "2026-01-01",
"end": "2026-12-31"
},
"entitlement": 22,
"allowance": 22,
"carried": 3,
"carried_expires_on": "2026-03-31",
"adjustments": 1,
"taken": 12,
"booked": 5,
"available": 9,
"lapsing": 0,
"day_minutes": 480
}
}
]
}
}Get a time off balance#
POST/v1/timeoff/balances.getRead
A person's balances (this leave year, and the next once near or booked into) with the adjustments behind them (reason, kind, expiry). Yourself, or anyone for owners, admins and HR.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_balances_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstring1–120 characters.
Returns
personobjectrequired2 fields
idstringrequirednamestringrequired
balancesobject[]required11 fields
yearobjectrequiredThe leave year.
2 fields
startstringrequiredendstringrequired
entitlementnumberrequiredDays for the whole leave year (prorated by working time and time employed).
allowancenumberrequiredAccrued so far (monthly accrual), else the entitlement.
carriednumberrequiredDays carried over from the year before.
carried_expires_onstring | nullrequiredUnused carried days lapse after this day.
adjustmentsnumberrequiredHR adjustments (corrections, imports, restored days).
takennumberrequiredbookednumberrequiredBooked or requested days still ahead (and requests waiting for a decision).
availablenumberrequiredlapsingnumberrequiredCarried days that lapse unless taken before carried_expires_on.
day_minutesintegerrequiredTheir typical working day in minutes: a day of balance is worth this much in hours (hourly bookings cost minutes ÷ that day's scheduled minutes).
adjustmentsobject[]required7 fields
idstringrequiredyearintegerrequiredamountnumberrequiredreasonstringrequiredkindstringrequiredexpires_onstring | nullrequiredcreated_atstringrequired
below_minimumobject | nullrequiredOwners, admins and HR: their allowance (their own or their policy's) is under the legal minimum of their country (else the EU 4 weeks); null otherwise, and for anyone else.
6 fields
annual_daysnumberrequiredminimumnumberrequiredcountrystring | nullrequiredsourcestringrequiredbasisstringrequiredrefusebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/balances.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p3"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/balances.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p3"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/timeoff/balances.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p3",
},
)
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 Costa"
},
"balances": [
{
"year": {
"start": "2026-01-01",
"end": "2026-12-31"
},
"entitlement": 22,
"allowance": 22,
"carried": 3,
"carried_expires_on": "2026-03-31",
"adjustments": 1,
"taken": 12,
"booked": 5,
"available": 9,
"lapsing": 0,
"day_minutes": 480
}
],
"adjustments": [
{
"id": "adj1",
"year": 2026,
"amount": 1,
"reason": "Worked on a public holiday",
"kind": "manual",
"expires_on": null,
"created_at": "2026-05-02T10:00:00.000Z"
}
],
"below_minimum": null
}
}Adjust a time off balance#
POST/v1/timeoff/balances.adjustWrite
Adds or removes days on a person's balance for a leave year (year: its first calendar year, default the current one), with a reason they see. expires_on (optional): the days lapse after that day if not taken. kind restore: gives back carried days that lapsed (e.g. the person could not take them because of sickness — CJEU C-350/06, or was not enabled to — C-684/16). Whole or half days, at most 366 either way. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_balances_adjuston HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequired1–120 characters.
amountnumberrequiredFrom -366 to 366.
reasonstringrequired1–300 characters.
yearintegerFrom 2000 to 2100.
expires_onstring | nullPattern
^\d{4}-\d{2}-\d{2}$.kind"manual" | "restore"
Returns
idstringrequiredperson_idstringrequiredbalanceobjectrequired11 fields
yearobjectrequiredThe leave year.
2 fields
startstringrequiredendstringrequired
entitlementnumberrequiredDays for the whole leave year (prorated by working time and time employed).
allowancenumberrequiredAccrued so far (monthly accrual), else the entitlement.
carriednumberrequiredDays carried over from the year before.
carried_expires_onstring | nullrequiredUnused carried days lapse after this day.
adjustmentsnumberrequiredHR adjustments (corrections, imports, restored days).
takennumberrequiredbookednumberrequiredBooked or requested days still ahead (and requests waiting for a decision).
availablenumberrequiredlapsingnumberrequiredCarried days that lapse unless taken before carried_expires_on.
day_minutesintegerrequiredTheir typical working day in minutes: a day of balance is worth this much in hours (hourly bookings cost minutes ÷ that day's scheduled minutes).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/balances.adjust \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p3",
"amount": 2,
"reason": "Lapsed while on sick leave",
"year": 2026,
"expires_on": "2026-12-31",
"kind": "restore"
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/balances.adjust', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p3",
"amount": 2,
"reason": "Lapsed while on sick leave",
"year": 2026,
"expires_on": "2026-12-31",
"kind": "restore"
}),
});
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/balances.adjust",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p3",
"amount": 2,
"reason": "Lapsed while on sick leave",
"year": 2026,
"expires_on": "2026-12-31",
"kind": "restore",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "adj2",
"person_id": "p3",
"balance": {
"year": {
"start": "2026-01-01",
"end": "2026-12-31"
},
"entitlement": 22,
"allowance": 22,
"carried": 3,
"carried_expires_on": "2026-03-31",
"adjustments": 2.5,
"taken": 12,
"booked": 5,
"available": 10.5,
"lapsing": 0,
"day_minutes": 480
}
}
}Export time off balances#
POST/v1/timeoff/balances.exportRead
Everyone's balances for a leave year as CSV text (name, work email, team, entitlement, carried, adjustments, taken, booked, available). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_balances_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
yearintegerFrom 2000 to 2100.
Returns
filenamestringrequiredcsvstringrequiredrowsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/balances.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"year":2026}'const res = await fetch('https://api.bizisy.com/v1/timeoff/balances.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"year": 2026
}),
});
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/balances.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"year": 2026,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"filename": "time-off-balances-2026-01-01.csv",
"csv": "name,work_email,team,year_start,entitlement,carried,adjustments,taken,booked,available\nSofia Costa,sofia@acme.test,Product,2026-01-01,22,3,1,12,5,9\n",
"rows": 1
}
}Import opening balances#
POST/v1/timeoff/balances.importWrite
Sets opening balances from a spreadsheet (up to 200 rows): work_email, days (whole or half, may be negative), reason (default "Opening balance"), year (the leave year's first calendar year, default the current one), expires_on (optional). Each row adds an adjustment. All or nothing: run it as a dry run first to see each row's outcome. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_balances_importon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rowsobject[]required1–200 items.
5 fields
work_emailstringrequiredUp to 320 characters.
daysnumber | stringrequiredreasonstring | nullUp to 300 characters.
yearnumber | stringexpires_onstring | nullUp to 20 characters.
Returns
createdintegerrequiredrowsobject[]required3 fields
rowintegerrequiredokbooleanrequiredproblemstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/balances.import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rows": [
{
"work_email": "sofia@acme.test",
"days": 3
},
{
"work_email": "tomas@acme.test",
"days": "1,5",
"reason": "Carried from 2025",
"year": "2026",
"expires_on": "2026-03-31"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/balances.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rows": [
{
"work_email": "sofia@acme.test",
"days": 3
},
{
"work_email": "tomas@acme.test",
"days": "1,5",
"reason": "Carried from 2025",
"year": "2026",
"expires_on": "2026-03-31"
}
]
}),
});
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/balances.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rows": [
{
"work_email": "sofia@acme.test",
"days": 3,
},
{
"work_email": "tomas@acme.test",
"days": "1,5",
"reason": "Carried from 2025",
"year": "2026",
"expires_on": "2026-03-31",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"created": 2,
"rows": [
{
"row": 1,
"ok": true,
"problem": null
},
{
"row": 2,
"ok": true,
"problem": null
}
]
}
}Import past and planned time off#
POST/v1/timeoff/importWrite
Records time off from a spreadsheet (up to 200 rows; e.g. moving from another tool): work_email, type (id or name), start, end (default start), start_part/end_part (full, am, pm), or hours (some hours of one day, e.g. 2.5, on a type that allows hours) with an optional start_time (HH:MM), note. Each row runs the same checks as HR booking for someone (employment, days already booked, balance, company rules — override_rules records rule-blocked rows anyway). Recorded as booked by HR, never sent for approval. All or nothing: run it as a dry run first. Owners, admins and HR, signed in.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_importon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rowsobject[]required1–200 items.
9 fields
work_emailstringrequiredUp to 320 characters.
typestringrequiredA type id or its name (case-insensitive), e.g. vacation.
Up to 60 characters.
startstringrequiredUp to 20 characters.
endstring | nullUp to 20 characters.
start_partstring | nullUp to 10 characters.
end_partstring | nullUp to 10 characters.
notestring | nullUp to 500 characters.
hoursnumber | stringSome hours of one day instead of day-parts (e.g. 2.5).
start_timestring | nullUp to 10 characters.
override_rulestrue
Returns
createdintegerrequiredrowsobject[]required4 fields
rowintegerrequiredokbooleanrequiredproblemstring | nullrequireddaysnumberrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rows": [
{
"work_email": "sofia@acme.test",
"type": "vacation",
"start": "2026-08-03"
},
{
"work_email": "tomas@acme.test",
"type": "Vacation",
"start": "2026-08-10",
"end": "2026-08-14",
"start_part": null,
"end_part": "am",
"note": "From the old tool"
}
],
"override_rules": true
}'const res = await fetch('https://api.bizisy.com/v1/timeoff/import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rows": [
{
"work_email": "sofia@acme.test",
"type": "vacation",
"start": "2026-08-03"
},
{
"work_email": "tomas@acme.test",
"type": "Vacation",
"start": "2026-08-10",
"end": "2026-08-14",
"start_part": null,
"end_part": "am",
"note": "From the old tool"
}
],
"override_rules": true
}),
});
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/import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rows": [
{
"work_email": "sofia@acme.test",
"type": "vacation",
"start": "2026-08-03",
},
{
"work_email": "tomas@acme.test",
"type": "Vacation",
"start": "2026-08-10",
"end": "2026-08-14",
"start_part": None,
"end_part": "am",
"note": "From the old tool",
},
],
"override_rules": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"created": 0,
"rows": [
{
"row": 1,
"ok": true,
"problem": null,
"days": 1
},
{
"row": 2,
"ok": false,
"problem": "No one in Bizisy has this work email.",
"days": 0
}
]
}
}My calendar feeds#
POST/v1/timeoff/feeds.listRead
Your time off calendar feeds (ICS links you added to Google, Outlook or Apple Calendar): whose days, last 4 characters, when created and last read. The links themselves are shown only once, when created.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_feeds_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects:
idstringrequiredkind"person" | "unit"requiredsubjectobjectrequired2 fields
idstringrequirednamestringrequired
last4stringrequiredcreated_atstringrequiredlast_used_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/feeds.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/timeoff/feeds.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/feeds.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": "f1",
"kind": "person",
"subject": {
"id": "p1",
"name": "Ana Ferreira"
},
"last4": "x9Qa",
"created_at": "2026-09-01T10:00:00.000Z",
"last_used_at": "2026-10-11T06:00:00.000Z"
}
]
}Create a calendar feed#
POST/v1/timeoff/feeds.createWrite
Creates a private calendar link (ICS) to subscribe to in a calendar app: your own days off (kind person), or a team's (kind unit, unit_id: who is away, as you may see it). Every event is titled "Away" (never the type or a note). Shown once — keep it private; revoke it any time. At most 5. In the app only.
- Web app only
- Refused for API keys and connected apps. Calendar feeds are created in the app only (the result is a private link).
- MCP tool
timeoff_feeds_createon My Workplace, 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
kind"person" | "unit"requiredunit_idstring1–120 characters.
Returns
idstringrequiredurlstringrequiredThe feed address (contains its secret; shown only now).
last4stringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/feeds.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"kind":"unit","unit_id":"u1"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/feeds.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"kind": "unit",
"unit_id": "u1"
}),
});
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/feeds.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"kind": "unit",
"unit_id": "u1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "f2",
"url": "https://api.bizisy.com/feeds/timeoff/bzto_org0000000001_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.ics",
"last4": "aaaa"
}
}Revoke a calendar feed#
POST/v1/timeoff/feeds.revokeDestructive
Turns a calendar feed off: its link stops working at once. Your own feeds; owners, admins and HR any (e.g. when someone leaves).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_feeds_revokeon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
feed_idstringrequired1–120 characters.
Returns
idstringrequiredrevokedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/feeds.revoke \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"feed_id":"f1"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/feeds.revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"feed_id": "f1"
}),
});
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/feeds.revoke",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"feed_id": "f1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "f1",
"revoked": true
}
}Absence report#
POST/v1/timeoff/reports.absenceRead
Working days away per month of a year, per team: vacation and other paid leave, unpaid leave, and health-related leave (sick and any type marked health). Health-related days show only for teams of 5 or more (smaller ones fold into "Smaller teams"), so no figure points at one person. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
timeoff_reports_absenceon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
yearintegerFrom 2000 to 2100.
Returns
yearintegerrequiredmonthsstring[]requiredteamsobject[]required3 fields
teamobject | nullrequirednull: "Smaller teams" or people without a team.
2 fields
idstringrequirednamestringrequired
peopleintegerrequiredrowsobject[]required4 fields
monthstringrequiredleavenumberrequiredunpaidnumberrequiredhealthnumber | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/reports.absence \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"year":2026}'const res = await fetch('https://api.bizisy.com/v1/timeoff/reports.absence', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"year": 2026
}),
});
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/reports.absence",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"year": 2026,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"year": 2026,
"months": [
"2026-01",
"2026-02"
],
"teams": [
{
"team": {
"id": "u1",
"name": "Engineering"
},
"people": 6,
"rows": [
{
"month": "2026-01",
"leave": 4,
"unpaid": 0,
"health": 1.5
},
{
"month": "2026-02",
"leave": 2.5,
"unpaid": 1,
"health": 0
}
]
},
{
"team": null,
"people": 3,
"rows": [
{
"month": "2026-01",
"leave": 1,
"unpaid": 0,
"health": null
},
{
"month": "2026-02",
"leave": 0,
"unpaid": 0,
"health": null
}
]
}
]
}
}My work schedule#
POST/v1/timeoff/my.scheduleRead
The caller's working days between from and to (at most 62 days): whether each is a working day, the expected minutes, the scheduled start and end (or core hours), public holidays and company days, and which schedule applies. For the person themself only.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
timeoff_my_scheduleon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.lang"en" | "pt" | "es" | "de" | "fr" | "it"Language of holiday names (default en).
Returns
daysobject[]required10 fields
datestringrequiredworkingbooleanrequiredexpected_minutesintegerrequiredExpected work minutes (0 on days off, holidays and company days).
startstring | nullrequiredendstring | nullrequiredcore_startstring | nullrequiredcore_endstring | nullrequiredholidaystring | nullrequiredcompany_daystring | nullrequiredscheduleobject | nullrequiredThe schedule that day; null: the working week and contract hours.
2 fields
idstringrequirednamestringrequired
weekly_minutesinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/timeoff/my.schedule \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"2026-10-12","to":"2026-10-18","lang":"es"}'const res = await fetch('https://api.bizisy.com/v1/timeoff/my.schedule', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"from": "2026-10-12",
"to": "2026-10-18",
"lang": "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/my.schedule",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"from": "2026-10-12",
"to": "2026-10-18",
"lang": "es",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"days": [
{
"date": "2026-10-12",
"working": true,
"expected_minutes": 480,
"start": "09:00",
"end": "18:00",
"core_start": null,
"core_end": null,
"holiday": null,
"company_day": null,
"schedule": {
"id": "sch1",
"name": "Office 40 h"
}
},
{
"date": "2026-10-17",
"working": false,
"expected_minutes": 0,
"start": null,
"end": null,
"core_start": null,
"core_end": null,
"holiday": null,
"company_day": null,
"schedule": {
"id": "sch1",
"name": "Office 40 h"
}
}
],
"weekly_minutes": 2220
}
}Something missing or wrong on this page? Write to hello@bizisy.com.