Skip to content

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

Input

  • person_idstring

    Whom 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_idstringrequired

    A leave type id (timeoff_types_list), e.g. vacation.

    1–120 characters.

  • startstringrequired

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

  • endstringrequired

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

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

    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.

  • hoursnumber

    Some 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_timestring

    With hours: when they start (HH:MM), optional.

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

  • notestring | null

    Seen by the person and HR only (never managers, colleagues or machines). Never write health details here.

    Up to 500 characters.

  • override_rulestrue

    HR only: record it although a rule blocks it (the rule is noted on the booking).

Returns

11 fields
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • typeobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • colorstringrequired
    • iconstringrequired
    • builtinbooleanrequired

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

  • daysnumberrequired

    Working days it costs.

  • partsobject[]required
    8 fields
    • datestringrequired
    • segment"full" | "am" | "pm" | "hours"required
    • minutesinteger | null

      Hours: the minutes booked.

    • start_timestring | null
    • day_minutesinteger | null

      Hours: the minutes scheduled that day (the cost is minutes ÷ day_minutes).

    • workingbooleanrequired
    • holidaystring | nullrequired
    • company_daystring | nullrequired
  • balancesobject[]required

    Types that use the balance: available before and after, per leave year.

    4 fields
    • year_startstringrequired
    • beforenumberrequired
    • afternumberrequired
    • negative_capnumberrequired
  • rulesobject[]required

    The company rules that warn, block or send it for approval.

    6 fields
    • rule_idstringrequired
    • namestringrequired
    • outcome"block" | "warn" | "needs_approval"required
    • messagestringrequired
    • daysstring[]required

      The 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"required

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

  • checkedobject[]required

    Every company rule that applies to this booking, with its verdict: pass, fail, or unknown (couldn't be decided: it never blocks).

    4 fields
    • rule_idstringrequired
    • namestringrequired
    • outcome"block" | "warn" | "needs_approval"required
    • state"pass" | "fail" | "unknown"required
  • approvalobjectrequired
    2 fields
    • neededbooleanrequired
    • stepsobject[]required
      2 fields
      • role"manager" | "hr"required
      • approverobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
  • problemsobject[]required

    Why it can't be booked as it is; empty: it can.

    3 fields
    • codestringrequired
    • messagestringrequired
    • hintstringrequired
  • can_bookbooleanrequired
  • returnsobject | nullrequired

    Sickness 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
    • daysnumberrequired

      Working days that go back to the balance.

    • lawstringrequired

      The country's rule (the EU rule, CJEU C-78/11, where Bizisy has no row of its own).

    • urlstringrequired
    • evidence"certificate" | "notice"required

      What the person owes under that rule: a medical certificate, or telling the employer.

    • requestsobject[]required
      4 fields
      • request_idstringrequired
      • typeobjectrequired
        5 fields
        • idstringrequired
        • namestringrequired
        • colorstringrequired
        • iconstringrequired
        • builtinbooleanrequired

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

      • datesstring[]required
      • daysnumberrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • person_idstring

    Whom 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_idstringrequired

    A leave type id (timeoff_types_list), e.g. vacation.

    1–120 characters.

  • startstringrequired

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

  • endstringrequired

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

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

    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.

  • hoursnumber

    Some 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_timestring

    With hours: when they start (HH:MM), optional.

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

  • notestring | null

    Seen by the person and HR only (never managers, colleagues or machines). Never write health details here.

    Up to 500 characters.

  • override_rulestrue

    HR only: record it although a rule blocks it (the rule is noted on the booking).

Returns

21 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • startstringrequired
  • endstringrequired
  • start_part"full" | "am" | "pm" | "hours"required

    full, 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"required

    full, or am: the last day ends at noon; hours with start_part hours.

  • minutesinteger | nullrequired

    Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

  • start_timestring | nullrequired

    Hours: when they start (HH:MM), if given; the person, their managers and HR only.

  • daysnumberrequired

    Working days it costs (hours: minutes ÷ the day's scheduled minutes).

  • status"pending" | "approved" | "declined" | "cancelled"required
  • typeobject | nullrequired

    null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

    5 fields
    • idstringrequired
    • namestringrequired
    • colorstringrequired
    • iconstringrequired
    • builtinbooleanrequired

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

  • notestring | nullrequired

    The person and HR only.

  • stepsobject[]required

    Approval steps ([] when booked at once). Only the person, their managers and HR see them.

    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      manager steps: who is asked; null for HR (anyone in HR decides).

      2 fields
      • idstringrequired
      • namestringrequired
    • decided_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • by_rulestring | null

      Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

  • booked_by"self" | "hr" | "import" | "company_day"required

    self, hr, import or company_day; null when the viewer does not see the type.

  • warningsstring[]required

    Rule warnings when it was booked (the person, managers and HR).

  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • created_atstringrequired
  • decided_atstring | nullrequired
  • cancelled_atstring | nullrequired
  • returnedobject | nullrequired

    Sickness 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
    • daysnumberrequired
    • datesstring[]required
    • lawstringrequired
    • side"leave" | "sickness"required

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

Input

  • person_idsstring[]required

    1–120 characters. 1–100 items.

  • type_idstringrequired

    1–120 characters.

  • startstringrequired

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

  • endstringrequired

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

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

    Seen by the person and HR only (never managers, colleagues or machines). Never write health details here.

    Up to 500 characters.

  • override_rulestrue

Returns

  • bookedintegerrequired
  • skippedintegerrequired
  • rowsobject[]required
    5 fields
    • person_idstringrequired
    • okbooleanrequired
    • request_idstring | nullrequired
    • daysnumberrequired
    • problemstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

  • request_idstringrequired

    1–120 characters.

  • reasonstring | null

    Up to 300 characters.

Returns

21 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • startstringrequired
  • endstringrequired
  • start_part"full" | "am" | "pm" | "hours"required

    full, 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"required

    full, or am: the last day ends at noon; hours with start_part hours.

  • minutesinteger | nullrequired

    Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

  • start_timestring | nullrequired

    Hours: when they start (HH:MM), if given; the person, their managers and HR only.

  • daysnumberrequired

    Working days it costs (hours: minutes ÷ the day's scheduled minutes).

  • status"pending" | "approved" | "declined" | "cancelled"required
  • typeobject | nullrequired

    null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

    5 fields
    • idstringrequired
    • namestringrequired
    • colorstringrequired
    • iconstringrequired
    • builtinbooleanrequired

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

  • notestring | nullrequired

    The person and HR only.

  • stepsobject[]required

    Approval steps ([] when booked at once). Only the person, their managers and HR see them.

    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      manager steps: who is asked; null for HR (anyone in HR decides).

      2 fields
      • idstringrequired
      • namestringrequired
    • decided_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • by_rulestring | null

      Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

  • booked_by"self" | "hr" | "import" | "company_day"required

    self, hr, import or company_day; null when the viewer does not see the type.

  • warningsstring[]required

    Rule warnings when it was booked (the person, managers and HR).

  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • created_atstringrequired
  • decided_atstring | nullrequired
  • cancelled_atstring | nullrequired
  • returnedobject | nullrequired

    Sickness 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
    • daysnumberrequired
    • datesstring[]required
    • lawstringrequired
    • side"leave" | "sickness"required

      leave: 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
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."}'
Response
{
  "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_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"pending" | "approved" | "declined" | "cancelled"
  • person_idstring

    1–120 characters.

  • waiting_for_meboolean
  • fromstring

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

  • tostring

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

  • unit_idstring

    1–120 characters.

  • limitinteger

    From 1 to 500.

Returns

  • itemsobject[]required
    21 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • startstringrequired
    • endstringrequired
    • start_part"full" | "am" | "pm" | "hours"required

      full, 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"required

      full, or am: the last day ends at noon; hours with start_part hours.

    • minutesinteger | nullrequired

      Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

    • start_timestring | nullrequired

      Hours: when they start (HH:MM), if given; the person, their managers and HR only.

    • daysnumberrequired

      Working days it costs (hours: minutes ÷ the day's scheduled minutes).

    • status"pending" | "approved" | "declined" | "cancelled"required
    • typeobject | nullrequired

      null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

      5 fields
      • idstringrequired
      • namestringrequired
      • colorstringrequired
      • iconstringrequired
      • builtinbooleanrequired

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

    • notestring | nullrequired

      The person and HR only.

    • stepsobject[]required

      Approval steps ([] when booked at once). Only the person, their managers and HR see them.

      7 fields
      • role"manager" | "hr"required
      • state"waiting" | "pending" | "approved" | "declined"required
      • approverobject | nullrequired

        manager steps: who is asked; null for HR (anyone in HR decides).

        2 fields
        • idstringrequired
        • namestringrequired
      • decided_byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • by_rulestring | null

        Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

    • booked_by"self" | "hr" | "import" | "company_day"required

      self, hr, import or company_day; null when the viewer does not see the type.

    • warningsstring[]required

      Rule warnings when it was booked (the person, managers and HR).

    • can_cancelbooleanrequired
    • can_decidebooleanrequired
    • created_atstringrequired
    • decided_atstring | nullrequired
    • cancelled_atstring | nullrequired
    • returnedobject | nullrequired

      Sickness 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
      • daysnumberrequired
      • datesstring[]required
      • lawstringrequired
      • side"leave" | "sickness"required

        leave: this booking lost the days; sickness: this sick leave gave them back.

  • waiting_for_meintegerrequired
  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • request_idstringrequired

    1–120 characters.

Returns

21 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • startstringrequired
  • endstringrequired
  • start_part"full" | "am" | "pm" | "hours"required

    full, 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"required

    full, or am: the last day ends at noon; hours with start_part hours.

  • minutesinteger | nullrequired

    Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

  • start_timestring | nullrequired

    Hours: when they start (HH:MM), if given; the person, their managers and HR only.

  • daysnumberrequired

    Working days it costs (hours: minutes ÷ the day's scheduled minutes).

  • status"pending" | "approved" | "declined" | "cancelled"required
  • typeobject | nullrequired

    null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

    5 fields
    • idstringrequired
    • namestringrequired
    • colorstringrequired
    • iconstringrequired
    • builtinbooleanrequired

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

  • notestring | nullrequired

    The person and HR only.

  • stepsobject[]required

    Approval steps ([] when booked at once). Only the person, their managers and HR see them.

    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      manager steps: who is asked; null for HR (anyone in HR decides).

      2 fields
      • idstringrequired
      • namestringrequired
    • decided_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • by_rulestring | null

      Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

  • booked_by"self" | "hr" | "import" | "company_day"required

    self, hr, import or company_day; null when the viewer does not see the type.

  • warningsstring[]required

    Rule warnings when it was booked (the person, managers and HR).

  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • created_atstringrequired
  • decided_atstring | nullrequired
  • cancelled_atstring | nullrequired
  • returnedobject | nullrequired

    Sickness 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
    • daysnumberrequired
    • datesstring[]required
    • lawstringrequired
    • side"leave" | "sickness"required

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

Input

  • request_idstringrequired

    1–120 characters.

  • decision"approve" | "decline"required
  • commentstring | null

    Up to 500 characters.

  • whystring | null

    Optional: 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
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • startstringrequired
  • endstringrequired
  • start_part"full" | "am" | "pm" | "hours"required

    full, 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"required

    full, or am: the last day ends at noon; hours with start_part hours.

  • minutesinteger | nullrequired

    Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

  • start_timestring | nullrequired

    Hours: when they start (HH:MM), if given; the person, their managers and HR only.

  • daysnumberrequired

    Working days it costs (hours: minutes ÷ the day's scheduled minutes).

  • status"pending" | "approved" | "declined" | "cancelled"required
  • typeobject | nullrequired

    null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

    5 fields
    • idstringrequired
    • namestringrequired
    • colorstringrequired
    • iconstringrequired
    • builtinbooleanrequired

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

  • notestring | nullrequired

    The person and HR only.

  • stepsobject[]required

    Approval steps ([] when booked at once). Only the person, their managers and HR see them.

    7 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "declined"required
    • approverobject | nullrequired

      manager steps: who is asked; null for HR (anyone in HR decides).

      2 fields
      • idstringrequired
      • namestringrequired
    • decided_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • commentstring | nullrequired
    • by_rulestring | null

      Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

  • booked_by"self" | "hr" | "import" | "company_day"required

    self, hr, import or company_day; null when the viewer does not see the type.

  • warningsstring[]required

    Rule warnings when it was booked (the person, managers and HR).

  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • created_atstringrequired
  • decided_atstring | nullrequired
  • cancelled_atstring | nullrequired
  • returnedobject | nullrequired

    Sickness 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
    • daysnumberrequired
    • datesstring[]required
    • lawstringrequired
    • side"leave" | "sickness"required

      leave: 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
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"
}'
Response
{
  "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_overview on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

7 fields
  • todaystringrequired
  • balancesobject[]required
    11 fields
    • yearobjectrequired

      The leave year.

      2 fields
      • startstringrequired
      • endstringrequired
    • entitlementnumberrequired

      Days for the whole leave year (prorated by working time and time employed).

    • allowancenumberrequired

      Accrued so far (monthly accrual), else the entitlement.

    • carriednumberrequired

      Days carried over from the year before.

    • carried_expires_onstring | nullrequired

      Unused carried days lapse after this day.

    • adjustmentsnumberrequired

      HR adjustments (corrections, imports, restored days).

    • takennumberrequired
    • bookednumberrequired

      Booked or requested days still ahead (and requests waiting for a decision).

    • availablenumberrequired
    • lapsingnumberrequired

      Carried days that lapse unless taken before carried_expires_on.

    • day_minutesintegerrequired

      Their 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[]required

    Pending and booked days from today on, soonest first.

    21 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • startstringrequired
    • endstringrequired
    • start_part"full" | "am" | "pm" | "hours"required

      full, 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"required

      full, or am: the last day ends at noon; hours with start_part hours.

    • minutesinteger | nullrequired

      Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

    • start_timestring | nullrequired

      Hours: when they start (HH:MM), if given; the person, their managers and HR only.

    • daysnumberrequired

      Working days it costs (hours: minutes ÷ the day's scheduled minutes).

    • status"pending" | "approved" | "declined" | "cancelled"required
    • typeobject | nullrequired

      null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

      5 fields
      • idstringrequired
      • namestringrequired
      • colorstringrequired
      • iconstringrequired
      • builtinbooleanrequired

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

    • notestring | nullrequired

      The person and HR only.

    • stepsobject[]required

      Approval steps ([] when booked at once). Only the person, their managers and HR see them.

      7 fields
      • role"manager" | "hr"required
      • state"waiting" | "pending" | "approved" | "declined"required
      • approverobject | nullrequired

        manager steps: who is asked; null for HR (anyone in HR decides).

        2 fields
        • idstringrequired
        • namestringrequired
      • decided_byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • by_rulestring | null

        Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

    • booked_by"self" | "hr" | "import" | "company_day"required

      self, hr, import or company_day; null when the viewer does not see the type.

    • warningsstring[]required

      Rule warnings when it was booked (the person, managers and HR).

    • can_cancelbooleanrequired
    • can_decidebooleanrequired
    • created_atstringrequired
    • decided_atstring | nullrequired
    • cancelled_atstring | nullrequired
    • returnedobject | nullrequired

      Sickness 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
      • daysnumberrequired
      • datesstring[]required
      • lawstringrequired
      • side"leave" | "sickness"required

        leave: this booking lost the days; sickness: this sick leave gave them back.

  • pastobject[]required

    The last 20 past, declined or cancelled ones, newest first.

    21 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • startstringrequired
    • endstringrequired
    • start_part"full" | "am" | "pm" | "hours"required

      full, 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"required

      full, or am: the last day ends at noon; hours with start_part hours.

    • minutesinteger | nullrequired

      Some hours of one day: the minutes booked (null otherwise, and for colleagues and machines, who see "Away part of the day").

    • start_timestring | nullrequired

      Hours: when they start (HH:MM), if given; the person, their managers and HR only.

    • daysnumberrequired

      Working days it costs (hours: minutes ÷ the day's scheduled minutes).

    • status"pending" | "approved" | "declined" | "cancelled"required
    • typeobject | nullrequired

      null: "Away" — the viewer does not see the type (colleagues, machines, managers for away-only and health types).

      5 fields
      • idstringrequired
      • namestringrequired
      • colorstringrequired
      • iconstringrequired
      • builtinbooleanrequired

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

    • notestring | nullrequired

      The person and HR only.

    • stepsobject[]required

      Approval steps ([] when booked at once). Only the person, their managers and HR see them.

      7 fields
      • role"manager" | "hr"required
      • state"waiting" | "pending" | "approved" | "declined"required
      • approverobject | nullrequired

        manager steps: who is asked; null for HR (anyone in HR decides).

        2 fields
        • idstringrequired
        • namestringrequired
      • decided_byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • by_rulestring | null

        Approved at once by the company's rule (Ask HR decision records): the rule, in its words.

    • booked_by"self" | "hr" | "import" | "company_day"required

      self, hr, import or company_day; null when the viewer does not see the type.

    • warningsstring[]required

      Rule warnings when it was booked (the person, managers and HR).

    • can_cancelbooleanrequired
    • can_decidebooleanrequired
    • created_atstringrequired
    • decided_atstring | nullrequired
    • cancelled_atstring | nullrequired
    • returnedobject | nullrequired

      Sickness 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
      • daysnumberrequired
      • datesstring[]required
      • lawstringrequired
      • side"leave" | "sickness"required

        leave: this booking lost the days; sickness: this sick leave gave them back.

  • pendingintegerrequired
  • typesobject[]required
    9 fields
    • idstringrequired
    • namestringrequired
    • colorstringrequired
    • iconstringrequired
    • builtinbooleanrequired

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

    • uses_balancebooleanrequired
    • bookablebooleanrequired

      false: HR records it (e.g. sick leave).

    • needs_approvalbooleanrequired
    • hours_min_minutesinteger | nullrequired

      Some 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
curl https://api.bizisy.com/v1/timeoff/my.overview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_calendar on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • fromstringrequired

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

  • tostringrequired

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

  • person_idstring

    HR: 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[]required
    7 fields
    • datestringrequired
    • workingbooleanrequired
    • holidaystring | nullrequired
    • company_daystring | nullrequired
    • minutesintegerrequired

      Minutes scheduled that day (0 when not a working day): what some hours are measured against.

    • startstring | nullrequired

      A fixed schedule's start that day (HH:MM).

    • endstring | nullrequired
  • bookedobject[]required
    7 fields
    • datestringrequired
    • segment"full" | "am" | "pm" | "hours"required
    • status"pending" | "approved"required
    • request_idstringrequired
    • typeobject | nullrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • colorstringrequired
      • iconstringrequired
      • builtinbooleanrequired

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

    • minutesinteger | nullrequired

      hours: the minutes booked.

    • start_timestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • fromstringrequired

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

  • tostringrequired

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

  • unit_idstring

    1–120 characters.

  • location_idstring

    1–120 characters.

  • person_idstring

    1–120 characters.

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

    Language of holiday names (default en).

Returns

8 fields
  • fromstringrequired
  • tostringrequired
  • todaystringrequired
  • peopleobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • location_idstring | nullrequired
  • itemsobject[]required
    10 fields
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • request_idstring | nullrequired

      Only for the person, their managers and HR.

    • startstringrequired
    • endstringrequired
    • start_part"full" | "am" | "pm" | "hours"required

      hours: away part of the day.

    • end_part"full" | "am" | "pm" | "hours"required
    • minutesinteger | null

      Hours: the minutes (the person, their managers and HR only).

    • start_timestring | null

      Hours: when they start (the person, their managers and HR only).

    • status"pending" | "approved"required

      Colleagues and machines only ever see approved days.

    • typeobject | nullrequired

      null: "Away".

      5 fields
      • idstringrequired
      • namestringrequired
      • colorstringrequired
      • iconstringrequired
      • builtinbooleanrequired

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

  • holidaysobject[]required
    4 fields
    • datestringrequired
    • namestringrequired
    • location_idstring | nullrequired
    • kind"public" | "company"required
  • coverageobject[]required
    3 fields
    • datestringrequired
    • awayintegerrequired
    • totalintegerrequired
  • hiddenbooleanrequired

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

Input

  • yearinteger

    From 2000 to 2100.

  • unit_idstring

    1–120 characters.

  • location_idstring

    1–120 characters.

  • qstring

    Up to 100 characters.

Returns

  • yearobjectrequired
    2 fields
    • startstringrequired
    • endstringrequired
  • rowsobject[]required
    2 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • location_idstring | nullrequired
    • balanceobjectrequired
      11 fields
      • yearobjectrequired

        The leave year.

        2 fields
        • startstringrequired
        • endstringrequired
      • entitlementnumberrequired

        Days for the whole leave year (prorated by working time and time employed).

      • allowancenumberrequired

        Accrued so far (monthly accrual), else the entitlement.

      • carriednumberrequired

        Days carried over from the year before.

      • carried_expires_onstring | nullrequired

        Unused carried days lapse after this day.

      • adjustmentsnumberrequired

        HR adjustments (corrections, imports, restored days).

      • takennumberrequired
      • bookednumberrequired

        Booked or requested days still ahead (and requests waiting for a decision).

      • availablenumberrequired
      • lapsingnumberrequired

        Carried days that lapse unless taken before carried_expires_on.

      • day_minutesintegerrequired

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

Input

  • person_idstring

    1–120 characters.

Returns

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • balancesobject[]required
    11 fields
    • yearobjectrequired

      The leave year.

      2 fields
      • startstringrequired
      • endstringrequired
    • entitlementnumberrequired

      Days for the whole leave year (prorated by working time and time employed).

    • allowancenumberrequired

      Accrued so far (monthly accrual), else the entitlement.

    • carriednumberrequired

      Days carried over from the year before.

    • carried_expires_onstring | nullrequired

      Unused carried days lapse after this day.

    • adjustmentsnumberrequired

      HR adjustments (corrections, imports, restored days).

    • takennumberrequired
    • bookednumberrequired

      Booked or requested days still ahead (and requests waiting for a decision).

    • availablenumberrequired
    • lapsingnumberrequired

      Carried days that lapse unless taken before carried_expires_on.

    • day_minutesintegerrequired

      Their 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[]required
    7 fields
    • idstringrequired
    • yearintegerrequired
    • amountnumberrequired
    • reasonstringrequired
    • kindstringrequired
    • expires_onstring | nullrequired
    • created_atstringrequired
  • below_minimumobject | nullrequired

    Owners, 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_daysnumberrequired
    • minimumnumberrequired
    • countrystring | nullrequired
    • sourcestringrequired
    • basisstringrequired
    • refusebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/balances.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p3"}'
Response
{
  "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_adjust on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstringrequired

    1–120 characters.

  • amountnumberrequired

    From -366 to 366.

  • reasonstringrequired

    1–300 characters.

  • yearinteger

    From 2000 to 2100.

  • expires_onstring | null

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

  • kind"manual" | "restore"

Returns

  • idstringrequired
  • person_idstringrequired
  • balanceobjectrequired
    11 fields
    • yearobjectrequired

      The leave year.

      2 fields
      • startstringrequired
      • endstringrequired
    • entitlementnumberrequired

      Days for the whole leave year (prorated by working time and time employed).

    • allowancenumberrequired

      Accrued so far (monthly accrual), else the entitlement.

    • carriednumberrequired

      Days carried over from the year before.

    • carried_expires_onstring | nullrequired

      Unused carried days lapse after this day.

    • adjustmentsnumberrequired

      HR adjustments (corrections, imports, restored days).

    • takennumberrequired
    • bookednumberrequired

      Booked or requested days still ahead (and requests waiting for a decision).

    • availablenumberrequired
    • lapsingnumberrequired

      Carried days that lapse unless taken before carried_expires_on.

    • day_minutesintegerrequired

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

Input

  • yearinteger

    From 2000 to 2100.

Returns

  • filenamestringrequired
  • csvstringrequired
  • rowsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/balances.export \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026}'
Response
{
  "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_import on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • rowsobject[]required

    1–200 items.

    5 fields
    • work_emailstringrequired

      Up to 320 characters.

    • daysnumber | stringrequired
    • reasonstring | null

      Up to 300 characters.

    • yearnumber | string
    • expires_onstring | null

      Up to 20 characters.

Returns

  • createdintegerrequired
  • rowsobject[]required
    3 fields
    • rowintegerrequired
    • okbooleanrequired
    • problemstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

  • rowsobject[]required

    1–200 items.

    9 fields
    • work_emailstringrequired

      Up to 320 characters.

    • typestringrequired

      A type id or its name (case-insensitive), e.g. vacation.

      Up to 60 characters.

    • startstringrequired

      Up to 20 characters.

    • endstring | null

      Up to 20 characters.

    • start_partstring | null

      Up to 10 characters.

    • end_partstring | null

      Up to 10 characters.

    • notestring | null

      Up to 500 characters.

    • hoursnumber | string

      Some hours of one day instead of day-parts (e.g. 2.5).

    • start_timestring | null

      Up to 10 characters.

  • override_rulestrue

Returns

  • createdintegerrequired
  • rowsobject[]required
    4 fields
    • rowintegerrequired
    • okbooleanrequired
    • problemstring | nullrequired
    • daysnumberrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

No input: send {}.

Returns

An array of objects:

  • idstringrequired
  • kind"person" | "unit"required
  • subjectobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • last4stringrequired
  • created_atstringrequired
  • last_used_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • kind"person" | "unit"required
  • unit_idstring

    1–120 characters.

Returns

  • idstringrequired
  • urlstringrequired

    The feed address (contains its secret; shown only now).

  • last4stringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

  • feed_idstringrequired

    1–120 characters.

Returns

  • idstringrequired
  • revokedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

  • yearinteger

    From 2000 to 2100.

Returns

  • yearintegerrequired
  • monthsstring[]required
  • teamsobject[]required
    3 fields
    • teamobject | nullrequired

      null: "Smaller teams" or people without a team.

      2 fields
      • idstringrequired
      • namestringrequired
    • peopleintegerrequired
    • rowsobject[]required
      4 fields
      • monthstringrequired
      • leavenumberrequired
      • unpaidnumberrequired
      • healthnumber | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/timeoff/reports.absence \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026}'
Response
{
  "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_schedule on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • fromstringrequired

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

  • tostringrequired

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

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

    Language of holiday names (default en).

Returns

  • daysobject[]required
    10 fields
    • datestringrequired
    • workingbooleanrequired
    • expected_minutesintegerrequired

      Expected work minutes (0 on days off, holidays and company days).

    • startstring | nullrequired
    • endstring | nullrequired
    • core_startstring | nullrequired
    • core_endstring | nullrequired
    • holidaystring | nullrequired
    • company_daystring | nullrequired
    • scheduleobject | nullrequired

      The schedule that day; null: the working week and contract hours.

      2 fields
      • idstringrequired
      • namestringrequired
  • weekly_minutesinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Developer docs