Tools Reference
BookYourPTO MCP exposes 385 tools across 18 categories to every connected client. A self-hosted server running in per-user mode also registers the login tool described under Auth. Every tool is listed below with its parameters and behaviour. This page is generated from the live tool registry, so it matches what your AI client actually sees.
Authentication
Authentication is handled automatically via OAuth 2.0 with PKCE. When you first connect, your browser opens a BookYourPTO login page; after you sign in, your AI client receives a short-lived access token — no credentials are ever shared with the AI. Every tool runs with your own identity and role-based permissions.
How to read this page
Each tool shows MCP annotations and a risk level that the host uses to decide when to prompt you for confirmation:
- Read-only — does not change any data (
readOnlyHint). Safe to call freely. - Write — creates or updates data. The AI should confirm intent before calling.
- Destructive — deletes data or performs an irreversible action (
destructiveHint). Hosts typically require explicit confirmation. - Risk: medium / high — surfaced to the client; high-risk tools (offboarding, deletes, payouts, publishing) should only be called after you explicitly confirm the specific record by ID.
Tool Categories
| Category | Tools | Jump to |
|---|---|---|
| Leaves | 12 | Leaves |
| Time Tracking | 15 | Time Tracking |
| Expenses | 25 | Expenses |
| Users | 21 | Users |
| Schedules | 12 | Schedules |
| Projects | 15 | Projects |
| Organization | 17 | Organization |
| Reports | 2 | Reports |
| HR | 73 | HR |
| Clients | 5 | Clients |
| Notifications | 5 | Notifications |
| Calendar | 8 | Calendar |
| Performance | 37 | Performance |
| Training | 14 | Training |
| Benefits | 8 | Benefits |
| Documents | 21 | Documents |
| Admin | 94 | Admin |
| System | 1 | System |
| Auth | 1 (per-user mode only) | Auth |
Leaves
12 tools.
query_leaves
List one person's leave requests that start in a given year. Without a status filter only PENDING and APPROVED leaves are returned; pass a status to see REJECTED, CANCELLED or WITHDRAWN ones. Defaults to the signed-in user. Reading someone else's leave follows the organization's calendar-visibility settings (ADMINISTRATOR and EXECUTIVE may read anyone; others may be refused with 403), and private leave types are shown as "Private" to viewers who are not the owner, an administrator/executive or the owner's department head.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | User ID to query (defaults to authenticated user) |
year | integer | No | Year the leaves start in (defaults to the current year) |
status | enum: PENDING, APPROVED, REJECTED, CANCELLED, WITHDRAWN | No | Only this status. Omit for PENDING and APPROVED together. |
get_leave_balance
Get the leave balance for a user and fiscal year: the annual bucket (allowance includes carry-over), the sick bucket, a row per balance-deducting leave type, and the non-deducting leave types used this year (days taken, and the cap where the type has one). Each row carries the leaveTypeId that create_leave_request needs. Defaults to the signed-in user. Reading someone else follows the calendar-visibility settings: ADMINISTRATOR and EXECUTIVE may read anyone in the organization; others may be refused with 403.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | User ID (defaults to authenticated user) |
year | integer | No | Fiscal year (defaults to current year) |
get_pending_leave_approvals
List PENDING leave requests waiting for a decision. Available to ADMINISTRATOR, EXECUTIVE and DEPARTMENT_HEAD, and to anyone flagged as an approver; others get 403. The caller's own requests are never included (no self-approval). A department head sees only the departments they head or manage. An EMPLOYEE flagged as an approver sees only the requests on which they are the first- or second-level approver, and a private leave type shows to them as "Private" with its reason and notes hidden. For requests to cancel already-approved leave, use get_pending_leave_cancellations.
Read-only
No parameters.
create_leave_request
Submit a new leave request. Anyone may book for themselves; ADMINISTRATOR and EXECUTIVE may book for anyone in the organization; a DEPARTMENT_HEAD may book for people in the departments they head or manage. The request is APPROVED at once when the leave type needs no approval, when the person is an EXECUTIVE, or when an administrator, executive or the person's department head books it for someone else; otherwise it is PENDING. Refused when the person is deactivated or offboarded, when the dates are not YYYY-MM-DD or the end is before the start, when the type's minimum notice or maximum days per request is not met, when the range covers only non-business days or holidays, when it overlaps an existing pending or approved leave, when the dates are locked, or when the balance is insufficient. Custom start/end times are only for single-day leaves. Use get_leave_balance first to check availability.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | ID of the person the leave is for (pass your own user ID to book for yourself) |
leaveTypeId | string | Yes | Leave type ID (use bypto://leave-types resource to look up) |
startDate | string | Yes | First day of leave (YYYY-MM-DD) |
endDate | string | Yes | Last day of leave (YYYY-MM-DD) |
startHalf | enum: FULL_DAY, FIRST_HALF, SECOND_HALF | No | Half-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY") |
endHalf | enum: FULL_DAY, FIRST_HALF, SECOND_HALF | No | Half-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY") |
leaveStartTime | string | No | Start time (HH:mm) for an hours-based single-day leave |
leaveEndTime | string | No | End time (HH:mm) for an hours-based single-day leave |
reason | string | No | Reason for leave |
notes | string | No | Additional notes |
approve_or_reject_leave
Approve or reject a PENDING leave request. Requires an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD, or someone flagged as an approver; a department head only for people in their departments, and an EMPLOYEE flagged as an approver only for requests assigned to them as first- or second-level approver (403 otherwise). Refused for your own leave and for a leave that is no longer PENDING. For a request to cancel an approved leave, use approve_or_reject_leave_cancellation.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
leaveId | string | Yes | ID of the leave request |
action | enum: approve, reject | Yes | Action to take |
reason | string | No | Rejection reason shown to the employee |
update_leave
Change a PENDING leave request (type, dates, half days, hours or reason). Only the fields you provide change; the rest are kept. Allowed for the owner, ADMINISTRATOR and EXECUTIVE, and a DEPARTMENT_HEAD for people in their departments. An APPROVED, rejected or cancelled leave cannot be edited: to change an approved leave, cancel it (delete_leave) or ask for cancellation (request_leave_cancellation) and book again. The new dates pass the same rules as a new request (notice, overlaps, locked dates, balance). Pass userId when the leave belongs to someone else.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
leaveId | string | Yes | Resource ID |
userId | string | No | Owner of the leave (defaults to the signed-in user; needed to find someone else's leave) |
leaveTypeId | string | No | New leave type ID |
startDate | string | No | New first day (YYYY-MM-DD) |
endDate | string | No | New last day (YYYY-MM-DD) |
startHalf | enum: FULL_DAY, FIRST_HALF, SECOND_HALF | No | |
endHalf | enum: FULL_DAY, FIRST_HALF, SECOND_HALF | No | |
leaveStartTime | string | No | Start time (HH:mm), single-day hours-based leave |
leaveEndTime | string | No | End time (HH:mm), single-day hours-based leave |
reason | string | No |
delete_leave
Cancel a leave request. Nothing is deleted: the leave is marked CANCELLED, kept in history, and stops counting against the balance. ADMINISTRATOR and EXECUTIVE may cancel anyone's PENDING or APPROVED leave, even after it started; a DEPARTMENT_HEAD may do the same for people in their departments. The owner may cancel their own PENDING leave until its first day; the owner's APPROVED leave cannot be cancelled here (refused) - use request_leave_cancellation so an approver decides. Rejected, cancelled or withdrawn leave cannot be cancelled. The owner is notified when someone else cancels it.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
leaveId | string | Yes | Resource ID |
query_leave_schedule
Who is on leave between two dates, across the team: each active person with PENDING or APPROVED leave overlapping the range, plus the public holidays in it. Useful for capacity planning and spotting staffing gaps. What the caller sees follows the organization's privacy settings: when department viewing is restricted, non-admins see only their own department (department heads, the departments they head or manage). Private leave types show as "Private" to viewers who may not see them.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | Start date (YYYY-MM-DD) |
endDate | string | Yes | End date (YYYY-MM-DD) |
departmentIds | string | No | Only people in these departments |
group_book_leaves
Book the same leave for every active person in one department (e.g. a shutdown or offsite). ADMINISTRATOR or EXECUTIVE only. Each person gets their own leave record, approved at once. People with an overlapping leave, or without enough balance, are skipped and listed; the result reports how many were created, skipped and failed. Refused when the department is unknown or inactive, has no active people, or the range covers only weekends and public holidays.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
departmentId | string | Yes | Department whose active members are booked |
leaveTypeId | string | Yes | Leave type ID |
startDate | string | Yes | First day (YYYY-MM-DD) |
endDate | string | Yes | Last day (YYYY-MM-DD) |
startHalf | enum: FULL_DAY, FIRST_HALF, SECOND_HALF | No | Half-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY") |
endHalf | enum: FULL_DAY, FIRST_HALF, SECOND_HALF | No | Half-day setting: FULL_DAY, FIRST_HALF, or SECOND_HALF (default: "FULL_DAY") |
reason | string | No | |
notes | string | No |
request_leave_cancellation
Ask for one of your own APPROVED leaves to be cancelled. The leave stays APPROVED (and keeps its days reserved) until an approver accepts or declines the request; approvers are notified. Only the owner may ask. Refused when the leave is not APPROVED, when a cancellation request is already pending for it, or when the leave has already ended (judged on the owner's calendar day). A PENDING leave does not need this: cancel it directly with delete_leave.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
leaveId | string | Yes | Resource ID |
reason | string | No | Why the leave should be cancelled |
get_pending_leave_cancellations
List APPROVED leaves whose owner has asked for them to be cancelled and that are waiting for a decision, oldest request first. Available to ADMINISTRATOR, EXECUTIVE and DEPARTMENT_HEAD, and to anyone flagged as an approver; others get 403. The caller's own requests are never included; a department head sees only the departments they head or manage. An EMPLOYEE flagged as an approver sees only requests on which they are the first- or second-level approver, and a private leave type shows to them as "Private" with its reason and notes hidden. Decide each with approve_or_reject_leave_cancellation.
Read-only
No parameters.
approve_or_reject_leave_cancellation
Decide a pending request to cancel an APPROVED leave. Approving cancels the leave (status CANCELLED, days returned to the balance); rejecting clears the request and the leave stays APPROVED. The owner is notified either way. Requires an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD, or someone flagged as an approver; a department head only for people in their departments, and an EMPLOYEE flagged as an approver only for requests assigned to them as first- or second-level approver (403 otherwise). Refused for your own leave, when there is no pending cancellation request, or when the leave is no longer APPROVED.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
leaveId | string | Yes | Resource ID |
action | enum: approve, reject | Yes | approve = cancel the leave; reject = keep it approved |
reason | string | No | Reason given to the owner when rejecting |
Time Tracking
15 tools.
get_time_tracking_status
Get current clock status (clocked in / out / on break) and today's summary for a user.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | User ID (defaults to authenticated user) |
clock_action
Clock the caller in or out, or start/end a break, at the current time. The organization may require a project, task or description on clock_in (PROJECT_REQUIRED, TASK_REQUIRED, DESCRIPTION_REQUIRED). This tool cannot send a GPS position, so in an organization that requires location, or enforces geofencing in REQUIRED mode, clock_in and clock_out are refused with LOCATION_REQUIRED: the person must clock from the mobile app or browser instead, or ask an administrator to add a manual entry. Also refused when time tracking is switched off (TIME_TRACKING_DISABLED) or the state does not allow the action (ALREADY_CLOCKED_IN, NOT_CLOCKED_IN, ALREADY_ON_BREAK, NOT_ON_BREAK).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
action | enum: clock_in, clock_out, start_break, end_break | Yes | The clock action to perform |
projectId | string | No | Project ID (for clock_in, if required by org settings) |
taskId | string | No | Task ID (for clock_in) |
description | string | No | Work description (for clock_in, max 500 characters) |
query_time_entries
List time entries, newest clock-in first, with the total approved / pending / rejected minutes for the whole filtered set (not just this page). Without userId an EMPLOYEE sees their own entries, a DEPARTMENT_HEAD their departments and ADMINISTRATOR/EXECUTIVE the organization; asking for someone outside that scope is refused (403). A date range may span at most 120 days: for a longer period (for example "hours this year") call this once per window of up to 120 days and add the totals. durationMinutes is already net of breaks.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Only this person's entries |
departmentId | string | No | Only this department (ADMINISTRATOR/EXECUTIVE only; ignored for other roles) |
startDate | string | No | Clock-in on or after (YYYY-MM-DD) |
endDate | string | No | Clock-in on or before (YYYY-MM-DD). At most 120 days after startDate. |
projectId | string | No | Filter by project ID |
approvalStatus | enum: PENDING, APPROVED, REJECTED | No | |
billable | boolean | No | Only billable (true) or non-billable (false) entries |
tag | string | No | Only entries carrying this tag |
page | integer | No | Page number (default: 1) |
limit | integer | No | Results per page (max 50) (default: 20) |
create_time_entry
Create a manual time entry (for example a forgotten clock-in). Refused (403) when the organization turned manual entry off, unless the caller is an ADMINISTRATOR/EXECUTIVE. Only an ADMINISTRATOR/EXECUTIVE may pass another person's userId; for a deactivated person only time up to their last day is accepted. Entries by administrators/executives are approved at once; others are PENDING when the organization requires approval. A taskId must belong to the projectId given (otherwise 400). Refused (403) for an entry in a locked pay period, unless the caller is an ADMINISTRATOR/EXECUTIVE, and refused for everyone when the entry falls in a FINALIZED or SIGNED timesheet period.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Whose time this is (ADMINISTRATOR/EXECUTIVE only); defaults to the caller |
clockIn | string | Yes | Clock-in date and time (ISO 8601 with offset, e.g. 2026-05-24T09:00:00-04:00) |
clockOut | string | No | Clock-out date and time (ISO 8601 with offset) |
projectId | string | No | |
taskId | string | No | |
description | string | No | What was worked on (max 500 characters) |
notes | string | No | |
isBillable | boolean | No | |
tags | string | No | Free-form labels |
breakDuration | integer | No | Unpaid break in minutes, subtracted from the duration |
update_time_entry
Update a time entry. Only the fields passed are changed. The owner or an ADMINISTRATOR/EXECUTIVE may edit; changing clock-in/out times is refused when the organization turned clock editing off (administrators exempt). Editing an APPROVED entry in an organization that requires approval sends it back to PENDING. A taskId must belong to the project the entry has after the edit (otherwise 400); changing projectId without a taskId clears the old task. Refused (403) for an entry in a locked pay period, unless the caller is an ADMINISTRATOR/EXECUTIVE, and refused for everyone when the entry falls in a FINALIZED or SIGNED timesheet period.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
entryId | string | Yes | Resource ID |
clockIn | string | No | ISO 8601 with offset |
clockOut | string | No | ISO 8601 with offset |
projectId | string | No | |
taskId | string | No | |
description | string | No | What was worked on (max 500 characters) |
notes | string | No | |
isBillable | boolean | No | |
tags | string | No | Free-form labels |
breakDuration | integer | No | Unpaid break in minutes, subtracted from the duration |
delete_time_entry
Delete a time entry (it is marked DELETED and drops out of lists and totals). The owner or an ADMINISTRATOR/EXECUTIVE may delete. Refused (403) for an entry in a locked pay period, unless the caller is an ADMINISTRATOR/EXECUTIVE, and refused for everyone when the entry falls in a FINALIZED or SIGNED timesheet period.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
entryId | string | Yes | Resource ID |
query_time_approvals
List completed time entries by approval status (default PENDING), excluding the caller's own, with each entry's rate and cost and the count per status. DEPARTMENT_HEAD (their departments), ADMINISTRATOR and EXECUTIVE only; employees are refused (403).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
status | enum: PENDING, APPROVED, REJECTED | No | Default PENDING |
limit | integer | No | Maximum entries to return (max 500) |
approve_time_entry
Approve or reject one PENDING time entry. DEPARTMENT_HEAD (entries from their departments), ADMINISTRATOR and EXECUTIVE only; nobody may decide their own entries. An entry already decided is refused (409).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
entryId | string | Yes | Resource ID |
action | enum: approve, reject | Yes | |
reason | string | No | Reason, shown to the employee (max 1000 characters) |
bulk_approve_time
Approve or reject many time entries at once. Same rules as approve_time_entry: only PENDING entries are changed, never the caller's own, and a DEPARTMENT_HEAD only inside their departments. The returned count is how many were actually changed.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
ids | string | Yes | Time entry IDs |
action | enum: approve, reject | Yes | |
reason | string | No |
get_billing_report
Billing report for APPROVED, completed time entries between two dates: totals (hours, billable hours, billable amount) and breakdowns by project, employee, day and task. ADMINISTRATOR/EXECUTIVE only. Optionally limited to one project. Pass includeEntries to also get every entry (can be large).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | First day (YYYY-MM-DD) |
endDate | string | Yes | Last day (YYYY-MM-DD) |
projectId | string | No | |
includeEntries | boolean | No | (default: false) |
query_timesheet_periods
List the organization's pay periods (weekly, biweekly, semi-monthly or monthly, as configured): the current period plus the previous five, newest first, each with periodStart and periodEnd. Pass from and to (YYYY-MM-DD) for the periods in a range instead. Use the dates with query_timesheets. Any role may call it.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | No | Range start (YYYY-MM-DD); pass with to |
to | string | No | Range end (YYYY-MM-DD); pass with from |
query_timesheets
List the timesheets for one pay period, with hours (regular, overtime, break, paid leave, holiday), pay when rates are set, and status. An EMPLOYEE sees only their own; a DEPARTMENT_HEAD their departments' active people; ADMINISTRATOR/EXECUTIVE the organization. OPEN timesheets are recomputed live from time entries; people with no time in the period are left out (except the caller). periodStart and periodEnd should be a period from query_timesheet_periods. Timesheet status flow: OPEN -> SUBMITTED -> APPROVED -> FINALIZED -> SIGNED; a rejection returns it to OPEN.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
periodStart | string | Yes | First day of the pay period (YYYY-MM-DD) |
periodEnd | string | Yes | Last day of the pay period (YYYY-MM-DD) |
submit_timesheet
Submit an OPEN timesheet for approval, which freezes its totals. The owner may submit their own; a DEPARTMENT_HEAD (their departments), ADMINISTRATOR or EXECUTIVE may submit on someone's behalf. Any other status is refused (409). Get the id from query_timesheets.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
timesheetId | string | Yes | Timesheet ID |
approve_or_reject_timesheet
Approve a SUBMITTED timesheet, or reject a SUBMITTED or APPROVED one back to OPEN for correction with an optional note to the employee. DEPARTMENT_HEAD (their departments), ADMINISTRATOR and EXECUTIVE only; nobody may approve or reject their own timesheet. A timesheet in another status is refused (409).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
timesheetId | string | Yes | Timesheet ID |
action | enum: approve, reject | Yes | |
notes | string | No | For reject: what needs correcting (max 1000 characters) |
finalize_timesheet
Finalize an APPROVED timesheet for payroll. This locks it: no one, administrators included, can then add, edit or delete time entries in that period for that person, and it cannot be reopened from here. When sign is true, or sign is omitted and the organization auto-sends timesheets for signature, a PDF is generated and sent to the employee in Documents for e-signature. DEPARTMENT_HEAD (their departments), ADMINISTRATOR and EXECUTIVE only; any status other than APPROVED is refused (409).
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
timesheetId | string | Yes | Timesheet ID |
sign | boolean | No | true sends it for e-signature, false does not; omit to follow the organization setting |
Expenses
25 tools.
Every expense tool that takes a report id also accepts the report number instead (for example EXP-2026-0001), so "approve EXP-2026-0042" works without looking the id up first. The number is resolved through the same list you could open yourself, so it only ever finds a report you can already see.
query_expenses
List expense reports, newest first by default. An EMPLOYEE sees their own; a DEPARTMENT_HEAD sees their departments; ADMINISTRATOR/EXECUTIVE see the organization. Passing another person's userId is refused (403) for an employee, and for a department head outside their departments. Date filters match reports whose departure is on/after startDate and whose return is on/before endDate.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Only reports submitted by this user |
status | enum: DRAFT, SUBMITTED, PENDING_APPROVAL, APPROVED, REJECTED, PAID, CANCELLED, pending, active | No | A status, or "pending" (SUBMITTED + PENDING_APPROVAL) or "active" (everything except PAID) |
reportType | enum: REIMBURSEMENT, COMPANY_CARD | No | Filter by report type |
search | string | No | Matches title, report number, trip purpose or description |
sort | enum: newest, oldest, amount-high, amount-low, title-az, title-za, departureDate | No | Sort order (default newest) |
startDate | string | No | Departure on or after (YYYY-MM-DD) |
endDate | string | No | Return on or before (YYYY-MM-DD) |
page | integer | No | (default: 1) |
limit | integer | No | Page size (max 50) (default: 20) |
get_expense_details
Get full details of one expense report: totals, line items (purchases), per diems, mileage entries, receipts, approval and rejection details, and payment. The submitter, their manager, the assigned approver, a DEPARTMENT_HEAD for their departments and ADMINISTRATOR/EXECUTIVE may read it; others get 403.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
expenseId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
get_expense_approvals
List expense reports waiting for approval (SUBMITTED or PENDING_APPROVAL), oldest submission first. ADMINISTRATOR/EXECUTIVE see the whole organization, a DEPARTMENT_HEAD sees their departments, and an employee with direct reports sees those reports; anyone else is refused (403). Returns pendingCount and pendingTotal.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | (default: 1) |
limit | integer | No | Page size (max 200) (default: 20) |
approve_or_reject_expense
Approve or reject an expense report that is SUBMITTED or PENDING_APPROVAL. Allowed for the assigned approver, the submitter's manager, a DEPARTMENT_HEAD for reports in their departments, and ADMINISTRATOR/EXECUTIVE. Nobody may approve or reject their own report. A rejection requires a reason, which is sent to the submitter; an approval takes optional notes.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
expenseId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
action | enum: approve, reject | Yes | Action to take |
notes | string | No | For approve: optional approver notes. For reject: the rejection reason (required). |
create_expense
Create a new DRAFT expense report for the caller. Supports REIMBURSEMENT (default) and COMPANY_CARD. COMPANY_CARD is refused (403) unless the organization enabled company cards and the caller is an administrator/executive, every role is allowed, or the caller was named as a card holder. Also refused when the plan's expense-claim limit is reached. payableToId must be an active person in the organization. Add items afterwards with add_expense_line_item, add_per_diem and add_mileage, then submit_expense.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Report title |
departureDate | string | Yes | Start/departure date (YYYY-MM-DD) |
returnDate | string | Yes | End/return date (YYYY-MM-DD) |
reportType | enum: REIMBURSEMENT, COMPANY_CARD | No | Report type (default: "REIMBURSEMENT") |
description | string | No | Report description |
tripPurpose | string | No | Trip purpose |
currency | string | No | Currency code (e.g. CAD, USD). Defaults to the organization currency. |
departmentId | string | No | Department ID |
projectId | string | No | Project ID |
payableToId | string | No | User ID to pay (for reimbursements to another user) |
submit_expense
Submit a DRAFT expense report for approval (the submitter or an ADMINISTRATOR/EXECUTIVE). Refused when the report has no items, when an item above the receipt threshold has no receipt, when the total exceeds the organization maximum, or for a company card report when the organization does not require approval for them. Reports below the auto-approve amount are approved immediately (autoApproved: true).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
expenseId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
mark_expense_paid
Mark an approved expense report as paid. Requires ADMINISTRATOR or EXECUTIVE role. Optionally records payment reference and method. Triggers QuickBooks sync if configured.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
expenseId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
paymentReference | string | No | Payment reference (e.g. cheque number, transfer ID) |
paymentMethod | string | No | Payment method: DIRECT_DEPOSIT, CHEQUE, WIRE_TRANSFER, CASH, CREDIT_CARD, OTHER |
get_expense_settings
Get the organization expense settings: which sections are enabled (purchases, per diems, travel/mileage, receipt scanning), approval rules, receipt requirements, the maximum report amount, company card configuration (and whether the caller may create company card claims), per-diem rates per meal type, mileage rates per km and per mile, tax rates and the default currency. Readable by every role.
Read-only
No parameters.
analyze_receipt
Scan a receipt (or a bank statement) with AI and return the extracted vendor, date, amounts, taxes (a separately printed liquor, city or tourism tax comes back as otherTax with its otherTaxLabel), currency and a category suggestion, plus the scan confidence and the monthly scan usage. Each scan counts against the plan's monthly receipt limit and is refused (403) once it is reached, or when receipt scanning is switched off for the organization. Pass expenseId to also attach the file to that report (the submitter, or an ADMINISTRATOR/EXECUTIVE). The extracted values are suggestions: create the line item with add_expense_line_item afterwards.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
imageBase64 | string | Yes | The file as base64 (a data: URL is accepted). JPEG, PNG, GIF, WebP or PDF, at most 10MB. |
mimeType | enum: image/jpeg, image/png, image/gif, image/webp, application/pdf | No | File type, only needed when it cannot be detected from the file itself |
fileName | string | No | File name to record (default receipt.<ext>) |
type | enum: receipt, bank_statement | No | What the file is (default: "receipt") |
expenseId | string | No | Expense report to attach the scanned file to. Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
upload_expense_receipt
Attach a receipt file (JPEG, PNG, GIF, WebP or PDF, at most 10MB) to an expense report without scanning it. The submitter may upload only to a DRAFT report; an ADMINISTRATOR/EXECUTIVE may also upload to SUBMITTED and PENDING_APPROVAL reports. Refused (403) once the plan's monthly receipt limit is reached. Link the returned receipt id to a purchase with update_line_item (receiptId).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
imageBase64 | string | Yes | The file as base64 (a data: URL is accepted). JPEG, PNG, GIF, WebP or PDF, at most 10MB. |
mimeType | enum: image/jpeg, image/png, image/gif, image/webp, application/pdf | No | File type, only needed when it cannot be detected from the file itself |
fileName | string | No | File name to record (default receipt.<ext>) |
get_receipt_quota
Get this month's receipt usage for the organization's plan: how many receipts were used, the limit and how many remain (remaining is null on an unlimited plan).
Read-only
No parameters.
delete_receipt
Delete a receipt from an expense report. The submitter may delete only from a DRAFT report; an ADMINISTRATOR/EXECUTIVE may also delete from SUBMITTED and PENDING_APPROVAL reports.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
receiptId | string | Yes | Resource ID |
add_expense_line_item
Add a purchase (line item) to an expense report. date, description, expenseType and amountBeforeTax are required; taxes (gst, pst, hst, qst, plus one named otherTax such as a liquor tax) and gratuity are separate amounts added on top. Refused when the organization switched the purchases section off. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
date | string | Yes | Date of the purchase (YYYY-MM-DD) |
description | string | Yes | What was bought |
expenseType | enum: MEALS_ENTERTAINMENT, TRANSPORTATION, ACCOMMODATION, COMMUNICATION, SUPPLIES, PARKING, TOLLS, FLIGHTS, CAR_RENTAL, TAXI_RIDESHARE, PUBLIC_TRANSIT, CONFERENCE_FEES, CLIENT_GIFTS, FUEL, AIRFARE, OFFICE_SUPPLIES, EQUIPMENT, SOFTWARE, PHONE_INTERNET, PROFESSIONAL_SERVICES, TRAINING, MEMBERSHIP, OTHER | Yes | Expense category |
amountBeforeTax | number | Yes | Amount before taxes (including otherTax) and gratuity |
vendor | string | No | Merchant / vendor name |
expenseClass | string | No | Accounting class, from the organization expenseClasses list |
currency | string | No | Currency code. Defaults to the report currency. |
exchangeRate | number | No | Rate to the organization currency (default 1) |
gst | number | No | GST amount |
pst | number | No | PST amount |
hst | number | No | HST amount |
qst | number | No | QST amount |
gratuity | number | No | Tip amount |
otherTax | number | No | One extra tax printed on its own line that is not GST/PST/HST/QST or sales tax, e.g. a liquor tax, city tax or tourism levy. Never also count it in pst. 0 removes it. |
otherTaxLabel | string | No | Name of otherTax as printed, at most 40 characters: usually "Liquor tax", "City tax" or "Tourism levy". Defaults to "Other tax" when otherTax is above 0. |
notes | string | No | |
receiptId | string | No | A receipt already uploaded to this report |
update_line_item
Update a purchase on an expense report. Only the fields passed are changed. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
itemId | string | Yes | Resource ID |
date | string | No | Date in YYYY-MM-DD format |
description | string | No | |
expenseType | enum: MEALS_ENTERTAINMENT, TRANSPORTATION, ACCOMMODATION, COMMUNICATION, SUPPLIES, PARKING, TOLLS, FLIGHTS, CAR_RENTAL, TAXI_RIDESHARE, PUBLIC_TRANSIT, CONFERENCE_FEES, CLIENT_GIFTS, FUEL, AIRFARE, OFFICE_SUPPLIES, EQUIPMENT, SOFTWARE, PHONE_INTERNET, PROFESSIONAL_SERVICES, TRAINING, MEMBERSHIP, OTHER | No | |
amountBeforeTax | number | No | |
vendor | string | No | Merchant / vendor name |
expenseClass | string | No | Accounting class, from the organization expenseClasses list |
currency | string | No | Currency code. Defaults to the report currency. |
exchangeRate | number | No | Rate to the organization currency (default 1) |
gst | number | No | GST amount |
pst | number | No | PST amount |
hst | number | No | HST amount |
qst | number | No | QST amount |
gratuity | number | No | Tip amount |
otherTax | number | No | One extra tax printed on its own line that is not GST/PST/HST/QST or sales tax, e.g. a liquor tax, city tax or tourism levy. Never also count it in pst. 0 removes it. |
otherTaxLabel | string | No | Name of otherTax as printed, at most 40 characters: usually "Liquor tax", "City tax" or "Tourism levy". Defaults to "Other tax" when otherTax is above 0. |
notes | string | No | |
receiptId | string | No | A receipt already uploaded to this report |
delete_line_item
Delete a purchase from an expense report. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
itemId | string | Yes | Resource ID |
add_per_diem
Add a per-diem (meal allowance) to an expense report. The amount is computed by the server from the organization rate for perDiemType (see get_expense_settings perDiemRates) times quantity, unless rateApplied is passed. Refused when the organization switched the per-diem section off. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
date | string | Yes | Day the allowance applies to (YYYY-MM-DD) |
perDiemType | enum: BREAKFAST, LUNCH, DINNER, BREAKFAST_LUNCH, LUNCH_DINNER, BREAKFAST_DINNER, FULL_DAY, INCIDENTALS | Yes | Which meals the allowance covers |
quantity | integer | No | Number of units claimed (default 1) |
rateApplied | number | No | Override the rate. Defaults to the organization rate for the per-diem type. |
currency | string | No | Currency code. Defaults to the report currency. |
exchangeRate | number | No | |
gst | number | No | |
pst | number | No | |
mealProvided | boolean | No | The meal was provided by someone else: recorded, but pays 0 |
notes | string | No |
update_per_diem
Update a per-diem on an expense report. Only the fields passed are changed; changing perDiemType without rateApplied re-applies the organization rate for the new type. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
itemId | string | Yes | Resource ID |
date | string | No | Date in YYYY-MM-DD format |
perDiemType | enum: BREAKFAST, LUNCH, DINNER, BREAKFAST_LUNCH, LUNCH_DINNER, BREAKFAST_DINNER, FULL_DAY, INCIDENTALS | No | |
quantity | integer | No | Number of units claimed (default 1) |
rateApplied | number | No | Override the rate. Defaults to the organization rate for the per-diem type. |
currency | string | No | Currency code. Defaults to the report currency. |
exchangeRate | number | No | |
gst | number | No | |
pst | number | No | |
mealProvided | boolean | No | The meal was provided by someone else: recorded, but pays 0 |
notes | string | No |
delete_per_diem
Delete a per-diem from an expense report. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
itemId | string | Yes | Resource ID |
add_mileage
Add a mileage (travel) entry to an expense report. date, description and distance are required; the amount is distance times the organization rate for the unit unless ratePerUnit is passed. Refused when the organization switched the travel section off. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
date | string | Yes | Date of the trip (YYYY-MM-DD) |
description | string | Yes | Purpose of the trip |
distance | number | Yes | Total distance driven, in the unit |
startLocation | string | No | Where the trip started |
endLocation | string | No | Where the trip ended |
roundTrip | boolean | No | Marks the trip as a round trip. It does not double the distance: pass the full distance. |
unit | enum: KILOMETERS, MILES | No | KILOMETERS or MILES. Defaults to the organization unit. |
ratePerUnit | number | No | Override the rate. Defaults to the organization rate per km or per mile. |
currency | string | No | Currency code. Defaults to the report currency. |
exchangeRate | number | No | |
gst | number | No | |
notes | string | No |
update_mileage
Update a mileage entry on an expense report. Only the fields passed are changed; changing unit without ratePerUnit re-applies the organization rate for the new unit. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
itemId | string | Yes | Resource ID |
date | string | No | Date in YYYY-MM-DD format |
description | string | No | |
distance | number | No | |
startLocation | string | No | Where the trip started |
endLocation | string | No | Where the trip ended |
roundTrip | boolean | No | Marks the trip as a round trip. It does not double the distance: pass the full distance. |
unit | enum: KILOMETERS, MILES | No | KILOMETERS or MILES. Defaults to the organization unit. |
ratePerUnit | number | No | Override the rate. Defaults to the organization rate per km or per mile. |
currency | string | No | Currency code. Defaults to the report currency. |
exchangeRate | number | No | |
gst | number | No | |
notes | string | No |
delete_mileage
Delete a mileage entry from an expense report. The submitter may change items only while the report is DRAFT; an ADMINISTRATOR/EXECUTIVE may also change SUBMITTED and PENDING_APPROVAL reports. Report totals are recalculated by the server.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
itemId | string | Yes | Resource ID |
cancel_expense
Cancel an expense report that is SUBMITTED, PENDING_APPROVAL or APPROVED (not yet paid); its status becomes CANCELLED and the record is kept. The submitter or an ADMINISTRATOR/EXECUTIVE may cancel. A DRAFT is removed with delete_expense instead.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
delete_expense
Permanently delete an expense report and its items. Only two cases are allowed: a DRAFT (by the submitter or an ADMINISTRATOR/EXECUTIVE) or a PAID report (EXECUTIVE only). Any other status is refused; use cancel_expense for submitted or approved reports.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
reportId | string | Yes | Expense report id (the id from query_expenses), or its report number such as EXP-2026-0001. |
bulk_mark_expenses_paid
Mark up to 50 APPROVED expense reports as paid in one call (for example after a payroll run). ADMINISTRATOR/EXECUTIVE only. All-or-nothing: if any id is not APPROVED, not found, or in another organization, nothing is marked. The payment date is recorded as now.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
expenseIds | string | Yes | Expense report ids (the id from query_expenses) or report numbers such as EXP-2026-0001, at most 50 |
paymentReference | string | No | Cheque number, transfer ID, payroll run, ... |
paymentMethod | string | No | Payment method, e.g. DIRECT_DEPOSIT, CHEQUE, WIRE_TRANSFER, CASH, CREDIT_CARD, OTHER |
update_expense_settings
Update organization-wide expense settings. ADMINISTRATOR/EXECUTIVE only. Only the fields passed are changed. A rate change is recorded in the rate history (with rateChangeReason) and applies to new items only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Turn the expenses module on or off |
enablePurchases | boolean | No | |
enablePerDiems | boolean | No | |
enableTravel | boolean | No | |
enableReceiptScanning | boolean | No | |
defaultCurrency | string | No | |
mileageUnit | enum: KILOMETERS, MILES | No | |
mileageRatePerKm | number | No | |
mileageRatePerMile | number | No | |
breakfastRate | number | No | |
lunchRate | number | No | |
dinnerRate | number | No | |
breakfastLunchRate | number | No | |
lunchDinnerRate | number | No | |
breakfastDinnerRate | number | No | |
fullDayRate | number | No | |
incidentalsRate | number | No | |
gstRate | number | No | Percent |
pstRate | number | No | Percent |
hstRate | number | No | Percent |
qstRate | number | No | Percent |
rateChangeReason | string | No | Recorded with any rate change |
requireReceipts | boolean | No | |
receiptThreshold | number | No | Receipts are required above this amount |
autoApproveBelow | number or null | No | Auto-approve reports below this total; null turns it off |
maxReportAmount | number or null | No | Largest report total allowed; null removes the cap |
maxDaysToSubmit | integer | No | |
requireApproval | boolean | No | |
requireSecondApproval | boolean | No | |
secondApprovalThreshold | number or null | No | |
enableCompanyCard | boolean | No | |
companyCardAllRoles | boolean | No | |
companyCardRequiresApproval | boolean | No |
Users
21 tools.
get_team_members
List the people in the organization the caller may see, with role, department, manager and (for administrators, executives and department heads) employment start date. By default only active people are returned; set activeOnly=false to include deactivated and offboarded people as well. Department heads only see their own department scope. Use this to "list active users"; use search_directory to find someone by name.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
activeOnly | boolean | No | Only active people (default true). false also returns deactivated / offboarded people. (default: true) |
get_user_profile
Get detailed profile for a specific user by ID.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User ID |
get_departments
List the departments in the organization with code, color, head and member count. Inactive departments are hidden unless includeInactive is true.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
includeInactive | boolean | No | Also list inactive departments (default: false) |
search_directory
Search the people directory by first name, last name or email (job title and employee number are not searched). Returns a page of matching people with department and role, plus total/page/pageSize. Uses the directory view, so a department head or employee sees as much of the organization as the directory access settings allow.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search text — matches first name, last name or email (case-insensitive) |
departmentId | string | No | Filter to a specific department |
includeInactive | boolean | No | Include deactivated / offboarded people (default: false) |
page | integer | No | Page number (1-indexed) (default: 1) |
pageSize | integer | No | Page size (max 200) (default: 50) |
get_org_chart
Get the organization reporting hierarchy as a tree of active people. Each node lists a person, their job title, department and direct reports. Uses the directory view, so how much of the organization a department head or employee sees follows the organization's directory access settings. Use this for "who reports to whom?" questions.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
rootUserId | string | No | User ID to root the tree at — defaults to every top-level person |
includeInactive | boolean | No | Include deactivated / offboarded people in the tree (default: false) |
update_user_profile
Update an employee profile: basic info, contact details, address, social links, employment and emergency contact. Only the fields you provide are changed. Anyone may edit their own personal and contact fields; employment fields (jobTitle, employeeId, departmentId, reportsToId, employmentType, employmentStartDate, probationPeriodMonths, payrollId) need ADMINISTRATOR or EXECUTIVE; a DEPARTMENT_HEAD may edit people in their own department scope. Role changes go through change_role, deactivation through offboard_user. Refusals: 403 for insufficient role, 400 MANAGER_NOT_FOUND when reportsToId is not an active person in the organization, 400 DEPARTMENT_NOT_FOUND.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
firstName | string | No | First name |
lastName | string | No | Last name |
middleName | string | No | Middle name |
preferredName | string | No | Preferred / display name |
jobTitle | string | No | Job title (admin/exec only) |
employeeId | string | No | Employee number (admin/exec only) |
phoneMobile | string | No | Mobile phone |
phoneLandline | string | No | Work / landline phone |
phoneHome | string | No | Home phone |
phoneExtension | string | No | Phone extension |
homeEmail | string | No | Personal/home email |
addressLine1 | string | No | |
addressLine2 | string | No | |
city | string | No | |
state | string | No | State / province |
postalCode | string | No | |
country | string | No | |
timezone | string | No | Personal IANA timezone override (e.g. America/Toronto); empty string inherits the organization timezone |
dateOfBirth | string | No | Date of birth (YYYY-MM-DD) |
gender | enum: MALE, FEMALE, OTHER, PREFER_NOT_TO_SAY | No | |
maritalStatus | enum: SINGLE, MARRIED, DIVORCED, WIDOWED, DOMESTIC_PARTNERSHIP, PREFER_NOT_TO_SAY | No | |
nationality | string | No | |
shirtSize | enum: XS, S, M, L, XL, XXL, XXXL | No | |
linkedinUrl | string | No | LinkedIn profile URL |
githubUrl | string | No | GitHub profile URL |
twitterUsername | string | No | X / Twitter handle or URL |
facebookUrl | string | No | Facebook profile URL |
employmentStartDate | string | No | Employment start / hire date (YYYY-MM-DD) |
reportsToId | string or null | No | Manager's user ID (must be an active person); null removes the manager |
departmentId | string | No | Department ID |
division | string | No | Division name (free text) |
workLocation | string | No | |
employmentType | enum: FULLTIME, PARTTIME, CONTRACT, INTERN, TEMPORARY, SEASONAL | No | Employment status |
probationPeriodMonths | enum: 3, 6 or null | No | Probation length in months (3 or 6), null for none |
payrollId | string | No | |
emergencyContactName | string | No | |
emergencyContactRelationship | string | No | |
emergencyContactPhone | string | No | Primary phone |
emergencyContactPhoneSecondary | string | No | Secondary phone |
emergencyContactEmail | string | No |
create_user
Create a new employee account. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE may create an executive. A welcome email with an account-setup link is always sent. No onboarding is started automatically — that is a separate step. Manager, employee number and other profile fields are set afterwards with update_user_profile. Refusals: 400 EMAIL_TAKEN (email already used anywhere), 400 DEPARTMENT_NOT_FOUND, 403 SEAT_LIMIT when the plan has no free seat.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
firstName | string | Yes | First name |
lastName | string | Yes | Last name |
email | string | Yes | Work email — used for login |
role | enum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVE | No | Role (default EMPLOYEE) |
jobTitle | string | No | Job title |
departmentId | string | No | Department ID |
employmentStartDate | string | No | Employment start / hire date (YYYY-MM-DD) |
probationPeriodMonths | enum: 3, 6 | No | Probation length in months (3 or 6); omit for none |
offboard_preview
Preview what will happen if a user is offboarded. Returns counts of leaves, time entries, expenses, document assignments, direct reports, department head assignments, 1:1 series, onboarding instances, projects, tasks, benefit enrollments, and future shifts that will be cleaned up. It also lists the departments the person heads and candidate replacement heads. ADMINISTRATOR or EXECUTIVE only. Always run this before offboard_user so you can show the operator a 'what will happen' summary.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
offboard_user
Offboard (deactivate) an employee with structured cleanup: cancels future leaves and shifts, reassigns department head duties, archives 1:1 series, closes onboarding and so on. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE may offboard an executive, you cannot offboard yourself or the last active executive, and an already inactive person is refused. Run offboard_preview FIRST and confirm with the operator. If the person heads any departments, replacementHeads must have exactly one entry per department they head (replacementHeadId null leaves it vacant). Writes an OFFBOARD audit log entry.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
employmentEndDate | string | Yes | Last day of employment (YYYY-MM-DD) |
terminationCode | enum: VOLUNTARY_RESIGNATION, INVOLUNTARY, LAYOFF, RETIREMENT, END_OF_CONTRACT, MUTUAL_AGREEMENT, OTHER | Yes | Reason the employment ended |
terminationNoticeDate | string | No | Date notice was given (YYYY-MM-DD) |
roeCompletedDate | string | No | Date the ROE / separation paperwork was completed (YYYY-MM-DD) |
notes | string | No | Internal notes about the offboarding |
replacementHeads | object | No | One entry per department the person heads (see offboard_preview) |
replacementHeads[].departmentId | string | Yes | A department this person heads |
replacementHeads[].replacementHeadId | string or null | Yes | Active person who takes over as head, or null to leave it vacant |
reactivate_user
Restore login access for a previously offboarded user. ADMINISTRATOR or EXECUTIVE only (an executive account needs an EXECUTIVE). Refused when the person is already active or the plan has no free seat. Does NOT undo the offboarding cleanup (cancelled leaves, archived 1:1s, etc).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
change_user_role
Change a user role to EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, or EXECUTIVE. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE may grant EXECUTIVE or edit an executive account, and nobody can change their own role. Writes an audit log entry with the previous and new role.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
role | enum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVE | Yes | User role |
create_department
Create a new department. ADMINISTRATOR or EXECUTIVE only. A code is generated from the name when omitted (and made unique). The head must be an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD in the organization (400 otherwise); one person may head several departments and keeps their own department.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Department name |
code | string | No | Short code (upper-cased; generated when omitted) |
description | string | No | Description |
color | string | No | Hex color (#RRGGBB), default #3b82f6 |
headOfDepartmentId | string | No | User ID of the department head |
update_department
Update a department. Only the fields you provide are changed. ADMINISTRATOR or EXECUTIVE may change anything; the DEPARTMENT_HEAD who leads it may change only name, description and color. headOfDepartmentId null removes the head. The head must be an active ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD in the organization (400 otherwise); one person may head several departments and keeps their own department. A duplicate code is refused with 400.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
departmentId | string | Yes | Resource ID |
name | string | No | |
code | string | No | |
description | string | No | |
color | string | No | |
isActive | boolean | No | false hides the department from lists |
headOfDepartmentId | string or null | No | User ID of the new department head, or null to clear it |
delete_department
Permanently delete a department. ADMINISTRATOR or EXECUTIVE only. Refused with 400 while any person is still assigned to it — reassign them first.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
departmentId | string | Yes | Resource ID |
query_teams
List every team in the organization (sorted by name) with its department and member count. Any signed-in person may call it.
Read-only
No parameters.
create_team
Create a new team. ADMINISTRATOR or EXECUTIVE only. The name must be unique in the organization (409 NAME_TAKEN); a departmentId must belong to the organization (400 DEPARTMENT_NOT_FOUND).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Team name |
description | string | No | |
departmentId | string | No | Department the team belongs to |
update_team
Update a team. ADMINISTRATOR or EXECUTIVE only. Only the fields you provide are changed; departmentId null detaches it from its department. A duplicate name is refused with 409.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
teamId | string | Yes | Resource ID |
name | string | No | |
description | string or null | No | New description, or null to clear it |
departmentId | string or null | No | Department ID, or null to clear it |
delete_team
Permanently delete a team and its memberships. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
teamId | string | Yes | Resource ID |
query_team_members
List the members of a team with their team role and join date. Any signed-in person may call it.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
teamId | string | Yes | Resource ID |
add_team_member
Add an active person to a team. ADMINISTRATOR or EXECUTIVE only. A deactivated person or one outside the organization is refused (404); an existing member is refused with 409.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
teamId | string | Yes | Resource ID |
userId | string | Yes | User ID to add |
role | string | No | Role within the team (default MEMBER) |
remove_team_member
Remove a person from a team. ADMINISTRATOR or EXECUTIVE only. Looks up the membership by user ID, then deletes it.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
teamId | string | Yes | Resource ID |
userId | string | Yes | User ID to remove |
Schedules
11 tools.
query_schedules
List scheduled shifts for a date range (dates and times in the organization's timezone), with the number of leave-days and the public holidays in the range and which weeks are published. ADMINISTRATOR and EXECUTIVE see everyone; a DEPARTMENT_HEAD sees the departments they head or manage; employees see their own shifts plus whatever the organization's schedule-visibility settings allow, and only published weeks unless default schedules are auto-generated. Naming a userId outside your view is refused with 403. The date shown for each shift is what update_shift expects as shiftDate.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | No | Start date (YYYY-MM-DD, defaults to today) |
endDate | string | No | End date (YYYY-MM-DD, defaults to +7 days) |
userId | string | No | Filter by user ID |
departmentId | string | No | Filter by department ID |
create_shift
Create a scheduled shift on one day, with times in the organization's timezone. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD. Omit userId to create an open shift anyone eligible can claim. The assigned person must be an active member of the organization (a deactivated or unknown person is refused with "Invalid user"). A department head may only assign people in, or file open shifts to, the departments they head or manage.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
date | string | Yes | Shift date (YYYY-MM-DD) |
startTime | string | Yes | Start time (HH:MM, e.g. "09:00") |
endTime | string | Yes | End time (HH:MM, e.g. "17:00") |
userId | string | No | User ID (omit for open shift) |
departmentId | string | No | Department the shift belongs to (useful for open shifts) |
shiftType | string | No | Shift type: REGULAR, MORNING, AFTERNOON, NIGHT, CUSTOM (default: "REGULAR") |
breakDuration | number | No | Break duration in minutes (default: 30) |
notes | string | No | Notes |
confirmPublished | boolean | No | Set to true only after the user confirmed changing a published week. Without it, a shift in a published week is refused |
The week is checked first: a shift in a week that is already published (visible to employees) is refused until the user confirms.
create_shifts
Create many scheduled shifts in ONE call: the same times for each listed person on each listed day (e.g. a whole team, Monday to Friday). Use this instead of repeated create_shift calls whenever more than a few shifts are needed. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD; a department head may only schedule people in the departments they head or manage. Every person must be an active member of the organization. Times are in the organization's timezone. A person who already has a shift on a day is skipped for that day. At most 500 shifts per call. It checks each week first and returns its status (Draft or Published) and how many shifts were already there; a PUBLISHED week is refused unless confirmPublished is true, which you set only after the user agreed.
It looks at each week first and returns its status (Draft or Published) and how many shifts were already there. A person who already has a shift on a day is left as they are unless existing is "update", which changes that shift to the new times. A published week is refused unless confirmPublished is true.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userIds | string | Yes | People to schedule (1–500) |
dates | string | Yes | Days to schedule (YYYY-MM-DD, 1–31) |
startTime | string | Yes | Start time, HH:MM 24-hour (e.g. "08:30") |
endTime | string | Yes | End time, HH:MM 24-hour (e.g. "16:30"); must be after the start |
breakDuration | integer | No | Unpaid break in minutes (default: 30) |
shiftType | string | No | REGULAR, MORNING, AFTERNOON, NIGHT, CUSTOM (default: "REGULAR") |
notes | string | No | Notes added to every shift |
existing | string | No | "skip" (default) leaves existing shifts as they are; "update" changes them to these times. Use "update" only after the user agreed |
confirmPublished | boolean | No | Set to true only after the user confirmed changing a published week |
Returns how many shifts were created, updated, left as they were and skipped, plus each week's status.
publish_schedule
Publish one or more consecutive weeks for the whole organization (publication is org-wide, not per department), making their shifts visible to employees. ADMINISTRATOR or EXECUTIVE only. Optionally emails each scheduled employee; the result says how many were notified.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
weekStart | string | Yes | First day of the first week to publish (YYYY-MM-DD) |
numberOfWeeks | integer | No | Number of weeks to publish (1-4) (default: 1) |
sendNotification | boolean | No | Send email notification to employees (default: true) |
update_shift
Change an existing shift. Only the fields you provide change; the rest are kept. Times are in the organization's timezone. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD; a department head only for shifts of people (or open shifts) in the departments they head or manage. Pass userId to reassign the shift (it must be an active person; a department head may only assign within their departments) or null to turn it into an open shift. shiftDate is the date the shift is on now, as query_schedules shows it; it is used to look the shift up.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
shiftId | string | Yes | Resource ID |
shiftDate | string | Yes | The date the shift is currently on (YYYY-MM-DD) |
date | string | No | Move the shift to this date (YYYY-MM-DD) |
startTime | string | No | New start time (HH:mm) |
endTime | string | No | New end time (HH:mm) |
shiftType | string | No | REGULAR, MORNING, AFTERNOON, NIGHT or CUSTOM |
breakDuration | integer | No | Break in minutes |
notes | string | No | |
userId | string or null | No | Reassign to this person, or null to make it an open shift |
delete_shift
Permanently delete one shift. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD; a department head only for shifts in the departments they head or manage.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
shiftId | string | Yes | Resource ID |
claim_shift
Claim an open (unassigned) shift for yourself. Any role may claim. Refused with 409 when someone already has it, once the shift has started, or when its week has not been published yet (an unpublished week is still a draft), and with 403 when the shift is restricted to a department you are not in.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
shiftId | string | Yes | Resource ID |
copy_week
Copy one week's assigned shifts onto the following week(s), matched by weekday, on business days only. Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD (a department head copies only the departments they head or manage). Open shifts and shifts of people who are no longer active are not copied. By default a person who already has a shift on a target day is skipped. Pass employeeIds to copy only those people (a department head only people in their departments, otherwise 403); an empty employeeIds list copies nothing. With sendNotification, only the people who actually got new shifts are emailed. Returns how many shifts were created and skipped.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
sourceWeekStart | string | Yes | First day of the week to copy (YYYY-MM-DD) |
targetWeekStart | string | Yes | First day of the first destination week (YYYY-MM-DD) |
numberOfWeeks | integer | No | How many consecutive weeks to fill (1-4) (default: 1) |
departmentId | string | No | Only copy shifts of people in this department |
employeeIds | array of string | No | Only copy shifts of these people (user ids, up to 500). Takes precedence over departmentId. An empty list copies nothing. |
skipConflicts | boolean | No | Skip a person/day that already has a shift (default: true) |
sendNotification | boolean | No | Email the affected employees their new schedule (default: false) |
clear_week
Permanently delete every shift in the organization for one week (weekStart and the six days after it), across all departments. Cannot be undone. ADMINISTRATOR or EXECUTIVE only. Refused when the week is published; unpublish it first.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
weekStart | string | Yes | First day of the week (YYYY-MM-DD), as shown in the schedule |
unpublish_schedule
Move a published week back to draft for the whole organization (publication is org-wide, not per department), hiding it from employees again. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
weekStart | string | Yes | First day of the week (YYYY-MM-DD), as shown in the schedule |
submit_schedule_for_review
Send a draft week to the organization's administrators and executives for review before they publish it. DEPARTMENT_HEAD only (others get 403); departmentId, when given, must be one the head heads or manages.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
weekStart | string | Yes | First day of the week (YYYY-MM-DD), as shown in the schedule |
departmentId | string | No | Department whose schedule is submitted (defaults to your own) |
email_schedule
Email each scheduled employee their shifts for a date range (by default one week from weekStart). Requires ADMINISTRATOR, EXECUTIVE or DEPARTMENT_HEAD. Pass departmentId to email only that department's active members.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
weekStart | string | Yes | First day of the week (YYYY-MM-DD), as shown in the schedule |
endDate | string | No | Last day to include (YYYY-MM-DD, defaults to weekStart + 6 days) |
departmentId | string | No | Only email people in this department |
Projects
15 tools.
list_projects
List projects, newest first. ADMINISTRATOR/EXECUTIVE see every project (and may filter by department); a DEPARTMENT_HEAD sees their departments' projects plus organization-wide ones; an EMPLOYEE sees their department's projects plus organization-wide ones. Hourly rate and budget amount are returned only to DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE. includeStats adds tracked hours and budget used.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
status | enum: ACTIVE, ON_HOLD, COMPLETED, CANCELLED, ARCHIVED | No | Filter by status |
departmentId | string | No | Only this department's projects (ADMINISTRATOR/EXECUTIVE only; ignored otherwise) |
includeStats | boolean | No | Include tracked hours and budget used (default: false) |
get_project
Get one project with its client, every task and issue (status, type, priority, due date, assignee), and time stats. Visible to anyone who can see the project in list_projects; hourly rate, budget amount and billed amount are returned only to DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project ID |
create_task
Create a billable work item (task) in a project that people can track time against; it starts ACTIVE. Pass parentTaskId to make it a subtask. An EMPLOYEE may only add tasks to their department's projects or organization-wide ones. For a tracked issue with type, priority, due date and assignee use create_issue.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project ID |
name | string | Yes | Task name |
description | string | No | Task description |
budgetHours | number | No | Budget hours for this task |
isBillable | boolean | No | Whether the task is billable (default: true) |
parentTaskId | string | No | Make this a subtask of another task in the same project |
query_project_tasks
List a project's top-level tasks with their subtasks and the time tracked against each (hours, entry count; cost only for DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE). This list has no filters; to filter by status, type, priority, assignee or text use query_project_issues.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
update_task
Update a project task or issue: change its status (for example mark it DONE), reassign it, set the due date or priority, rename it. Only the fields passed are changed. Anyone who can see the project may change only the status; any other change needs a DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE, or the item's assignee or reporter. A new assignee must be an active person in the organization (400 Invalid assignee otherwise).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
taskId | string | Yes | Resource ID |
name | string | No | Title |
description | string | No | |
status | enum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLED | No | Board columns are TODO, IN_PROGRESS, IN_REVIEW, DONE |
type | enum: TASK, BUG, FEATURE, STORY, EPIC | No | |
priority | enum: LOW, MEDIUM, HIGH, URGENT, CRITICAL | No | |
labels | string | No | Replaces the whole label list |
dueDate | string or null | No | Due date (YYYY-MM-DD); null clears it |
estimatedHours | number or null | No | |
budgetHours | number or null | No | |
isBillable | boolean | No | |
assigneeId | string or null | No | Active person to assign; null unassigns |
parentTaskId | string or null | No | Parent task in the same project; null detaches |
delete_task
Permanently delete a project task. DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
taskId | string | Yes | Resource ID |
get_project_board
Get the Kanban board of a project: items grouped into the TODO, IN_PROGRESS, IN_REVIEW and DONE columns. Items in other statuses (ACTIVE, COMPLETED, CANCELLED) are not on the board.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
add_project_comment
Post a comment on a task or issue in a project (comments belong to a task, not to the project itself).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
taskId | string | Yes | The task or issue to comment on |
content | string | Yes | Comment text |
query_project_comments
List the comments on one task or issue in a project, oldest first.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
taskId | string | Yes | The task or issue whose comments to list |
query_project_issues
List a project's tasks and issues (including subtasks) in board order, filtered by status, type, priority, assignee or a name search.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
status | enum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLED | No | |
type | enum: TASK, BUG, FEATURE, STORY, EPIC | No | |
priority | enum: LOW, MEDIUM, HIGH, URGENT, CRITICAL | No | |
assigneeId | string | No | |
search | string | No | Matches the name |
create_issue
Create a tracked issue in a project (task, bug, feature, story or epic) with priority, due date, labels and an optional assignee; it starts in TODO and the caller is the reporter. An EMPLOYEE may only add issues to their department's projects or organization-wide ones. The assignee must be an active person.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
name | string | Yes | Title |
description | string | No | |
type | enum: TASK, BUG, FEATURE, STORY, EPIC | No | Default TASK |
priority | enum: LOW, MEDIUM, HIGH, URGENT, CRITICAL | No | Default MEDIUM |
status | enum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLED | No | Default TODO |
labels | string | No | |
dueDate | string | No | Due date (YYYY-MM-DD) |
estimatedHours | number | No | |
assigneeId | string | No | |
parentTaskId | string | No | Parent task in the same project |
update_issue
Update a project issue. Only the fields passed are changed. Anyone who can see the project may change only the status; any other change needs a DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE, or the item's assignee or reporter. A new assignee must be an active person in the organization (400 Invalid assignee otherwise).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
issueId | string | Yes | Resource ID |
name | string | No | Title |
description | string | No | |
status | enum: TODO, IN_PROGRESS, IN_REVIEW, DONE, ACTIVE, COMPLETED, CANCELLED | No | Board columns are TODO, IN_PROGRESS, IN_REVIEW, DONE |
type | enum: TASK, BUG, FEATURE, STORY, EPIC | No | |
priority | enum: LOW, MEDIUM, HIGH, URGENT, CRITICAL | No | |
labels | string | No | Replaces the whole label list |
dueDate | string or null | No | Due date (YYYY-MM-DD); null clears it |
estimatedHours | number or null | No | |
budgetHours | number or null | No | |
isBillable | boolean | No | |
assigneeId | string or null | No | Active person to assign; null unassigns |
parentTaskId | string or null | No | Parent task in the same project; null detaches |
delete_issue
Permanently delete a project issue. DEPARTMENT_HEAD, ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
issueId | string | Yes | Resource ID |
update_project
Update a project. Only the fields passed are changed. ADMINISTRATOR/EXECUTIVE may edit any project; a DEPARTMENT_HEAD only projects in their departments (not organization-wide ones). Only ADMINISTRATOR/EXECUTIVE can move a project to another department. The code must be unique in the organization; the manager must be an active person.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
name | string | No | |
code | string | No | |
description | string or null | No | |
status | enum: ACTIVE, ON_HOLD, COMPLETED, CANCELLED, ARCHIVED | No | |
priority | enum: LOW, MEDIUM, HIGH, URGENT | No | |
color | string | No | |
isBillable | boolean | No | |
hourlyRate | number or null | No | |
budgetHours | number or null | No | |
budgetAmount | number or null | No | |
managerId | string or null | No | Project manager; null clears |
clientId | string or null | No | A client from query_clients; null clears |
departmentId | string or null | No | ADMINISTRATOR/EXECUTIVE only; null makes it organization-wide |
startDate | string or null | No | Date in YYYY-MM-DD format |
endDate | string or null | No | Date in YYYY-MM-DD format |
delete_project
Permanently delete a project with all its tasks, issues, comments and members. Time entries, shifts and expense reports that referenced it are kept but lose the link. ADMINISTRATOR/EXECUTIVE only. Cannot be undone.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Resource ID |
Organization
17 tools.
get_org_info
Get organization settings: name, timezone, currency, leave allowances, fiscal year, etc.
Read-only
No parameters.
get_public_holidays
List public holidays for a year (default: the caller's current year). Without userId, returns the organization's holidays. With userId, returns the holidays that apply to that person — their personal holiday country and their add/exclude overrides — when the caller may see them (the person, administrators/executives, or their department head); otherwise the organization's holidays are returned.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
year | integer | No | Calendar year |
userId | string | No | Resolve the holidays that apply to this person |
get_dashboard_stats
Get organization-level stats: total users, departments, leave types, leaves. Requires EXECUTIVE role.
Read-only
No parameters.
get_notifications
Get the authenticated user's notifications. Supports filtering by read status.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | enum: all, unread, read | No | Filter: all, unread, or read (default: "all") |
page | integer | No | (default: 1) |
limit | integer | No | Page size (max 100) (default: 20) |
get_directory_settings
Get the organization's people directory and org chart settings: whether each is enabled, who may view and export them (orgChartAccess, orgChartExportAccess, directoryAccess), and which profile fields the directory shows. Explains why search_directory or get_org_chart return less of the organization for some roles. Any signed-in person may read it.
Read-only
No parameters.
add_public_holiday
Add a holiday LOCATION to the organization: imports every public holiday for a country (optionally one state/province) for the given year from the public holiday calendar. It does not create a single custom holiday — for a one-off day for one person use add_user_holiday_override. ADMINISTRATOR or EXECUTIVE only. Refused with 400 when that country/subdivision is already added, 404 when no holidays are found for it. Use query_holiday_countries / query_holiday_subdivisions for valid codes.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
country | string | Yes | ISO 3166-1 alpha-2 country code (e.g. "CA") |
subdivision | string | No | ISO 3166-2 subdivision code as listed by query_holiday_subdivisions (e.g. "CA-ON") |
year | integer | Yes | Year to import (2020-2050) |
delete_public_holiday
Remove a holiday LOCATION: deletes EVERY public holiday the organization has for the same country as the given holiday (all years and all subdivisions of that country), not just the one day. Cannot be undone. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
holidayId | string | Yes | ID of any holiday belonging to the country to remove |
query_holiday_countries
List the countries available for importing public holidays (code and name).
Read-only
No parameters.
query_holiday_subdivisions
List the subdivisions (states/provinces) that have their own public holidays in a country.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
countryCode | string | Yes | ISO country code (e.g. "CA", "US") |
query_user_holiday_overrides
List one person's holiday overrides: EXCLUDE (an organization holiday they do not observe) and ADD (an extra personal holiday). Readable by the person, administrators/executives, and their department head; anyone else is refused with 403.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_user_holiday_override
Add a holiday override for one person. type EXCLUDE removes an organization holiday for them (publicHolidayId required, from get_public_holidays); type ADD gives them an extra personal holiday (name and date required). ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
type | enum: EXCLUDE, ADD | Yes | |
publicHolidayId | string | No | Organization holiday to exclude (EXCLUDE only) |
name | string | No | Holiday name (ADD only) |
date | string | No | Holiday date YYYY-MM-DD (ADD only) |
isRecurring | boolean | No | Repeats every year (default true) (default: true) |
isHalfDay | boolean | No | (default: false) |
query_asset_categories
List the active asset categories defined for the organization (Laptop, Phone, Badge, etc.) with how many assets use each. Used by add_asset and update_asset.
Read-only
No parameters.
create_asset_category
Create a new asset category. ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Category name (e.g. "Laptop") |
description | string | No |
delete_asset_category
Deactivate an asset category so it is no longer offered; existing assets keep it. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
categoryId | string | Yes | Resource ID |
query_certification_types
List the active certification types defined for the organization (AWS Solutions Architect, PMP, etc.) with how many certifications use each. Used by add_certification.
Read-only
No parameters.
create_certification_type
Create a new certification type. ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Certification name (e.g. "AWS Solutions Architect Associate") |
description | string | No | Description (e.g. issuing body, validity) |
delete_certification_type
Deactivate a certification type so it is no longer offered; existing certifications keep it. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
typeId | string | Yes | Resource ID |
Reports
2 tools.
generate_leave_report
Leave report: leave requests whose start date falls in a range, newest first, with counts by status (approved, pending, rejected) and total days across every matching request. Paged (up to 500 per page). ADMINISTRATOR and EXECUTIVE see the whole organization; a DEPARTMENT_HEAD sees only the departments they head or manage (a departmentId outside that is refused with 403). Employees get 403.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | No | Earliest start date (YYYY-MM-DD) |
endDate | string | No | Latest start date (YYYY-MM-DD) |
departmentId | string | No | Filter by department |
userId | string | No | Filter by person |
leaveTypeId | string | No | Filter by leave type |
status | enum: PENDING, APPROVED, REJECTED, CANCELLED, WITHDRAWN | No | Filter by status (all statuses when omitted) |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Rows per page (max 500) (default: 50) |
generate_timesheet_report
Time-tracking report over clocked time entries. reportType: summary (totals, billable share, overtime, per-weekday hours), by_employee, by_project, by_department, overtime or attendance. Durations are in MINUTES (the summary fields named totalHours, billableHours, overtimeHours and avgHoursPerDay hold minutes). Give startDate and endDate for a custom range; otherwise range picks a preset (default: this week). ADMINISTRATOR and EXECUTIVE see the whole organization and cost figures; a DEPARTMENT_HEAD sees only the departments they head or manage and no costs (a departmentId outside that is refused with 403). Employees get 403. Refused when time tracking is switched off for the organization.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
reportType | enum: summary, by_employee, by_project, by_department, overtime, attendance | No | Which report to build (default: "summary") |
startDate | string | No | Report start date (YYYY-MM-DD); needs endDate too |
endDate | string | No | Report end date (YYYY-MM-DD); needs startDate too |
range | enum: today, week, month, quarter, year | No | Preset range, used when startDate/endDate are not both given (default week) |
userId | string | No | Filter by person |
departmentId | string | No | Filter by department |
HR
73 tools.
query_employee_notes
List notes attached to an employee that the caller may read. Each note carries visibleToRoles, the roles allowed to read it (EMPLOYEE there means the employee the note is about). ADMINISTRATOR, EXECUTIVE, a DEPARTMENT_HEAD for their departments, and the employee themselves see the notes shared with their role; anyone else gets an empty list.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_employee_note
Add a note to an employee profile. An EMPLOYEE may only add notes to their own profile, and their notes are always visible to every role. ADMINISTRATOR and EXECUTIVE may add notes to anyone; a DEPARTMENT_HEAD only to people in their departments, and must include ADMINISTRATOR in visibleToRoles. Everyone other than an EMPLOYEE must pass visibleToRoles; include EMPLOYEE only if the employee should read it. The employee and admins may be notified.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
content | string | Yes | The note text (max 5000 characters) |
visibleToRoles | array of enum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVE | No | Roles that may read the note. EMPLOYEE means the employee the note is about. A DEPARTMENT_HEAD must include ADMINISTRATOR. |
delete_employee_note
Permanently delete a note. Only its author, an ADMINISTRATOR or an EXECUTIVE may. Cannot be undone.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
noteId | string | Yes | Resource ID |
query_education
List education records (institution, degree, major, GPA, dates) for one person. An HR record: readable by the person themselves, ADMINISTRATOR and EXECUTIVE for anyone in the organization, and a DEPARTMENT_HEAD for people in the departments they head; anyone else is refused with 403 (Access denied).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_education_entry
Add an education record for a user. institution is required. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
institution | string | Yes | School name |
degree | enum: HIGH_SCHOOL, ASSOCIATE, BACHELOR, MASTER, DOCTORATE, DIPLOMA, CERTIFICATE, GDIP, OTHER | No | Degree type |
major | string | No | |
gpa | string | No | GPA as text, e.g. "3.8" or "3.8/4.0" |
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
update_education_entry
Correct an education record. Only the fields you pass change. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
educationId | string | Yes | Resource ID |
institution | string | No | |
degree | enum: HIGH_SCHOOL, ASSOCIATE, BACHELOR, MASTER, DOCTORATE, DIPLOMA, CERTIFICATE, GDIP, OTHER | No | Degree type |
major | string | No | |
gpa | string | No | |
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
delete_education_entry
Permanently delete an education record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
educationId | string | Yes | Resource ID |
query_languages
List language proficiencies for one person, with separate reading/writing and speaking levels. An HR record: readable by the person themselves, ADMINISTRATOR and EXECUTIVE for anyone in the organization, and a DEPARTMENT_HEAD for people in the departments they head; anyone else is refused with 403 (Access denied).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_language
Add a language proficiency record for a user. language is required. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
language | string | Yes | Language name (e.g. "Spanish", "Mandarin") |
readingWritingProficiency | enum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVE | No | Reading and writing proficiency |
speakingProficiency | enum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVE | No | Speaking proficiency |
update_language
Update a language proficiency record. Only the fields you pass change. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
languageId | string | Yes | Resource ID |
language | string | No | |
readingWritingProficiency | enum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVE | No | |
speakingProficiency | enum: ELEMENTARY, LIMITED_WORKING, PROFESSIONAL, FULL_PROFESSIONAL, NATIVE | No |
delete_language
Permanently delete a language record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
languageId | string | Yes | Resource ID |
query_certifications
List certifications for a user (name, type, issuing body, credential ID, issued and expiry dates). Past-expiry certifications are marked EXPIRED. Visible to the employee themselves, ADMINISTRATOR, EXECUTIVE, and a DEPARTMENT_HEAD for their departments.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_certification
Add a certification for a user. name is required. The employee themselves, ADMINISTRATOR or EXECUTIVE only. Adding one for someone else returns 404 when that person is deactivated or not in your organization, or when certificationTypeId is not one of your organization's types.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
name | string | Yes | Certification name |
certificationTypeId | string | No | ID of one of the organization's certification types |
issuingBody | string | No | Organization that issued the certification |
credentialId | string | No | Credential / licence number |
issuedDate | string | No | Date in YYYY-MM-DD format |
expiryDate | string | No | Date in YYYY-MM-DD format |
update_certification
Update a certification. Only the fields you pass change; changing expiryDate recomputes ACTIVE/EXPIRED. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
certId | string | Yes | Resource ID |
name | string | No | |
certificationTypeId | string | No | |
issuingBody | string | No | |
credentialId | string | No | |
issuedDate | string | No | Date in YYYY-MM-DD format |
expiryDate | string | No | Date in YYYY-MM-DD format |
delete_certification
Permanently delete a certification record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
certId | string | Yes | Resource ID |
query_visa
List visa / work authorization records for a user (type, issuing country, status, dates, note). Past-expiry visas are marked EXPIRED. Visible to the employee themselves, ADMINISTRATOR, EXECUTIVE, and a DEPARTMENT_HEAD for their departments.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_visa_entry
Add a visa / work authorization record for a user. visaType is required. A past expiryDate is stored as EXPIRED. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
visaType | string | Yes | Visa type (e.g. "H-1B", "TN", "Permanent Resident") |
issuingCountry | string | No | Issuing country |
status | string | No | Status, defaults to ACTIVE (e.g. ACTIVE, PENDING) |
issuedDate | string | No | Date in YYYY-MM-DD format |
expiryDate | string | No | Date in YYYY-MM-DD format |
note | string | No |
delete_visa_entry
Permanently delete a visa record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
visaId | string | Yes | Resource ID |
query_assets
List company equipment held by a user (description, category, serial number, status, assigned and returned dates). Visible to the employee themselves, ADMINISTRATOR, EXECUTIVE, and the DEPARTMENT_HEAD of their department.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assign_asset
Issue a piece of company equipment to a user (status ASSIGNED). description is required. Pass categoryId, or categoryName to use (or create) a category by name. ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department. Refused for a deactivated person (INACTIVE_PERSON).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
description | string | Yes | What the asset is (e.g. "MacBook Pro 14 2024") |
categoryId | string | No | Asset category ID |
categoryName | string | No | Category name; an existing category with this name is used, otherwise one is created |
serialNumber | string | No | |
dateAssigned | string | No | Date issued (YYYY-MM-DD) |
update_asset
Update an equipment record held by a user. Only the fields you pass change. ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assetId | string | Yes | Resource ID |
description | string | No | |
serialNumber | string | No | |
categoryId | string | No | |
categoryName | string | No | |
dateAssigned | string | No | Date in YYYY-MM-DD format |
dateReturned | string | No | Date in YYYY-MM-DD format |
status | enum: AVAILABLE, ASSIGNED, RETIRED, LOST | No | Asset status |
return_asset
Mark an asset as returned: sets its status to AVAILABLE and, when dateReturned is given, records that date. Pass dateReturned (YYYY-MM-DD) to record when it came back; without it the return date is left as it was. ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assetId | string | Yes | Resource ID |
dateReturned | string | No | Date the asset was returned (YYYY-MM-DD) |
delete_asset
Permanently delete an asset record (use return_asset to mark it returned without losing history). ADMINISTRATOR, EXECUTIVE, or the DEPARTMENT_HEAD of the holder's department.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assetId | string | Yes | Resource ID |
query_custom_field_values
Read a user's values for the organization's custom profile fields (each with its field id, name, fieldType and options). Only fields that have a value are returned, and values on custom tabs hidden from the caller's role are left out. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
tabId | string | No | Only values for fields on this custom tab |
set_custom_field_values
Set a user's values for one or more custom profile fields (creates or replaces each value). Every value is a string: numbers as text, CHECKBOX as "true"/"false", DATE as YYYY-MM-DD, LIST_SINGLE as one of the field's options, LIST_MULTI as a JSON array string of options. A required field cannot be set empty. Fields come from query_custom_field_values (customField.id). The employee themselves, ADMINISTRATOR or EXECUTIVE only; a field on a tab hidden from the caller's role returns 404. Values are applied in order and stop at the first invalid one.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
values | object | Yes | |
values[].customFieldId | string | Yes | |
values[].value | string | Yes |
query_compensation_history
List compensation history (pay rate changes over time) for a user, newest first. ADMINISTRATOR or EXECUTIVE only; everyone else, including the employee themselves, is refused.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_compensation_entry
Add a compensation change record (a raise, a new pay rate, or a move between salaried and hourly). ADMINISTRATOR or EXECUTIVE only. effectiveDate, payType and a positive payRate are required.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
effectiveDate | string | Yes | Date this rate took effect (YYYY-MM-DD) |
payType | string | Yes | Pay type. The app offers SALARY or HOURLY. |
payRate | number | Yes | Pay rate: the annual amount for SALARY, the hourly rate for HOURLY |
currency | string | No | ISO currency code, defaults to USD on the server |
paySchedule | string | No | Pay schedule. The app offers WEEKLY, BIWEEKLY, SEMIMONTHLY or MONTHLY. |
overtimeStatus | string | No | Overtime status. The app offers EXEMPT or NON_EXEMPT. |
changeReason | string | No | Why the pay changed (e.g. Promotion, Annual review) |
comment | string | No |
update_compensation_entry
Correct an existing compensation history entry. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
compId | string | Yes | Resource ID |
effectiveDate | string | No | Date in YYYY-MM-DD format |
payType | string | No | Pay type. The app offers SALARY or HOURLY. |
payRate | number | No | |
currency | string | No | |
paySchedule | string | No | Pay schedule. The app offers WEEKLY, BIWEEKLY, SEMIMONTHLY or MONTHLY. |
overtimeStatus | string | No | Overtime status. The app offers EXEMPT or NON_EXEMPT. |
changeReason | string | No | |
comment | string | No |
delete_compensation_entry
Permanently delete a compensation history entry. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
compId | string | Yes | Resource ID |
query_bonuses
List one-off bonus records for a user, newest first. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_bonus
Add a one-off bonus record for a user. ADMINISTRATOR or EXECUTIVE only. date and a positive amount are required.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
date | string | Yes | Bonus date (YYYY-MM-DD) |
amount | number | Yes | |
currency | string | No | ISO currency code, defaults to USD on the server |
reason | string | No | e.g. Q4 Performance, Signing, Referral |
comment | string | No |
update_bonus
Correct an existing bonus record. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
bonusId | string | Yes | Resource ID |
date | string | No | Date in YYYY-MM-DD format |
amount | number | No | |
currency | string | No | |
reason | string | No | |
comment | string | No |
delete_bonus
Permanently delete a bonus record. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
bonusId | string | Yes | Resource ID |
query_job_history
List position changes (title, department, division, location, manager) over time for a user. ADMINISTRATOR and EXECUTIVE see anyone, DEPARTMENT_HEAD sees their own and their departments, EMPLOYEE sees only their own.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_job_history_entry
Add a job history record (promotion, transfer, title change). ADMINISTRATOR or EXECUTIVE only. This is a historical record: department, division, workLocation and reportsTo are free text as they should read in the history, and it does not change the employee's current profile.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
effectiveDate | string | Yes | YYYY-MM-DD |
jobTitle | string | No | |
department | string | No | Department name as text |
division | string | No | |
workLocation | string | No | |
reportsTo | string | No | Manager name as text |
changeReason | string | No | e.g. Promotion, Transfer |
update_job_history_entry
Correct an existing job history record. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
historyId | string | Yes | Resource ID |
effectiveDate | string | No | Date in YYYY-MM-DD format |
jobTitle | string | No | |
department | string | No | |
division | string | No | |
workLocation | string | No | |
reportsTo | string | No | |
changeReason | string | No |
delete_job_history_entry
Permanently delete a job history entry. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
historyId | string | Yes | Resource ID |
query_employment_status_history
List employment status changes (full-time, part-time, contract, etc.) over time. ADMINISTRATOR and EXECUTIVE see anyone, DEPARTMENT_HEAD sees their own and their departments, EMPLOYEE sees only their own.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_employment_status_change
Record an employment status change in the history (e.g. PARTTIME to FULLTIME). ADMINISTRATOR or EXECUTIVE only. This is a history record and does not change the employee's current profile.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
effectiveDate | string | Yes | Date in YYYY-MM-DD format |
employmentStatus | enum: FULLTIME, PARTTIME, CONTRACT, INTERN, TEMPORARY, SEASONAL | Yes | Employment status |
comment | string | No |
update_employment_status_change
Correct an existing employment status history entry. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
historyId | string | Yes | Resource ID |
effectiveDate | string | No | Date in YYYY-MM-DD format |
employmentStatus | enum: FULLTIME, PARTTIME, CONTRACT, INTERN, TEMPORARY, SEASONAL | No | Employment status |
comment | string | No |
delete_employment_status_change
Permanently delete an employment status history entry. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
historyId | string | Yes | Resource ID |
query_equity
List equity grants (stock options, RSUs, SARs, phantom stock) for a user. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_equity_grant
Record an equity grant. ADMINISTRATOR or EXECUTIVE only. grantDate, equityType and a positive grantAmount (number of units) are required.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
grantDate | string | Yes | Date in YYYY-MM-DD format |
equityType | enum: STOCK_OPTION, RSU, SAR, PHANTOM | Yes | |
grantAmount | number | Yes | Number of units granted |
exercisePrice | number | No | Exercise / strike price per unit |
currency | string | No | ISO currency code, defaults to USD on the server |
vestingSchedule | string | No | Free-text vesting schedule (e.g. 4 years, 1 year cliff, monthly) |
vestingStartDate | string | No | Date in YYYY-MM-DD format |
vestingPeriodMonths | integer | No | Total vesting period in months |
cliffMonths | integer | No | Cliff period in months |
expirationDate | string | No | Date in YYYY-MM-DD format |
status | string | No | Grant status, defaults to ACTIVE on the server |
vestedAmount | number | No | |
exercisedAmount | number | No | |
comment | string | No |
delete_equity_grant
Permanently delete an equity grant record. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
equityId | string | Yes | Resource ID |
query_commissions
List commission plans on record for a user, newest first. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_commission
Record a commission plan for a user (its type and rate from an effective date). ADMINISTRATOR or EXECUTIVE only. effectiveDate, commissionType and a positive rate are required.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
effectiveDate | string | Yes | Date in YYYY-MM-DD format |
commissionType | enum: PERCENTAGE, FLAT_RATE, TIERED | Yes | |
rate | number | Yes | Percentage for PERCENTAGE, amount for FLAT_RATE |
currency | string | No | ISO currency code, defaults to USD on the server |
frequency | string | No | How often it pays out (e.g. MONTHLY, QUARTERLY) |
target | number | No | |
cap | number | No | |
changeReason | string | No | |
comment | string | No |
delete_commission
Permanently delete a commission record. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
commissionId | string | Yes | Resource ID |
query_dependents
List dependents on file for a user (children, spouse, etc.). The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
add_dependent
Add a dependent to a user record. The employee themselves, ADMINISTRATOR or EXECUTIVE only. name and relationship are required.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
name | string | Yes | Full name of the dependent |
relationship | string | Yes | e.g. SPOUSE, CHILD, DOMESTIC_PARTNER, PARENT, OTHER |
dateOfBirth | string | No | Date in YYYY-MM-DD format |
gender | string | No |
update_dependent
Update a dependent record. Only the fields you pass change. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
depId | string | Yes | Resource ID |
name | string | No | |
relationship | string | No | |
dateOfBirth | string | No | Date in YYYY-MM-DD format |
gender | string | No |
delete_dependent
Permanently remove a dependent record. The employee themselves, ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
depId | string | Yes | Resource ID |
query_onboarding_instances
List onboarding and offboarding checklists (instances) with their tasks. Filter by userId, type and status. ADMINISTRATOR and EXECUTIVE see all; a DEPARTMENT_HEAD sees their departments, their own, and any they have tasks on; everyone else sees their own and those they have tasks on (only their own tasks on someone else's checklist).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Only checklists for this employee |
type | enum: ONBOARDING, OFFBOARDING | No | ONBOARDING or OFFBOARDING |
status | enum: NOT_STARTED, IN_PROGRESS, COMPLETED | No |
create_onboarding_instance
Start an onboarding or offboarding checklist for an employee, optionally from a template (task list). The template's tasks are copied with due dates computed from the employee's start date (onboarding) or end date (offboarding). ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments. Starting ONBOARDING for a deactivated person is refused (INACTIVE_PERSON); offboarding them is allowed.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
templateId | string | No | Onboarding template (task list) ID; omit for an empty checklist |
type | enum: ONBOARDING, OFFBOARDING | No | Defaults to ONBOARDING |
startDate | string | No | Date recorded as the checklist start (YYYY-MM-DD); defaults to now. Task due dates are computed from the employee start/end date, not this. |
update_onboarding_instance
Set the status of an onboarding/offboarding checklist (NOT_STARTED, IN_PROGRESS, COMPLETED). Status also updates automatically as tasks are completed. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
status | enum: NOT_STARTED, IN_PROGRESS, COMPLETED | Yes |
delete_onboarding_instance
Permanently delete an onboarding/offboarding checklist and all its tasks. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
query_onboarding_tasks
List the tasks in an onboarding/offboarding checklist with their status, assignee and due date. ADMINISTRATOR, EXECUTIVE, the employee the checklist is for, and anyone with a task on it.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
add_onboarding_task
Add an ad-hoc task to an onboarding/offboarding checklist. title is required. Attach a document template with documentTemplateId so the employee gets their own copy (to sign when requiresSignature is true). ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments. An inactive or unknown assignee is refused, as is a document template that is archived or replaced (TEMPLATE_NOT_CURRENT).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
title | string | Yes | Task title |
description | string | No | |
assignedToId | string | No | User ID of the person responsible |
assignedRole | enum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUS | No | Which team owns the task (defaults to HR on the server) |
category | enum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHER | No | Task category (defaults to OTHER on the server) |
dueDate | string | No | Date in YYYY-MM-DD format |
documentTemplateId | string | No | Document template to attach |
requiresSignature | boolean | No | Whether the attached document must be signed |
update_onboarding_task
Update a checklist task. A status-only change (PENDING, COMPLETED, SKIPPED) may be made by the task's assignee, or for an unassigned task by an ADMINISTRATOR, EXECUTIVE or the department head; completing a task with an unsigned required document is refused for non-admins. Changing any other field needs ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
taskId | string | Yes | Resource ID |
status | enum: PENDING, COMPLETED, SKIPPED | No | |
title | string | No | |
description | string | No | |
assignedToId | string | No | |
assignedRole | enum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUS | No | Which team owns the task (defaults to HR on the server) |
category | enum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHER | No | Task category (defaults to OTHER on the server) |
dueDate | string | No | Date in YYYY-MM-DD format |
complete_onboarding_task
Mark a checklist task COMPLETED. The task's assignee may do this, or for an unassigned task an ADMINISTRATOR, EXECUTIVE or the department head. If a document that must be signed is attached, non-admins are refused until it is signed.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
taskId | string | Yes | Resource ID |
delete_onboarding_task
Permanently delete a task from an onboarding/offboarding checklist. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for people in their departments.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
instanceId | string | Yes | Resource ID |
taskId | string | Yes | Resource ID |
query_onboarding_templates
List onboarding/offboarding templates (task lists) the caller can see, with task and usage counts. Filter by type. Administrators see all; others see organization-wide lists plus those for their departments.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
type | enum: ONBOARDING, OFFBOARDING | No | ONBOARDING or OFFBOARDING |
create_onboarding_template
Create an onboarding or offboarding template (task list). name is required and must be unique per type and department (409 otherwise). Omit departmentId for an organization-wide list. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments. A DEPARTMENT_HEAD's list defaults to their own department.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
type | enum: ONBOARDING, OFFBOARDING | No | Defaults to ONBOARDING |
departmentId | string | No | Scope the list to one department |
icon | string | No | Icon name shown next to the list |
update_onboarding_template
Update an onboarding/offboarding template (task list). Only the fields you pass change. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments. Only administrators may change departmentId.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
name | string | No | |
type | enum: ONBOARDING, OFFBOARDING | No | ONBOARDING or OFFBOARDING |
departmentId | string or null | No | Department ID, or null for organization-wide |
icon | string | No | |
isActive | boolean | No |
delete_onboarding_template
Permanently delete an onboarding/offboarding template and its task definitions. Checklists already started from it are kept. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
query_onboarding_template_tasks
List the task definitions inside an onboarding/offboarding template.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
add_onboarding_template_task
Add a task definition to an onboarding/offboarding template. It applies to checklists started from the template afterwards, not to ones already running. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments. An inactive assignee or a document template that is archived or replaced (TEMPLATE_NOT_CURRENT) is refused.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
title | string | Yes | |
description | string | No | |
assignedToId | string | No | User ID responsible; when omitted the organization default assignee is used |
assignedRole | enum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUS | No | Which team owns the task (defaults to HR on the server) |
category | enum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHER | No | Task category (defaults to OTHER on the server) |
dueDateType | enum: NONE, ON_HIRE, CUSTOM | No | NONE, ON_HIRE (due on the start / last day), or CUSTOM (dueDaysFromHire days before/after) |
dueDaysFromHire | integer | No | Days from the start/end date, used when dueDateType is CUSTOM |
dueDaysDirection | enum: BEFORE, AFTER | No | |
notificationTiming | enum: SOON, ON_DUE_DATE, NONE | No | |
targetScope | enum: ALL, SOME | No | ALL employees the list is used for, or SOME (only targetEmployeeIds) |
targetEmployeeIds | string | No | Used when targetScope is SOME |
documentTemplateId | string | No | Document template each employee receives a copy of |
requiresSignature | boolean | No |
update_onboarding_template_task
Update a task definition in an onboarding/offboarding template. Only the fields you pass change. Changing documentTemplateId or requiresSignature is also applied to matching tasks on checklists already started from this template. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
taskDefId | string | Yes | Resource ID |
title | string | No | |
description | string | No | |
assignedToId | string | No | User ID responsible; when omitted the organization default assignee is used |
assignedRole | enum: HR, IT, MANAGER, EMPLOYEE, MISCELLANEOUS | No | Which team owns the task (defaults to HR on the server) |
category | enum: DOCUMENTS, EQUIPMENT, ACCESS, TRAINING, OTHER | No | Task category (defaults to OTHER on the server) |
dueDateType | enum: NONE, ON_HIRE, CUSTOM | No | NONE, ON_HIRE (due on the start / last day), or CUSTOM (dueDaysFromHire days before/after) |
dueDaysFromHire | integer | No | Days from the start/end date, used when dueDateType is CUSTOM |
dueDaysDirection | enum: BEFORE, AFTER | No | |
notificationTiming | enum: SOON, ON_DUE_DATE, NONE | No | |
targetScope | enum: ALL, SOME | No | ALL employees the list is used for, or SOME (only targetEmployeeIds) |
targetEmployeeIds | string | No | Used when targetScope is SOME |
documentTemplateId | string | No | Document template each employee receives a copy of |
requiresSignature | boolean | No |
delete_onboarding_template_task
Permanently delete a task definition from an onboarding/offboarding template. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for task lists scoped to their departments.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
taskDefId | string | Yes | Resource ID |
query_onboarding_packets
List new hire welcome packets. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
get_onboarding_packet
Get full details of a new hire packet (arrival, location, contact, instructions, "Get to Know You" questions, linked task lists). ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
packetId | string | Yes | Resource ID |
create_onboarding_packet
Create a new hire welcome packet: arrival time, location, contact person, instructions, linked task lists and "Get to Know You" questions. name is required. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
arrivalTime | string | No | Arrival time (e.g. "9:00 AM") |
location | string | No | |
whoToContactId | string | No | User ID of the contact person (must be active) |
otherInstructions | string | No | |
linkedTemplateIds | string | No | Onboarding template IDs linked to this packet |
sendGetToKnowYou | boolean | No | Send the "Get to Know You" questions |
getToKnowYouQuestions | string | No | "Get to Know You" questions |
getToKnowYouScope | enum: ALL, DEPARTMENT, CUSTOM | No | Who receives the answers: ALL, DEPARTMENT or CUSTOM (getToKnowYouIds) |
getToKnowYouIds | string | No | Department or employee IDs for DEPARTMENT/CUSTOM scope |
isDefault | boolean | No |
update_onboarding_packet
Update a new hire packet. Only the fields you pass change. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
packetId | string | Yes | Resource ID |
name | string | No | |
arrivalTime | string | No | Arrival time (e.g. "9:00 AM") |
location | string | No | |
whoToContactId | string | No | User ID of the contact person (must be active) |
otherInstructions | string | No | |
linkedTemplateIds | string | No | Onboarding template IDs linked to this packet |
sendGetToKnowYou | boolean | No | Send the "Get to Know You" questions |
getToKnowYouQuestions | string | No | "Get to Know You" questions |
getToKnowYouScope | enum: ALL, DEPARTMENT, CUSTOM | No | Who receives the answers: ALL, DEPARTMENT or CUSTOM (getToKnowYouIds) |
getToKnowYouIds | string | No | Department or employee IDs for DEPARTMENT/CUSTOM scope |
isDefault | boolean | No |
delete_onboarding_packet
Permanently delete a new hire packet. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
packetId | string | Yes | Resource ID |
Clients
5 tools.
query_clients
List the organization's clients (the companies projects are billed to), alphabetically, with project counts. Filter by status or a name search. Returns every match (no paging). DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches the client name |
status | enum: ACTIVE, INACTIVE, ARCHIVED | No |
get_client
Get one client with its contact details and projects. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Resource ID |
create_client
Create a client. The name must be unique in the organization (409 otherwise); status defaults to ACTIVE. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Client name |
email | string or null | No | |
phone | string or null | No | |
company | string or null | No | |
address | string or null | No | Full postal address as one text field |
notes | string or null | No | |
status | enum: ACTIVE, INACTIVE, ARCHIVED | No |
update_client
Update a client. Only the fields passed are changed; null clears a field. A new name must be unique in the organization. Set status INACTIVE or ARCHIVED to retire a client without deleting it. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Resource ID |
name | string | No | |
email | string or null | No | |
phone | string or null | No | |
company | string or null | No | |
address | string or null | No | Full postal address as one text field |
notes | string or null | No | |
status | enum: ACTIVE, INACTIVE, ARCHIVED | No |
delete_client
Permanently delete a client. Refused (400) while the client has any ACTIVE project; its other projects are kept but unlinked from it. Consider update_client with status ARCHIVED instead. DEPARTMENT_HEAD, ADMINISTRATOR and EXECUTIVE only; employees are refused (403).
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Resource ID |
Notifications
5 tools.
get_unread_notification_count
Get the number of unread notifications for the current user.
Read-only
No parameters.
mark_notification_read
Mark one of the current user's notifications as read.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
notificationId | string | Yes | Resource ID |
mark_all_notifications_read
Mark every notification as read for the current user.
Write
No parameters.
delete_notification
Delete (dismiss) one of the current user's notifications.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
notificationId | string | Yes | Resource ID |
clear_all_notifications
Delete every notification for the current user. Cannot be undone.
Destructive · Risk: medium
No parameters.
Calendar
8 tools.
get_calendar_status
Show the current user's calendar sync state: connected Google/Outlook integrations, their iCal feeds, and which providers the server has configured.
Read-only
No parameters.
query_calendar_feeds
List the current user's iCal feeds with type, subscription URL, last access and access count. The URL is a private link: anyone holding it can read the feed.
Read-only
No parameters.
create_calendar_feed
Create an iCal subscription URL for the current user, to add to Google Calendar, Outlook or Apple Calendar. feedType PERSONAL (own leave, anyone), APPROVALS (leave awaiting the caller's approval), DEPARTMENT (needs departmentId; ADMINISTRATOR/EXECUTIVE any department, DEPARTMENT_HEAD only their scope), DIRECT_REPORTS (ADMINISTRATOR/EXECUTIVE/DEPARTMENT_HEAD with at least one direct report), ORGANIZATION (ADMINISTRATOR/EXECUTIVE). The returned URL is a private link: anyone holding it can read the feed.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
feedType | enum: PERSONAL, DEPARTMENT, DIRECT_REPORTS, APPROVALS, ORGANIZATION | Yes | |
departmentId | string | No | Required when feedType is DEPARTMENT |
name | string | No | Friendly name for the feed |
delete_calendar_feed
Delete one of the current user's calendar feeds. Its iCal URL stops working immediately.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
feedId | string | Yes | Resource ID |
connect_google_calendar
Start the Google Calendar OAuth flow for the current user. Returns authUrl — the user must open it in a browser to grant access.
Read-only
No parameters.
disconnect_google_calendar
Disconnect the current user's Google Calendar integration.
Write · Risk: medium
No parameters.
connect_outlook_calendar
Start the Outlook Calendar OAuth flow for the current user. Returns authUrl — the user must open it in a browser to grant access.
Read-only
No parameters.
disconnect_outlook_calendar
Disconnect the current user's Outlook Calendar integration.
Write · Risk: medium
No parameters.
Performance
37 tools.
query_goals
List a person's performance goals, optionally filtered by status or category. Administrators and executives may read anyone, department heads their own departments, employees only their own.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
status | enum: NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLED | No | |
category | string | No | Exact category name (case-insensitive) |
create_goal
Set a performance goal for a person. Allowed for executives (anyone, including themselves), administrators (anyone except themselves) and department heads (people in departments they head or manage, not themselves); employees cannot. The person must be an active member (404 otherwise). Progress starts at 0; use update_goal to move it.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Goal owner |
title | string | Yes | |
description | string | No | |
category | string | No | e.g. Engineering, Sales, Personal |
dueDate | string | No | Date in YYYY-MM-DD format |
status | enum: NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLED | No | Default NOT_STARTED |
weight | number | No | Relative weight of the goal |
update_goal
Update a goal. The goal owner and anyone who may manage their performance can change title, description, status, percentComplete (0-100) and dueDate; category and weight change only for a manager and are ignored for the owner. Setting percentComplete also syncs the status (100 = COMPLETED, 0 = NOT_STARTED, otherwise IN_PROGRESS from NOT_STARTED).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Goal owner |
goalId | string | Yes | Resource ID |
title | string | No | |
description | string | No | |
status | enum: NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLED | No | |
percentComplete | integer | No | |
dueDate | string | No | Date in YYYY-MM-DD format |
category | string | No | |
weight | number or null | No |
delete_goal
Permanently delete a goal and all its comments. Allowed for executives (anyone, including themselves), administrators (anyone except themselves) and department heads (people in departments they head or manage, not themselves); employees cannot. The goal owner cannot delete a goal set for them.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
goalId | string | Yes | Resource ID |
query_goal_comments
List the comments on a goal that the caller may read. Comments carry a visibility floor (SHARED, MANAGEMENT, LEADERSHIP); ones above the caller's level are left out. Readable by the owner, their department head, administrators and executives.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
goalId | string | Yes | Resource ID |
add_goal_comment
Comment on a goal. Allowed for executives (anyone, including themselves), administrators (anyone except themselves) and department heads (people in departments they head or manage, not themselves); employees cannot. visibility sets who can read it: SHARED (default; the owner too), MANAGEMENT (not the owner) or LEADERSHIP (administrators and executives only, which department heads cannot choose).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Goal owner |
goalId | string | Yes | Resource ID |
content | string | Yes | Comment text |
visibility | enum: SHARED, MANAGEMENT, LEADERSHIP | No |
delete_goal_comment
Permanently delete a goal comment. Allowed for its author, or for someone who may manage the goal owner's performance.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
goalId | string | Yes | Resource ID |
commentId | string | Yes | Resource ID |
query_one_on_one_series
List the recurring 1:1 series a person takes part in (default: the caller), with both participants, cadence and the next scheduled meeting. Viewing someone else's needs administrator/executive, being their manager, or heading their department.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Whose 1:1s to list (default: the caller) |
create_one_on_one_series
Set up a recurring 1:1 between an employee (subjectId) and another person (participantId, default: the subject's department head, then their manager). Allowed for executives (anyone), administrators (anyone but themselves) and department heads (their own departments, not themselves). Both people must be active. Creates the first meeting only (firstMeetingDate, default one week from today in the organization's timezone) and notifies the participants by email. Refused with 409 if the pair already has a series.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
subjectId | string | No | Employee the 1:1 is about (default: the caller) |
participantId | string | No | Who they meet with (default: department head, then manager) |
frequency | enum: WEEKLY, BIWEEKLY, MONTHLY, ONE_TIME | No | Meeting cadence (default WEEKLY) |
firstMeetingDate | string | No | First meeting date (YYYY-MM-DD) |
startTime | string | No | Start time of day, HH:MM (24-hour) |
durationMinutes | integer | No | Duration in minutes (default 30) |
reviewCycleId | string | No | Link the series to a review cycle |
update_one_on_one_series
Update a 1:1 series: cadence, active flag, next meeting date, start time, duration or linked review cycle. Open to the two participants, administrators, executives, the subject's manager and their department head. Reactivating a series whose participant has left is refused.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
seriesId | string | Yes | Resource ID |
frequency | enum: WEEKLY, BIWEEKLY, MONTHLY, ONE_TIME | No | Meeting cadence |
isActive | boolean | No | Pause (false) or resume (true) the series |
nextMeetingDate | string | No | Date in YYYY-MM-DD format |
startTime | string | No | Start time of day, HH:MM (24-hour) |
durationMinutes | integer | No | Duration in minutes (1-480) |
reviewCycleId | string | No | Review cycle to link; empty string unlinks |
cancel_one_on_one_series
Permanently delete a 1:1 series with ALL its meetings, agenda items and notes, past and future, and remove synced calendar events. This cannot be undone; to pause a series instead, use update_one_on_one_series with isActive false. Allowed for whoever may set up a 1:1 for the subject (executives, administrators for others, department heads for their departments); participants alone cannot. The other participant is notified.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
seriesId | string | Yes | Resource ID |
query_one_on_one_meetings
List the meetings in a 1:1 series, newest first, with agenda and note counts. Open to the two participants, administrators, executives, the subject's manager and their department head.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
seriesId | string | Yes | Resource ID |
schedule_one_on_one_meeting
Add a meeting on a given date to an existing 1:1 series. Set its time or duration afterwards with update_one_on_one_meeting. Open to the two participants, administrators, executives, the subject's manager and their department head.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
seriesId | string | Yes | Resource ID |
meetingDate | string | Yes | Date in YYYY-MM-DD format |
update_one_on_one_meeting
Reschedule a 1:1 meeting or record its outcome: date, start time, duration, or status. Open to the two participants, administrators, executives, the subject's manager and their department head.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
seriesId | string | Yes | Resource ID |
meetingId | string | Yes | Resource ID |
meetingDate | string | No | Date in YYYY-MM-DD format |
startTime | string | No | Start time of day, HH:MM (24-hour) |
durationMinutes | integer | No | Duration in minutes (1-480) |
status | enum: SCHEDULED, COMPLETED, CANCELLED, SKIPPED | No |
query_meeting_agenda
List the agenda items for a 1:1 meeting in order. Open to the two participants, administrators, executives, the subject's manager and their department head.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
add_agenda_item
Add an agenda item to the end of a 1:1 meeting's agenda. The caller is recorded as its author. Open to the two participants, administrators, executives, the subject's manager and their department head.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
text | string | Yes | Agenda item text |
update_agenda_item
Edit an agenda item's text, tick it off (isCompleted) or move it (sortOrder). Open to the two participants, administrators, executives, the subject's manager and their department head.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
itemId | string | Yes | Resource ID |
text | string | No | |
isCompleted | boolean | No | |
sortOrder | integer | No |
delete_agenda_item
Permanently delete an agenda item. Open to the two participants, administrators, executives, the subject's manager and their department head.
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
itemId | string | Yes | Resource ID |
query_meeting_notes
List notes on a 1:1 meeting. Private notes are returned only to their author. Open to the two participants, administrators, executives, the subject's manager and their department head.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
add_meeting_note
Add a note to a 1:1 meeting. Mark it private to keep it visible only to yourself. Open to the two participants, administrators, executives, the subject's manager and their department head.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
content | string | Yes | |
isPrivate | boolean | No | Private notes are only visible to the author (default: false) |
update_meeting_note
Edit a 1:1 meeting note or change whether it is private. Only the note's author may edit it (404 otherwise).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
noteId | string | Yes | Resource ID |
content | string | No | |
isPrivate | boolean | No |
delete_meeting_note
Permanently delete a 1:1 meeting note. Only the note's author may delete it (404 otherwise).
Destructive
| Parameter | Type | Required | Description |
|---|---|---|---|
meetingId | string | Yes | Resource ID |
noteId | string | Yes | Resource ID |
query_performance_cycles
List every performance review cycle in the organization with its timing, scope, status, member count and assessment count. Administrators and executives only (others get 403); use query_active_performance_cycles for the short list of running cycles.
Read-only
No parameters.
query_active_performance_cycles
List review cycles that are ACTIVE and still open today in the organization's timezone (id, name, timing, dates, status only). Callable by anyone who may send documents: administrators, executives and department heads (department heads see only cycles covering someone in their departments).
Read-only
No parameters.
create_performance_cycle
Create a performance review cycle. Administrators and executives only. A FIXED cycle (the default) needs startDate; an ANNIVERSARY cycle uses anniversaryMonths instead of dates. Scope defaults to ALL employees; DEPARTMENT needs departmentId and CUSTOM needs employeeIds (all must be active members, otherwise 400). Status defaults to ACTIVE.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Cycle name, e.g. "Annual Review 2026" |
type | string | No | Free-form cycle type label, e.g. ANNUAL, QUARTERLY (default ANNUAL) |
status | enum: DRAFT, ACTIVE | No | DRAFT (not running, sends no reminders) or ACTIVE |
timing | enum: FIXED, ANNIVERSARY | No | FIXED = a start/end window; ANNIVERSARY = due a number of months after each person's hire date |
startDate | string | No | Window start (YYYY-MM-DD). Required when timing is FIXED |
endDate | string | No | Window end (YYYY-MM-DD), not before startDate |
anniversaryMonths | integer | No | ANNIVERSARY timing only: months after hire the review falls due (default 12) |
anniversaryRepeats | boolean | No | ANNIVERSARY timing only: repeat every interval (default true) |
reminderOffsetDays | integer | No | Days before the due date to send reminders, 1-6 values (default 14, 3) |
employeeScope | enum: ALL, DEPARTMENT, CUSTOM | No | Who the cycle covers: ALL active employees, one DEPARTMENT (needs departmentId), or CUSTOM (needs employeeIds) |
departmentId | string | No | Department ID, for employeeScope DEPARTMENT |
employeeIds | string | No | Active employee IDs, for employeeScope CUSTOM. Supplying this without employeeScope sets the scope to CUSTOM |
update_performance_cycle
Update a performance review cycle: name, type, status (DRAFT/ACTIVE), timing, dates, reminders or who it covers. Administrators and executives only. Only the fields you pass change; the current scope is kept when you change only dates or reminders. Adding employees requires them to be active.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
cycleId | string | Yes | Resource ID |
name | string | No | |
type | string | No | Free-form cycle type label, e.g. ANNUAL, QUARTERLY (default ANNUAL) |
status | enum: DRAFT, ACTIVE | No | DRAFT (not running, sends no reminders) or ACTIVE |
timing | enum: FIXED, ANNIVERSARY | No | FIXED = a start/end window; ANNIVERSARY = due a number of months after each person's hire date |
startDate | string | No | Window start (YYYY-MM-DD). Required when timing is FIXED |
endDate | string | No | Window end (YYYY-MM-DD), not before startDate |
anniversaryMonths | integer | No | ANNIVERSARY timing only: months after hire the review falls due (default 12) |
anniversaryRepeats | boolean | No | ANNIVERSARY timing only: repeat every interval (default true) |
reminderOffsetDays | integer | No | Days before the due date to send reminders, 1-6 values (default 14, 3) |
employeeScope | enum: ALL, DEPARTMENT, CUSTOM | No | Who the cycle covers: ALL active employees, one DEPARTMENT (needs departmentId), or CUSTOM (needs employeeIds) |
departmentId | string | No | Department ID, for employeeScope DEPARTMENT |
employeeIds | string | No | Active employee IDs, for employeeScope CUSTOM. Supplying this without employeeScope sets the scope to CUSTOM |
delete_performance_cycle
Permanently delete a performance review cycle together with every assessment filed under it. Administrators and executives only. This cannot be undone; set status to DRAFT with update_performance_cycle to pause a cycle instead.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
cycleId | string | Yes | Resource ID |
duplicate_performance_cycle
Copy an existing performance cycle (timing, dates, reminders and scope) as a new DRAFT named "Copy of <name>". Optionally rename it and give it new dates in the same call. Administrators and executives only. Activate the copy with update_performance_cycle status ACTIVE.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
cycleId | string | Yes | Cycle to copy |
newName | string | No | Name for the copy (default "Copy of <name>") |
newStartDate | string | No | Start date for the copy (YYYY-MM-DD) |
newEndDate | string | No | End date for the copy (YYYY-MM-DD) |
query_performance_assessments
List performance assessments, optionally for one review cycle and/or one subject. Administrators and executives see all. Anyone else sees only assessments they are writing plus COMPLETED ones about themselves, with the author hidden on PEER and DIRECT_REPORT feedback; asking for another person returns an empty list.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
cycleId | string | No | Review cycle ID |
userId | string | No | Subject (person being assessed) |
create_performance_assessment
Assign an assessment within a review cycle: who is assessed (userId), who writes it (assessorId) and in what capacity. Administrators and executives only. Subject and assessor must be active members (otherwise 404). It starts PENDING; the assessor fills it in with update_performance_assessment.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
reviewCycleId | string | Yes | Review cycle ID |
userId | string | Yes | Subject (person being assessed) |
assessorId | string | Yes | Person writing the assessment |
assessorType | enum: SELF, MANAGER, PEER, DIRECT_REPORT | No | Assessor relationship (default MANAGER) |
update_performance_assessment
Fill in or change an assessment. The assessor (or an administrator/executive) may set status, responses, overallRating and comments; setting status COMPLETED records the completion time. Only administrators and executives may change assessorId, assessorType, userId or reviewCycleId (ignored for others). Anyone else gets 403.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Resource ID |
status | enum: PENDING, IN_PROGRESS, COMPLETED | No | |
responses | object | No | Answers to the template questions, e.g. { question, answer }. Replaces the stored responses |
overallRating | number or null | No | Overall rating, e.g. 1-5; null clears it |
comments | string | No | |
assessorId | string | No | Admin/executive only: reassign to another active member |
assessorType | enum: SELF, MANAGER, PEER, DIRECT_REPORT | No | Admin/executive only |
userId | string | No | Admin/executive only: change the subject (must be active) |
reviewCycleId | string | No | Admin/executive only: move to another cycle |
query_performance_templates
List assessment templates (named sets of review questions). Administrators and executives only.
Read-only
No parameters.
create_performance_template
Create an assessment template with at least one question. Administrators and executives only. Names are unique per organization (409 on a duplicate).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
description | string | No | |
questions | object | Yes | Questions, e.g. { question: "Top accomplishment?", type: "TEXT", required: true } |
questions[].question | string | Yes | Question text |
questions[].type | string | Yes | Answer type, e.g. TEXT or RATING |
questions[].required | boolean | Yes | Whether an answer is required |
isActive | boolean | No | Default true |
update_performance_template
Update an assessment template. Administrators and executives only. Passing questions REPLACES the whole question list, so send every question you want to keep.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
name | string | No | |
description | string | No | |
questions | object | No | Full replacement question list |
questions[].question | string | Yes | Question text |
questions[].type | string | Yes | Answer type, e.g. TEXT or RATING |
questions[].required | boolean | Yes | Whether an answer is required |
isActive | boolean | No |
delete_performance_template
Permanently delete an assessment template. Administrators and executives only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
get_performance_settings
Get the organization's performance settings: who may use goals, cascading goals, goal sharing default and categories, feedback summaries, and 1:1 enablement, default cadence and visibility. Administrators and executives only.
Read-only
No parameters.
update_performance_settings
Update organization-wide performance settings. Administrators and executives only. Only the fields you pass change. goalUsersIds replaces the list of people allowed to set goals when goalUsersScope is SOME; inactive or unknown people being added are dropped.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
goalUsersScope | enum: NONE, ALL, SOME | No | Who may use goals |
goalUsersIds | string | No | People allowed to use goals when goalUsersScope is SOME (full replacement) |
cascadingGoals | boolean | No | |
goalSharingDefault | enum: PRIVATE, MANAGER, DEPARTMENT, ORGANIZATION | No | |
goalCategories | string | No | Goal category names (full replacement) |
includeFeedbackSummaries | boolean | No | |
oneOnOnesEnabled | boolean | No | |
oneOnOneDefaultFreq | enum: WEEKLY, BIWEEKLY, MONTHLY | No | |
oneOnOneVisibility | enum: PARTICIPANTS_ONLY, MANAGER_CHAIN, ADMIN | No |
Training
14 tools.
query_user_training
List a person's training assignments with course details, status (ASSIGNED, IN_PROGRESS, COMPLETED, OVERDUE), due and completed dates. Administrators and executives may read anyone, department heads their own departments, employees only their own.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assign_training
Assign a training course to one person, or record one they already completed (status COMPLETED, completedDate defaults to their today). Allowed for administrators and executives (anyone) and department heads (people in departments they head or manage, not themselves). Refused for a deactivated person unless recording a completion (INACTIVE_PERSON), and with 409 ALREADY_ASSIGNED if the course is already assigned to them.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
courseId | string | Yes | Training course ID |
dueDate | string | No | Date in YYYY-MM-DD format |
status | enum: ASSIGNED, IN_PROGRESS, COMPLETED, OVERDUE | No | Default ASSIGNED |
completedDate | string | No | Only used when status is COMPLETED |
notes | string | No |
update_training_assignment
Update a training assignment. Allowed for administrators and executives (anyone) and department heads (people in departments they head or manage, not themselves). Such a manager may change status, dueDate, completedDate, score and notes. The person themselves may only set status IN_PROGRESS or COMPLETED (with an optional completedDate); their other fields are ignored. Use mark_training_complete for the common case.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assignmentId | string | Yes | Resource ID |
status | enum: ASSIGNED, IN_PROGRESS, COMPLETED, OVERDUE | No | |
dueDate | string | No | Date in YYYY-MM-DD format |
completedDate | string | No | Date in YYYY-MM-DD format |
score | number | No | |
notes | string | No |
mark_training_complete
Mark a training assignment COMPLETED. The person themselves or a manager may do this. completedDate defaults to now on the server; score and notes are kept only when a manager (administrator, executive or their department head) sends them.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assignmentId | string | Yes | Resource ID |
completedDate | string | No | Completion day (YYYY-MM-DD); omit to use today |
score | number | No | |
notes | string | No |
dismiss_training
Permanently delete a training assignment from a person's record (it is not marked complete or skipped; it is removed). Allowed for administrators and executives (anyone) and department heads (people in departments they head or manage, not themselves). Employees cannot. This cannot be undone.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
assignmentId | string | Yes | Resource ID |
query_training_courses
List the organization's active training courses with category and assignment counts. Optionally filter by category.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
categoryId | string | No | Only courses in this training category |
create_training_course
Create a training course in the catalog. Administrators and executives only. When isRequired is true it is assigned immediately to every active person it targets (requiredForType, default ALL). Names are unique (409 on a duplicate).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
description | string | No | |
categoryId | string | No | Training category ID |
provider | string | No | |
duration | integer | No | Duration in minutes |
url | string | No | Link to the training material |
frequency | enum: ONE_TIME, EVERY_YEAR, EVERY_2_YEARS, EVERY_3_YEARS, EVERY_5_YEARS | No | How often the course must be retaken |
dueDaysFromHire | integer | No | Days after hire the course is due |
isRequired | boolean | No | Required courses are assigned automatically to everyone they target |
requiredForType | enum: ALL, DEPARTMENT, ROLE, EMPLOYEES | No | Who a required course targets: ALL, one DEPARTMENT (requiredDepartmentId), one ROLE (requiredRole) or specific EMPLOYEES (requiredEmployeeIds) |
requiredDepartmentId | string | No | Department ID, for requiredForType DEPARTMENT |
requiredRole | enum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVE | No | Role, for requiredForType ROLE |
requiredEmployeeIds | string | No | User IDs, for requiredForType EMPLOYEES |
allowSelfComplete | boolean | No | Let assignees mark it complete themselves |
update_training_course
Update a training course. Administrators and executives only. Only the fields you pass change. Turning isRequired on assigns it to everyone it targets who does not have it yet. Set isActive false to retire a course without deleting its history.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
courseId | string | Yes | Resource ID |
name | string | No | |
description | string | No | |
categoryId | string | No | Training category ID |
provider | string | No | |
duration | integer | No | Duration in minutes |
url | string | No | Link to the training material |
frequency | enum: ONE_TIME, EVERY_YEAR, EVERY_2_YEARS, EVERY_3_YEARS, EVERY_5_YEARS | No | How often the course must be retaken |
dueDaysFromHire | integer | No | Days after hire the course is due |
isRequired | boolean | No | Required courses are assigned automatically to everyone they target |
requiredForType | enum: ALL, DEPARTMENT, ROLE, EMPLOYEES | No | Who a required course targets: ALL, one DEPARTMENT (requiredDepartmentId), one ROLE (requiredRole) or specific EMPLOYEES (requiredEmployeeIds) |
requiredDepartmentId | string | No | Department ID, for requiredForType DEPARTMENT |
requiredRole | enum: EMPLOYEE, DEPARTMENT_HEAD, ADMINISTRATOR, EXECUTIVE | No | Role, for requiredForType ROLE |
requiredEmployeeIds | string | No | User IDs, for requiredForType EMPLOYEES |
allowSelfComplete | boolean | No | Let assignees mark it complete themselves |
isActive | boolean | No |
delete_training_course
Permanently delete a training course AND every assignment of it, including completion records. Administrators and executives only. To retire a course but keep its history, use update_training_course with isActive false.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
courseId | string | Yes | Resource ID |
bulk_assign_training
Assign a training course to many people at once: a list of userIds, or every active member of a department (departmentId, which takes precedence). Administrators and executives only. Inactive or unknown people are dropped and people who already have the course are skipped; the result reports how many were assigned and skipped.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
courseId | string | Yes | Resource ID |
userIds | string | No | |
departmentId | string | No | Assign to every active member of this department |
dueDate | string | No | Date in YYYY-MM-DD format |
notes | string | No |
query_training_categories
List training categories with their course counts.
Read-only
No parameters.
create_training_category
Create a training category. Administrators and executives only. Names are unique (409 on a duplicate).
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes |
update_training_category
Rename a training category. Administrators and executives only.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
categoryId | string | Yes | Resource ID |
name | string | Yes |
delete_training_category
Delete a training category. Its courses are kept and become uncategorised. Administrators and executives only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
categoryId | string | Yes | Resource ID |
Benefits
8 tools.
query_benefit_plans
List the organization's active benefit plans (medical, dental, vision, life, disability, retirement, reimbursement, other) with contributions and enrollment counts.
Read-only
No parameters.
create_benefit_plan
Create a benefit plan. Administrators and executives only. Plan names are unique (409 on a duplicate); contributions cannot be negative.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
category | enum: MEDICAL, DENTAL, VISION, LIFE, DISABILITY, RETIREMENT, REIMBURSEMENT, OTHER | Yes | Plan category |
description | string | No | |
provider | string | No | Insurer or provider name |
policyNumber | string | No | |
employeeContribution | number or null | No | Employee contribution per period |
employerContribution | number or null | No | Employer contribution per period |
contributionType | enum: FIXED, PERCENTAGE | No | Whether contributions are fixed amounts or percentages |
currency | string | No | ISO currency code (default USD) |
update_benefit_plan
Update a benefit plan. Administrators and executives only. Only the fields you pass change. Set isActive false to retire a plan without deleting its enrollments.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | Resource ID |
name | string | No | |
category | enum: MEDICAL, DENTAL, VISION, LIFE, DISABILITY, RETIREMENT, REIMBURSEMENT, OTHER | No | Plan category |
description | string | No | |
provider | string | No | Insurer or provider name |
policyNumber | string | No | |
employeeContribution | number or null | No | Employee contribution per period |
employerContribution | number or null | No | Employer contribution per period |
contributionType | enum: FIXED, PERCENTAGE | No | Whether contributions are fixed amounts or percentages |
currency | string | No | ISO currency code (default USD) |
isActive | boolean | No |
delete_benefit_plan
Permanently delete a benefit plan AND every enrollment in it. Administrators and executives only. To retire a plan but keep enrollment history, use update_benefit_plan with isActive false.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | Resource ID |
query_user_benefits
List a person's benefit enrollments with plan name, category, provider, status, enrollment and termination dates, and employee/employer amounts. Administrators and executives may read anyone, department heads their own departments, employees only their own.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
enroll_user_in_benefit
Enroll a person in a benefit plan. Administrators and executives only. The person must be active (404 otherwise); refused with 409 if they are already enrolled in that plan.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
planId | string | Yes | Benefit plan ID |
status | enum: ELIGIBLE, ENROLLED, WAIVED, TERMINATED | No | Default ENROLLED |
enrollmentDate | string | No | Date in YYYY-MM-DD format |
employeeAmount | number | No | |
employerAmount | number | No |
update_user_benefit_enrollment
Update a benefit enrollment: status, enrollment or termination date, and employee/employer amounts. Administrators and executives only. Only the fields you pass change.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
enrollmentId | string | Yes | Resource ID |
status | enum: ELIGIBLE, ENROLLED, WAIVED, TERMINATED | No | Enrollment status |
enrollmentDate | string | No | Date in YYYY-MM-DD format |
terminationDate | string | No | Date in YYYY-MM-DD format |
employeeAmount | number or null | No | |
employerAmount | number or null | No |
unenroll_user_from_benefit
Permanently delete a benefit enrollment record. Administrators and executives only. To keep the history, set status TERMINATED with a terminationDate via update_user_benefit_enrollment instead.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
enrollmentId | string | Yes | Resource ID |
Documents
21 tools.
query_documents
List documents. EMPLOYEE sees their own folder, DEPARTMENT_HEAD their department scope, ADMINISTRATOR/EXECUTIVE the whole organization. Filter by category, signature status, the person whose folder it is (userId), or a search over title, description and file name.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
category | enum: CONTRACT, OFFER_LETTER, SALARY_INCREMENT, PERFORMANCE_REVIEW, POLICY_DOCUMENT, ID_DOCUMENT, CERTIFICATE, TRAINING_MATERIAL, MEDICAL_CERTIFICATE, VISA_DOCUMENT, TAX_DOCUMENT, INSURANCE, TIMESHEET, OTHER | No | |
status | enum: NOT_REQUIRED, PENDING, SIGNED, DECLINED, EXPIRED | No | Signature status |
userId | string | No | Whose folder (the document's owner) |
search | string | No | Matches title, description or file name |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
delete_document
Permanently delete a document, its file and all its signing assignments (not reversible). ADMINISTRATOR/EXECUTIVE may delete any; a DEPARTMENT_HEAD only documents they sent to people in their department scope (never one HR or an administrator sent to their department); anyone, including a head, may delete a document they uploaded that has no signing assignments. Anything else is 403.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
documentId | string | Yes | Resource ID |
get_document_audit_trail
Get the audit trail for a document — views, downloads, signature events and so on, newest first. ADMINISTRATOR or EXECUTIVE for any document; a DEPARTMENT_HEAD only for a document they sent, their own, or one sent to them (never one HR sent to someone in their department); employees get 403.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
documentId | string | Yes | Resource ID |
page | integer | No | (default: 1) |
limit | integer | No | Page size (max 200) (default: 50) |
query_expiring_documents
List documents whose expiry date or signature deadline (for unsigned documents) falls within the next N days, soonest first, with days remaining and an urgency level. Visibility follows the caller: own documents for an employee; for a department head their own documents plus the ones they sent to people in their department scope (not what HR sent there); whole organization for administrators and executives. Documents the caller is still waiting to sign in a signing order are left out.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
days | integer | No | Window in days (1-365, default 60) (default: 60) |
remind_document_signers
Send a reminder notification to every signer of a document who has not signed yet (status PENDING or VIEWED). ADMINISTRATOR/EXECUTIVE for any document; a DEPARTMENT_HEAD only for documents owned by people in their department scope.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
documentId | string | Yes | Resource ID |
query_document_assignments
List document signing assignments. view "my" (default) lists the assignments sent TO the caller (WAITING ones — not yet their turn in a signing order — are hidden unless asked for by status). view "all" lists every assignment in the organization for ADMINISTRATOR/EXECUTIVE, or the ones the caller sent for a DEPARTMENT_HEAD; for anyone else it falls back to "my".
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
view | enum: my, all | No | (default: "my") |
status | enum: WAITING, PENDING, VIEWED, SIGNED, DECLINED, EXPIRED | No | |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
get_assignment_stats
Get counts of the caller's own document assignments (pending, overdue, declined and so on). Not organization-wide.
Read-only
No parameters.
assign_document
Send an existing document to up to 50 active people for signature. ADMINISTRATOR/EXECUTIVE may pick anyone in the organization and assign any document; a DEPARTMENT_HEAD only people in their department scope, only a document they sent, their own or one sent to them, and never to themselves (403). People who already have a pending assignment for the document are skipped. Refused when a person is inactive or out of scope, or the plan document quota would be exceeded. For one template sent to many people, use create_bulk_send.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
documentId | string | Yes | Resource ID |
userIds | string | Yes | User IDs to assign (max 50) |
title | string | Yes | Title the signers see |
message | string | No | Message to the signers |
dueDate | string | No | Due date (YYYY-MM-DD) |
priority | enum: LOW, NORMAL, HIGH, URGENT | No | Default NORMAL |
decline_document_assignment
Decline a signing assignment that was sent to the caller. Only the assignee can decline; a signed or already declined assignment is refused.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
assignmentId | string | Yes | Resource ID |
reason | string | No |
query_document_templates
List the current version of each document template. ADMINISTRATOR/EXECUTIVE see all; a DEPARTMENT_HEAD only templates pinned to a department in their scope; employees are refused. Archived templates are listed only when archived is true.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
category | enum: CONTRACT, OFFER_LETTER, SALARY_INCREMENT, PERFORMANCE_REVIEW, POLICY_DOCUMENT, ID_DOCUMENT, CERTIFICATE, TRAINING_MATERIAL, MEDICAL_CERTIFICATE, VISA_DOCUMENT, TAX_DOCUMENT, INSURANCE, TIMESHEET, OTHER | No | |
search | string | No | Matches name or description |
archived | boolean | No | List archived templates instead of live ones (default: false) |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
get_document_template_versions
Version history of a document template (newest first, from any version id), with how many documents were sent from each version. ADMINISTRATOR, EXECUTIVE or a DEPARTMENT_HEAD who can see the template.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
update_document_template
Rename or edit the details of the current version of a document template. Only the fields you provide are changed. The name must stay unique among live templates (case-insensitive). Old versions cannot be edited (404). To amend the PDF itself, a new version must be uploaded in the app.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
name | string | No | |
description | string or null | No | |
category | enum: CONTRACT, OFFER_LETTER, SALARY_INCREMENT, PERFORMANCE_REVIEW, POLICY_DOCUMENT, ID_DOCUMENT, CERTIFICATE, TRAINING_MATERIAL, MEDICAL_CERTIFICATE, VISA_DOCUMENT, TAX_DOCUMENT, INSURANCE, TIMESHEET, OTHER | No | |
defaultDueInDays | integer or null | No | Default days until due when sent |
archive_document_template
Archive a document template so it can no longer be sent; documents already sent are kept. Reversible with restore_document_template. ADMINISTRATOR, EXECUTIVE, or a DEPARTMENT_HEAD for a template in their scope (their "delete").
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
restore_document_template
Restore an archived document template so it can be sent again. ADMINISTRATOR or EXECUTIVE only. Refused with 409 when another live template already uses the same name.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
delete_document_template
Permanently delete a document template and its WHOLE version chain (every earlier version too). Documents already sent from it are kept. ADMINISTRATOR or EXECUTIVE only — department heads must use archive_document_template.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
send_document_from_template
Create a document from a template and send it for signature. Each signer mapping pairs a template signer role (roleIndex, from the template fields) with an active person. ADMINISTRATOR/EXECUTIVE may pick anyone; a DEPARTMENT_HEAD only people in their department scope. Refused with 409 TEMPLATE_NOT_CURRENT for an archived or replaced template version, and when the plan document quota would be exceeded.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
signerMappings | object | Yes | |
signerMappings[].roleIndex | integer | Yes | Signer role index on the template |
signerMappings[].userId | string | Yes | Person who signs that role |
title | string | No | Document title (defaults to the template name) |
message | string | No | |
dueDate | string | No | Due date (YYYY-MM-DD); defaults from the template |
query_bulk_send_jobs
List bulk send jobs (one template sent to many recipients) with their progress. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
create_bulk_send
Start a bulk send: one template sent to up to 500 recipients, each matched by email to an active person in the organization (rows without a match are reported as failures in the job, not sent). Runs in the background — check progress with query_bulk_send_jobs. ADMINISTRATOR or EXECUTIVE only. Refused with 409 TEMPLATE_NOT_CURRENT for an archived or replaced template, and when the plan document quota would be exceeded.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | Resource ID |
recipients | object | Yes | Recipients (max 500); extra string columns may be mapped to template fields |
recipients[].email | string | Yes | |
recipients[].name | string | Yes | |
name | string | No | Job name (defaults to "Bulk send - <template>") |
columnMapping | object (map) | No | Maps recipient columns to template fields |
query_document_webhooks
List webhooks subscribed to document signing events (secrets are masked). ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
create_document_webhook
Create a webhook that receives document signing events at a public HTTPS URL (max 10 per organization). The server generates the signing secret and returns it in full only in this response — tell the user to store it now. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Public HTTPS URL |
events | array of enum: document.created, document.signed, document.completed, document.declined, document.expired, document.viewed, document.reminder_sent | Yes | Event types to subscribe to |
delete_document_webhook
Delete a document webhook. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
webhookId | string | Yes | Resource ID |
Admin
94 tools.
get_org_settings
Get the org-wide general settings: name, timezone, business days, leave year start month, default annual and sick allowances, week start day, privacy toggles (calendarViewRestricted, departmentViewRestricted), carry-forward rules and probation reminders.
Read-only
No parameters.
update_org_settings
Update org-wide general settings. ADMINISTRATOR or EXECUTIVE only. Only the fields you pass change. Removing a business day deletes auto-generated scheduled shifts on that weekday from the current week onward. Currency, country and date/time formats are not settable here.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | |
timezone | string | No | IANA timezone, e.g. America/Toronto |
businessDays | array of enum: mon, tue, wed, thu, fri, sat, sun | No | |
leaveYearStartMonth | integer | No | |
defaultLeaveAllowance | number | No | |
defaultSickLeaveAllowance | number | No | |
weekStartDay | integer | No | 0 = Sunday ... 6 = Saturday |
calendarViewRestricted | boolean | No | |
departmentViewRestricted | boolean | No | When true, non-admins only see people in their own department |
carryForwardDays | number | No | |
carryForwardHours | number | No | |
carryForwardEligibilityYears | integer | No | |
carryForwardExpires | boolean | No | |
carryForwardExpiryMonths | integer or null | No | |
dashboardBalanceDisplay | enum: ANNUAL, SICK, BOTH | No | |
calendarBalanceDisplay | enum: ANNUAL, SICK, BOTH | No | |
probationRemindersEnabled | boolean | No | |
probationReminderRecipients | object | No | All four flags are required when this is set |
probationReminderRecipients.departmentHead | boolean | Yes | |
probationReminderRecipients.manager | boolean | Yes | |
probationReminderRecipients.executive | boolean | Yes | |
probationReminderRecipients.administrator | boolean | Yes |
get_branding
Get the org branding settings (brand name, light/dark logos, favicons, custom CSS).
Read-only
No parameters.
update_branding
Update org branding. EXECUTIVE only, and requires the white-label branding add-on (refused with 403 otherwise). Only the fields you pass change; pass null to clear a logo or favicon URL.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
brandName | string | No | |
logoLightUrl | string or null | No | |
logoDarkUrl | string or null | No | |
faviconUrl | string or null | No | |
faviconDarkUrl | string or null | No | |
customCSS | string or null | No |
get_email_settings
Get the org SMTP settings (host, port, user, from name/address, TLS flags). ADMINISTRATOR or EXECUTIVE only. The password is never returned.
Read-only
No parameters.
update_email_settings
Update the org custom SMTP settings. ADMINISTRATOR or EXECUTIVE only. BookYourPTO replaces the whole configuration, so this tool reads the current settings and merges your changes before saving; fields you omit keep their current values. The host must be a public mail server. smtpPassword is required when the host changes; omit it to keep the stored one.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
smtpHost | string | No | |
smtpPort | integer | No | |
smtpUser | string | No | |
smtpPassword | string | No | |
emailFromName | string | No | |
emailFromAddress | string | No | |
useSSL | boolean | No | |
useSTARTTLS | boolean | No | |
rejectUnauthorized | boolean | No |
send_test_email
Send a test email to the signed-in user through an SMTP configuration, without saving it. ADMINISTRATOR or EXECUTIVE only. Fields you omit are taken from the saved settings; the stored password is only used when the host is unchanged.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
smtpHost | string | No | |
smtpPort | integer | No | |
smtpUser | string | No | |
smtpPassword | string | No | |
emailFromName | string | No | |
emailFromAddress | string | No | |
useSSL | boolean | No | |
useSTARTTLS | boolean | No | |
rejectUnauthorized | boolean | No |
delete_email_settings
Remove the org custom SMTP configuration so email goes through the platform mail server. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
No parameters.
get_notification_defaults
Get the org-wide notification defaults (digests, product updates, digest scope) and the maximum digest scope employees may choose. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
update_notification_defaults
Update the org-wide notification defaults that apply to anyone who has not set their own. ADMINISTRATOR or EXECUTIVE only. BookYourPTO stores the whole object, so this tool reads the current defaults and merges your changes; fields you omit keep their values. Set reset=true to return to the system defaults.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
productUpdates | boolean | No | |
dailyDigest | object | No | Daily digest email. hourOfDay is 0-23 in the recipient timezone. |
dailyDigest.enabled | boolean | No | |
dailyDigest.hourOfDay | integer | No | |
weeklyDigest | object | No | Weekly digest email. dayOfWeek is 0 (Sunday) to 6 (Saturday). |
weeklyDigest.enabled | boolean | No | |
weeklyDigest.hourOfDay | integer | No | |
weeklyDigest.dayOfWeek | integer | No | |
publicHolidaysOnDigest | boolean | No | |
digestScope | enum: self, department, managed, organization | No | |
documents | object | No | |
documents.uploaded | boolean | No | |
documents.expiring | boolean | No | |
birthdayGreeting | boolean | No | |
requestAlerts | enum: all, routed | No | |
maxDigestScope | enum: organization, department, self | No | Widest digest scope a non-admin may choose |
reset | boolean | No | Discard all customisation and use the system defaults |
get_personal_notifications
Get the signed-in user notification preferences (digests, digest scope, alerts) and the widest digest scope they may choose.
Read-only
No parameters.
update_personal_notifications
Update the signed-in user notification preferences. Any role. BookYourPTO stores the whole object, so this tool reads the current preferences and merges your changes. A digestScope wider than the org allows (or "managed" with no direct reports) is refused with 403. Set reset=true to fall back to the org defaults.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
productUpdates | boolean | No | |
dailyDigest | object | No | Daily digest email. hourOfDay is 0-23 in the recipient timezone. |
dailyDigest.enabled | boolean | No | |
dailyDigest.hourOfDay | integer | No | |
weeklyDigest | object | No | Weekly digest email. dayOfWeek is 0 (Sunday) to 6 (Saturday). |
weeklyDigest.enabled | boolean | No | |
weeklyDigest.hourOfDay | integer | No | |
weeklyDigest.dayOfWeek | integer | No | |
publicHolidaysOnDigest | boolean | No | |
digestScope | enum: self, department, managed, organization | No | |
documents | object | No | |
documents.uploaded | boolean | No | |
documents.expiring | boolean | No | |
birthdayGreeting | boolean | No | |
requestAlerts | enum: all, routed | No | |
reset | boolean | No | Discard personal preferences and use the org defaults |
get_sso_settings
Get the org SSO (Auth0) configuration. The client secret is never returned, only whether one is set.
Read-only
No parameters.
update_sso_settings
Update SSO (Auth0) settings. EXECUTIVE only, and requires a plan with SSO. Only the fields you pass change. Misconfiguration can lock people out. Auto-created users can start only as EMPLOYEE or DEPARTMENT_HEAD. Public email domains (gmail.com etc.) are refused in allowedDomains, which replaces the whole list when passed.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | |
auth0Domain | string or null | No | |
auth0ClientId | string or null | No | |
auth0ClientSecret | string or null | No | Pass null to clear the stored secret |
enableGoogle | boolean | No | |
enableMicrosoft | boolean | No | |
enableGitHub | boolean | No | |
enableSAML | boolean | No | |
allowLocalLogin | boolean | No | |
enforceSSO | boolean | No | |
autoCreateUsers | boolean | No | |
defaultRole | enum: EMPLOYEE, DEPARTMENT_HEAD | No | |
defaultDepartmentId | string or null | No | |
allowedDomains | string | No |
query_sso_domains
List SSO domains for the org with their DNS verification status and the TXT record to publish. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
add_sso_domain
Add a domain to the SSO allow-list; returns the DNS TXT record to publish before verifying. ADMINISTRATOR or EXECUTIVE only. Public email domains and domains verified by another org are refused.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | Yes |
verify_sso_domain
Check DNS for the verification TXT record of an SSO domain. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
delete_sso_domain
Remove a domain from the SSO allow-list. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
get_slack_integration
Get the org Slack integration: webhookUrl and enabledNotificationTypes. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
update_slack_integration
Update the org Slack integration. ADMINISTRATOR or EXECUTIVE only. The webhook URL must start with https://hooks.slack.com/. Fields you omit keep their current values, including the webhook URL when you change only the notification types. Pass webhookUrl: null to disconnect. enabledNotificationTypes replaces the whole list of events posted to the channel.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
webhookUrl | string or null | No | null disconnects the integration |
enabledNotificationTypes | array of enum: LEAVE_SUBMITTED, LEAVE_APPROVED, LEAVE_REJECTED, LEAVE_CANCELLED, EXPENSE_SUBMITTED, EXPENSE_APPROVED, EXPENSE_REJECTED, EXPENSE_PAID, TIME_ENTRY_APPROVED, TIME_ENTRY_REJECTED, DOCUMENT_UPLOADED, DOCUMENT_SIGNED, APPROVAL_REQUIRED, SYSTEM_ANNOUNCEMENT | No |
test_slack_integration
Post a test message to a Slack webhook. ADMINISTRATOR or EXECUTIVE only. Uses the saved org webhook unless webhookUrl is given. Fails with 400 when the message cannot be delivered.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
webhookUrl | string | No |
get_teams_integration
Get the org Microsoft Teams integration: webhookUrl and enabledNotificationTypes. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
update_teams_integration
Update the org Microsoft Teams integration. ADMINISTRATOR or EXECUTIVE only. The webhook URL must be a Teams incoming webhook or Power Automate workflow URL. Fields you omit keep their current values, including the webhook URL when you change only the notification types. Pass webhookUrl: null to disconnect. enabledNotificationTypes replaces the whole list of events posted to the channel.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
webhookUrl | string or null | No | null disconnects the integration |
enabledNotificationTypes | array of enum: LEAVE_SUBMITTED, LEAVE_APPROVED, LEAVE_REJECTED, LEAVE_CANCELLED, EXPENSE_SUBMITTED, EXPENSE_APPROVED, EXPENSE_REJECTED, EXPENSE_PAID, TIME_ENTRY_APPROVED, TIME_ENTRY_REJECTED, DOCUMENT_UPLOADED, DOCUMENT_SIGNED, APPROVAL_REQUIRED, SYSTEM_ANNOUNCEMENT | No |
test_teams_integration
Post a test message to a Microsoft Teams webhook. ADMINISTRATOR or EXECUTIVE only. Uses the saved org webhook unless webhookUrl is given. Fails with 400 when the message cannot be delivered.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
webhookUrl | string | No |
get_personal_integrations
Get the signed-in user personal Slack and Teams webhook URLs (where their own notifications are posted). Any role.
Read-only
No parameters.
update_personal_integrations
Set or clear the signed-in user personal Slack and Teams webhook URLs. Any role. BookYourPTO clears any URL it is not sent, so this tool reads the current values first; a field you omit keeps its value and null clears it.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
slackWebhookUrl | string or null | No | Must start with https://hooks.slack.com/; null clears |
teamsWebhookUrl | string or null | No | Teams webhook or Power Automate URL; null clears |
query_audit_logs
Query the org-wide audit log, newest first. ADMINISTRATOR or EXECUTIVE only, and requires a plan with audit logs. Filter by action, entity type, acting user or date range (dates are inclusive calendar days). Use this for "who changed X?" / "what happened on Y?" investigations.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | No | e.g. CREATE, UPDATE, DELETE, SETTINGS_CHANGE, EXPORT, LOGIN |
entityType | string | No | e.g. USER, ORGANIZATION, LEAVE, EXPENSE_REPORT, DOCUMENT |
userId | string | No | The user who performed the action |
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
export_audit_logs
Export the audit log for a date range (inclusive). ADMINISTRATOR or EXECUTIVE only. Returns the entries inline as JSON (default, at most 500 shown) or the CSV text. The export only filters by date; use query_audit_logs to filter by action, entity or user.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
format | enum: json, csv | No | (default: "json") |
query_signin_logs
Query sign-in attempts, newest first. ADMINISTRATOR or EXECUTIVE only. Filter by user, email (substring), IP (substring), success, or date range (inclusive). Useful for security investigations.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | |
email | string | No | Case-insensitive substring of the email used |
ipAddress | string | No | Substring of the client IP |
success | boolean | No | Filter by successful or failed sign-ins |
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
export_signin_logs
Export sign-in logs for a date range (inclusive). ADMINISTRATOR or EXECUTIVE only. Returns the entries inline as JSON (default, at most 500 shown) or the CSV text.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
format | enum: json, csv | No | (default: "json") |
query_leave_transactions
Query the history of leave requests across the org (who requested what, status, approver), newest first. ADMINISTRATOR or EXECUTIVE only. The date range filters on when the request was submitted (inclusive). This is the request log, not a balance ledger.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | |
status | enum: PENDING, APPROVED, REJECTED, CANCELLED, WITHDRAWN | No | |
leaveTypeId | string | No | |
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
query_time_tracking_transactions
Query time entries across the org with their source and approval status, newest first. ADMINISTRATOR or EXECUTIVE only. The date range filters on clock-in day (inclusive).
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userName | string | No | Case-insensitive substring of the first or last name |
source | enum: MANUAL, CLOCK, IMPORT, API | No | |
approvalStatus | enum: PENDING, APPROVED, REJECTED | No | |
startDate | string | No | Date in YYYY-MM-DD format |
endDate | string | No | Date in YYYY-MM-DD format |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
query_security_violations
List recorded security violations (for example forced sign-outs after an invalid token), newest first. ADMINISTRATOR or EXECUTIVE only. Filter by whether they have been reviewed.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
reviewed | boolean | No | |
limit | integer | No | (default: 50) |
offset | integer | No | (default: 0) |
update_security_violation
Mark a security violation as reviewed (or not) and attach review notes. ADMINISTRATOR or EXECUTIVE only. Records the caller as the reviewer.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
violationId | string | Yes | Resource ID |
reviewed | boolean | No | |
notes | string | No |
query_phi_access_log
Query the PHI (protected health information) access log, newest first. ADMINISTRATOR or EXECUTIVE only. Filter by the person whose record was accessed (userId) or by resource type. No date filter is available.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | The person whose health record was accessed (not the accessor) |
resourceType | string | No | |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
get_subscription
Get the current subscription status (plan, seats, billing period, trial info, pending cancellation).
Read-only
No parameters.
change_plan
Switch the active paid subscription to another plan or billing interval (Stripe prorates the change). ADMINISTRATOR or EXECUTIVE only. Only pro and business can be chosen here; Enterprise is arranged by sales. Requires an existing subscription; use create_checkout_session to start one.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
plan | enum: pro, business | Yes | |
interval | enum: monthly, yearly | Yes | |
currency | enum: USD, CAD | Yes |
cancel_subscription
Cancel the subscription. ADMINISTRATOR or EXECUTIVE only. By default it cancels at the end of the current billing period (reversible with reactivate_subscription until then). immediately=true ends it now with no refund and cannot be reactivated.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
immediately | boolean | No | End the subscription now instead of at period end (default: false) |
reactivate_subscription
Undo a pending cancel-at-period-end before the period ends. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
No parameters.
sync_subscription
Re-read the subscription state from Stripe into the org (recovery after a missed webhook). ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
No parameters.
get_usage
Get current resource usage (users, documents, receipts, projects, expense claims) against plan limits.
Read-only
No parameters.
get_usage_breakdown
Get usage attribution per user (who uploaded what, who signed what, etc.). ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
query_invoices
List the org invoices, newest first. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
get_invoice_line_items
Get line items for a specific invoice. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
invoiceId | string | Yes | Resource ID |
request_refund
Submit a refund request for review by the BookYourPTO team; nothing is refunded automatically. ADMINISTRATOR or EXECUTIVE only. invoiceId must be a PAID invoice of this org. amount is in cents; omit it for a full refund. Refused while another request from the org is still pending.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
invoiceId | string | No | |
amount | integer | No | Amount in cents; omit for a full refund |
reason | string | Yes |
query_refund_requests
List the org refund requests with their status, newest first. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
status | enum: PENDING, APPROVED, DENIED, PROCESSED | No | |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
get_billing_alerts
Get active billing alerts (trial ending, payment failed, near a plan limit). Returns an empty list for roles below ADMINISTRATOR.
Read-only
No parameters.
query_addons
List add-ons (currently white-label branding) and whether the org has them, including any end date after removal.
Read-only
No parameters.
toggle_addon
Add or remove an add-on on the active subscription. ADMINISTRATOR or EXECUTIVE only. Adding charges immediately; during a trial it is refused with 409 unless skipTrial=true, which ends the trial and starts paid billing now. Removing keeps the feature until the end of the paid period, with no refund.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
addOn | enum: whiteLabelBranding | Yes | |
action | enum: add, remove | Yes | |
skipTrial | boolean | No | Required to add during a trial; ends the trial |
create_checkout_session
Create a Stripe Checkout link for starting a paid subscription. ADMINISTRATOR or EXECUTIVE only. The plan is a single line item, so there is no seat count. A trial may apply if the org has not trialled before. Returns a URL the user must open to pay.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
plan | enum: pro, business | Yes | |
interval | enum: monthly, yearly | No | (default: "monthly") |
currency | enum: USD, CAD | No | Defaults to CAD on the server |
couponCode | string | No | |
addOns | array of enum: whiteLabelBranding | No |
create_billing_portal_session
Create a Stripe customer portal link for self-service billing (payment method, invoices). ADMINISTRATOR or EXECUTIVE only.
Write
No parameters.
validate_coupon
Check whether a coupon code is valid and what it gives, without applying it.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes |
get_quickbooks_status
Check whether QuickBooks Online is connected for the org. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
connect_quickbooks
Get the QuickBooks Online authorization URL (authUrl) to start the connection; the user must open it in a browser. ADMINISTRATOR or EXECUTIVE only. Requires a plan with the QuickBooks integration.
Read-only
No parameters.
disconnect_quickbooks
Disconnect QuickBooks Online and stop all syncing. ADMINISTRATOR or EXECUTIVE only.
Destructive · Risk: high
No parameters.
get_quickbooks_settings
Get the QuickBooks sync settings (what syncs, auto-sync, default expense and payment accounts). ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
update_quickbooks_settings
Update QuickBooks sync settings. ADMINISTRATOR or EXECUTIVE only. Only the fields you pass change; an empty string clears an account. Refused with 404 when QuickBooks is not connected. Account ids come from query_quickbooks_accounts.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
syncExpenses | boolean | No | |
syncTimeEntries | boolean | No | |
syncEmployees | boolean | No | |
autoSync | boolean | No | |
defaultExpenseAccountId | string | No | |
defaultExpenseAccountName | string | No | |
paymentAccountId | string | No | Bank / credit card account bills are paid from |
paymentAccountName | string | No |
query_quickbooks_accounts
List the QuickBooks chart of accounts (qboAccounts), bank accounts, and the local expense categories that can be mapped to them. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
get_qb_account_mappings
Get the expense category to QuickBooks account mappings. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
update_qb_account_mappings
Save expense category to QuickBooks account mappings. ADMINISTRATOR or EXECUTIVE only. Each entry needs the local category name and the QuickBooks account id and name (from query_quickbooks_accounts).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
mappings | object | Yes | |
mappings[].localCategory | string | Yes | |
mappings[].qboAccountId | string | Yes | |
mappings[].qboAccountName | string | Yes |
query_quickbooks_customers
List QuickBooks customers (qboCustomers) alongside local clients and projects. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
sync_qb_customers
Push local clients and/or projects to QuickBooks as customers. ADMINISTRATOR or EXECUTIVE only. Writes into the customer's QuickBooks company.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
type | enum: clients, projects, both | No | (default: "both") |
sync_employees_to_quickbooks
Sync employees between BookYourPTO and QuickBooks: "push" sends linked people to QuickBooks, "pull" brings QuickBooks changes back, "both" (default) does each. createUnmatched=true also creates QuickBooks employees for everyone not yet linked. ADMINISTRATOR or EXECUTIVE only.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
direction | enum: push, pull, both | No | (default: "both") |
createUnmatched | boolean | No | (default: false) |
get_qb_employee_mappings
Get the BookYourPTO user to QuickBooks employee links. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
sync_expenses_to_quickbooks
Push every approved expense report not yet synced to QuickBooks as bills. ADMINISTRATOR or EXECUTIVE only. There is no date filter; it processes the whole unsynced backlog.
Write · Risk: medium
No parameters.
get_expense_sync_status
How many approved expense reports are synced vs unsynced, plus recent sync logs. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
sync_time_to_quickbooks
Push every approved time entry not yet synced to QuickBooks as time activities. ADMINISTRATOR or EXECUTIVE only. There is no date filter; it processes the whole unsynced backlog.
Write · Risk: medium
No parameters.
preview_leave_liability
Preview the accrued leave liability that sync_leave_liability would post. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
sync_leave_liability
Post the leave liability as a journal entry in QuickBooks, debiting the expense account and crediting the liability account. ADMINISTRATOR or EXECUTIVE only. Both account ids are required (from query_quickbooks_accounts).
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
expenseAccountId | string | Yes | |
liabilityAccountId | string | Yes |
get_quickbooks_payroll_summary
Get the payroll summary per linked employee from QuickBooks. ADMINISTRATOR or EXECUTIVE only. No date filter is available.
Read-only
No parameters.
get_quickbooks_sync_history
List QuickBooks sync log entries, newest first, optionally filtered by entity type, status or direction. ADMINISTRATOR or EXECUTIVE only.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
entityType | enum: EMPLOYEE, TIME_ACTIVITY, BILL, VENDOR, DEPARTMENT, JOURNAL_ENTRY, CUSTOMER, ACCOUNT | No | |
status | enum: SUCCESS, FAILED, SKIPPED, PARTIAL | No | |
direction | enum: PUSH, PULL, BIDIRECTIONAL | No | |
page | integer | No | Page number (1-indexed) (default: 1) |
limit | integer | No | Page size (max 100) (default: 25) |
change_password
Change the signed-in user password. Requires the current password. The new password must meet the org password policy, must not appear in known breaches and must differ from the current one. It signs out every other session of this account, which can include the session this assistant uses; you may need to reconnect afterwards.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
currentPassword | string | Yes | |
newPassword | string | Yes |
check_password_breach
Check whether a candidate password appears in known data breaches (k-anonymity lookup; the password itself is not sent to the breach service). Returns only { breached }. Passwords shorter than 8 characters, and rate-limited calls, always report breached: false.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
password | string | Yes |
setup_totp
Begin TOTP two-factor setup for the signed-in user. Returns a QR code data URL, the base32 secret and one-time backup codes; finish with confirm_totp. Refused if 2FA is already on.
Write
No parameters.
confirm_totp
Finish TOTP two-factor setup with the first 6-digit code from the authenticator app. It signs out every other session of this account, which can include the session this assistant uses; you may need to reconnect afterwards.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes |
disable_totp
Turn off TOTP two-factor for the signed-in user and revoke all their trusted devices. Requires the current password; not available to OAuth-only accounts.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
password | string | Yes |
query_trusted_devices
List devices trusted to skip the 2FA prompt for the signed-in user, marking the current one.
Read-only
No parameters.
revoke_trusted_device
Revoke a single trusted device of the signed-in user.
Destructive · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
deviceId | string | Yes | Resource ID |
revoke_all_trusted_devices
Revoke all trusted devices of the signed-in user. Every device must pass 2FA again on next sign-in.
Destructive · Risk: high
No parameters.
reset_user_2fa
Reset another user's two-factor: clears their TOTP secret, backup codes and trusted devices. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE can reset an executive. Refused if the user has no 2FA.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
resend_credentials
Send a user a password-reset link (valid 1 hour) and sign them out of every session. ADMINISTRATOR or EXECUTIVE only; only an EXECUTIVE can do this for an executive. Reports whether the email was sent. The reset link itself is never returned (it is a credential for another person, and this conversation is stored); if the email was not sent, send the reset again from the Users page in BookYourPTO.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | BookYourPTO user ID |
request_data_export
Export all personal data the product holds about the signed-in user, returned inline as JSON. Covers only the caller; there is no way to export another person here. Rate limited.
Write
No parameters.
request_deletion_code
Email the signed-in user a 6-digit code that confirms deleting their own account (request_data_deletion) or, for an executive, the organization. Rate limited to a couple of emails every two minutes.
Write · Risk: medium
No parameters.
request_data_deletion
Permanently anonymize a user's account (right to erasure); audit history is kept. Cannot be undone. Deleting your own account needs the emailed code from request_deletion_code. Deleting someone else needs ADMINISTRATOR or EXECUTIVE (no code); only an EXECUTIVE can delete an executive. Refused for the last active executive or the last administrator.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Person to delete; omit for yourself |
code | string | No | 6-digit code; required when deleting yourself |
confirmDeletion | literal: true | Yes | Must be true; guards against accidental deletion |
opt_out_of_processing
Set whether the signed-in user opts out of sharing their data (the doNotShareData privacy flag). optOut=false opts back in. Logged in the audit trail.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
optOut | boolean | No | (default: true) |
query_domains
List custom domains configured for the org (white-label), with status and branding. ADMINISTRATOR or EXECUTIVE only.
Read-only
No parameters.
get_domain
Get one custom domain: verification and SSL status, DNS records to publish, and its branding.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
add_custom_domain
Add a custom domain (e.g. hr.acme.com) with the brand shown on it. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise). Returns the DNS records to configure before verify_domain.
Write · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Fully qualified domain, e.g. hr.acme.com |
brandName | string | Yes | Name shown on the branded login and app |
primaryColor | string | No | Hex colour; defaults to #3B82F6 |
update_custom_domain_branding
Update the branding served on a custom domain (logos, colours, login page, footer, support links, email sender, custom CSS) or make it the primary domain. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise). Only the fields you pass change; null clears a field.
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
brandName | string | No | |
tagline | string or null | No | |
logoLightUrl | string or null | No | |
logoDarkUrl | string or null | No | |
logoLoginUrl | string or null | No | |
faviconUrl | string or null | No | |
faviconDarkUrl | string or null | No | |
appleTouchIcon | string or null | No | |
primaryColor | string | No | |
primaryHover | string | No | |
accentColor | string or null | No | |
loginBackground | string or null | No | |
loginWelcomeText | string or null | No | |
hidePoweredBy | boolean | No | |
footerText | string or null | No | |
privacyPolicyUrl | string or null | No | |
termsOfServiceUrl | string or null | No | |
supportEmail | string or null | No | |
supportUrl | string or null | No | |
emailFromName | string or null | No | |
emailFromAddress | string or null | No | |
emailLogoUrl | string or null | No | |
emailFooterText | string or null | No | |
customCSS | string or null | No | |
isPrimary | boolean | No | Make this the primary domain (unsets the others) |
verify_domain
Check DNS for a custom domain's verification records. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
request_domain_ssl
Manage the SSL certificate of a verified custom domain: "provision" requests one (default), "check" reports its status, "refresh" re-issues it. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise).
Write · Risk: medium
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
action | enum: check, provision, refresh | No | (default: "provision") |
get_domain_dns_provider
Detect the DNS provider of a custom domain (Cloudflare, Route 53, etc.) to tailor DNS instructions.
Read-only
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
delete_custom_domain
Remove a custom domain from the org; its branding stops being served there. ADMINISTRATOR or EXECUTIVE only, and changes require the white-label branding add-on (refused with 403 otherwise).
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
domainId | string | Yes | Resource ID |
create_support_ticket
Open a ticket with the BookYourPTO support team, filed under the signed-in user. ADMINISTRATOR or EXECUTIVE only (403 for anyone else — ask an administrator to open it); at most 5 per 10 minutes. title is 5-200 characters and every text field below needs at least 10 characters. Required fields by type: blank = description; bug = description, stepsToReproduce, expectedBehavior; feature = problemDescription, desiredSolution; security = summary, vulnerabilityDetails, impact, affectedArea, severity.
Write
| Parameter | Type | Required | Description |
|---|---|---|---|
type | enum: blank, bug, feature, security | Yes | |
title | string | Yes | |
description | string | No | |
stepsToReproduce | string | No | |
expectedBehavior | string | No | |
desktopInfo | string | No | |
problemDescription | string | No | |
desiredSolution | string | No | |
alternativesConsidered | string | No | |
summary | string | No | |
vulnerabilityDetails | string | No | |
proofOfConcept | string | No | |
impact | string | No | |
affectedArea | enum: Web App, API, Authentication, Data, Other | No | |
severity | enum: Critical, High, Medium, Low | No | |
cweId | string | No | |
additionalContext | string | No |
System
1 tool.
get_health
Check the MCP server health: API connectivity, auth status, cache size, and uptime.
Read-only
No parameters.
Auth
1 tool.
This tool is registered only when a self-hosted server runs in per-user mode (no OAuth, no shared credentials). OAuth connections never see it.
login
Exchange BookYourPTO email + password for an access token on this connection. Required only when running in per-user mode (no OAuth, no shared credentials). An organization that requires single sign-on refuses password sign-in here (SSO_REQUIRED); instead, sign in to BookYourPTO with SSO in your browser and connect through OAuth, which authorizes the session you are already signed in to.
Destructive · Risk: high
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | BookYourPTO account email |
password | string | Yes | BookYourPTO account password |