Calculate team PTO balances
calculate_team_pto_balancesRead-onlyIdempotent
Use this when an owner or HR person wants PTO balances for a team: one PTO, vacation or sick leave balance per employee from one accrual policy (accrual_amount + accrual_unit + accrual_per, e.g. 15, days, year) and a list of employees (typed, pasted CSV, or an attached CSV/Excel file with name, hire date, starting balance, hours used). Applies the same policy options as calculate_pto_balance (per hour worked, per pay period, annual front-loaded or accrued, tenure tiers, caps, carryover and reset, waiting period). Returns each person's balance, hours used this year, year-end projection and hours at risk at the reset, team totals, and PDF, Excel (with each person's ledger) and CSV files. Does not give legal advice, process payroll, or compute PTO payout in money. For one person's dated ledger use calculate_pto_balance.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pay_date | No | Any real payday for weekly or biweekly pay, e.g. 2026-01-09, so accruals land on the right Fridays. Default: the first Friday on or after the ledger start. | |
| employees | No | The team: a list of employees, or CSV text with a header such as "name,hire_date,starting_balance,used_hours" and one row per person. Up to 500. | |
| hire_date | No | Hire (start) date, e.g. 2024-03-04. Used for tenure tiers, the waiting period and the first partial pay period. | |
| as_of_date | No | Date to report the balance on, e.g. 2026-10-26. Default: today in US Eastern time. | |
| first_year | No | For annual_front_loaded: prorated (default, first grant prorated by days left in the year) or full. | |
| reset_date | No | When the accrual year resets (carryover is applied), e.g. "01-01" (default January 1), "July 1", or "anniversary" (hire anniversary), or "none". | |
| accrual_per | No | How often accrual_amount is earned: year, month, week, pay_period, or hour_worked. Required for hours; days or weeks without it are read as per year. | |
| annual_days | No | Days of PTO per year, e.g. 15. Converted with hours_per_day (default 8). | |
| max_balance | No | Maximum balance (accrual stops at this cap until hours are used), in hours, e.g. 240, or "30 days". | |
| accrual_rate | No | Fallback only, when you cannot fill accrual_amount/accrual_unit/accrual_per: the rule as text with a number, unit and period, e.g. "1 per 30", "4.62 hours per paycheck", "15 days a year". Hours without a period are refused. | |
| accrual_unit | No | Unit of accrual_amount: hours (default), days, or weeks (weeks = days_per_week x hours_per_day). | |
| annual_hours | No | Hours of PTO per year, e.g. 120. Use instead of annual_days. | |
| hours_worked | No | Actual hours worked per pay period for per_hour_worked, e.g. [{"date":"2026-01-09","hours":72}] or "2026-01-09: 72, 2026-01-23: 80". Periods not listed use the standard hours. | |
| tenure_tiers | No | Tenure tiers (years of service), as text "0-2: 10 days, 3-5: 15 days, 6+: 20 days" or a list [{"from_year":0,"annual_days":10},{"from_year":3,"annual_days":15}]. "years 3-5" starts at the 3rd work anniversary. | |
| days_per_week | No | Workdays per week, default 5. Converts weeks of PTO to hours. | |
| hours_per_day | No | Hours in one PTO day, default 8, e.g. 7.5. | |
| pay_frequency | No | Pay schedule: weekly, biweekly (default, every two weeks), semimonthly (15th and last day), or monthly. | |
| accrual_amount | No | Preferred way to give the rule: the amount earned, e.g. 15 (with accrual_unit days, accrual_per year), 4.62 (hours per pay_period) or 0.0333 (hours per hour_worked). | |
| accrual_method | No | How PTO is earned: per_hour_worked (e.g. 1 h per 30 h worked), per_pay_period (fixed hours each paycheck, e.g. 4.62 h), annual_front_loaded (whole year granted at once on the reset date), annual_accrued_per_period (yearly amount, e.g. 15 days, spread evenly over pay periods). Optional: inferred from the other fields. | |
| employees_file | No | Optional CSV or Excel (.xlsx) file of employees with columns like name, hire date, starting balance, hours used, e.g. team-pto.csv. | |
| hours_per_week | No | Standard hours per week, default 40, e.g. 30 for part time. Used when hours worked are not given. | |
| waiting_period | No | Waiting period after hire before PTO can be used, e.g. "90 days" or "3 months". | |
| carryover_limit | No | Hours that may roll over at the reset date, e.g. 40. 0 = use it or lose it. Leave out for unlimited rollover. | |
| starting_balance | No | Known balance on starting_balance_date, in hours, e.g. 32.5 (from a pay stub), or "4 days". | |
| annual_accrual_cap | No | Most hours that can be earned in one accrual year, e.g. 48. | |
| waiting_period_rule | No | accrue_but_locked (default: hours accrue from hire but cannot be used until the waiting period ends) or no_accrual (nothing accrues during the waiting period). | |
| starting_balance_date | No | Date of the starting balance, e.g. 2026-01-01. Default: the start of the current accrual year (or the hire date if later). | |
| hours_worked_per_period | No | Hours worked in each pay period, for per_hour_worked when it differs from the standard (40 h/week), e.g. 64. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| as_of | Yes | ||
| notes | Yes | ||
| policy | Yes | ||
| totals | Yes | ||
| warnings | Yes | ||
| downloads | Yes | ||
| employees | Yes | ||
| reset_date | Yes | ||
| as_of_label | Yes | ||
| assumptions | Yes | ||
| source_file | Yes | ||
| as_of_source | Yes | ||
| employees_total | Yes | ||
| projection_through | Yes |