Jump to Content

Object Overview

The PTO Request Object

A PTO request represents a paid time off request submitted by or on behalf of an employee. Each request is tied to a specific PTO policy, covers a date range, and progresses through statuses (pending, approved, denied, or canceled).

PTO endpoints require a premium plan.

Returned by

Endpoint	Shape
`GET /pto/requests`	List of PTO requests
`POST /pto/requests`	Created PTO request
`POST /pto/requests/:pto_request_id/approve`	Updated PTO request
`POST /pto/requests/:pto_request_id/deny`	Updated PTO request

Field Reference

Core fields

Field	Type	Description
`pto_request_id`	integer	Unique PTO request identifier.
`employee_id`	integer	The employee this request belongs to.
`company_id`	integer	The company this request belongs to.
`policy_id`	integer \| null	The PTO policy this request was filed under.
`pto_type`	string	The type of PTO (e.g. `"vacation"`, `"sick"`, `"holiday"`, `"pto"`). Derived from the policy.
`status`	string	Current request status. See Statuses below.
`message`	string \| null	Optional message or reason from the employee.

Date fields

All date fields are normalized to YYYY-MM-DD format (date-only, no timestamp).

Field	Type	Description
`pto_start`	string \| null	Start date of the requested time off.
`pto_end`	string \| null	End date of the requested time off.
`created_at`	string \| null	Date the request was created.
`approved_at`	string \| null	Date the request was approved. Null if not yet approved.

Breakdown

Field	Type	Description
`pto_dates_and_hours`	array	Per-day breakdown of PTO hours. Each entry has `date` (string, `YYYY-MM-DD`) and `hours` (number).

Nested objects

Field	Type	Description
`employee`	object	Employee summary: `employee_id`, `first_name`, `last_name`, `nickname`.
`policy`	object \| null	Policy summary: `policy_id`, `name`, `policy_type`, `is_unlimited`.

Statuses

Value	Description
`"pending"`	Awaiting approval.
`"approved"`	Approved by a manager or admin.
`"denied"`	Denied by a manager or admin.
`"canceled"`	Canceled by the employee or system.

Example

{
  "pto_request_id": 7001,
  "employee_id": 42,
  "company_id": 11,
  "policy_id": 5,
  "pto_type": "vacation",
  "pto_start": "2026-03-20",
  "pto_end": "2026-03-22",
  "created_at": "2026-03-17",
  "status": "pending",
  "approved_at": null,
  "message": "Family trip",
  "pto_dates_and_hours": [
    { "date": "2026-03-20", "hours": 8 },
    { "date": "2026-03-21", "hours": 8 },
    { "date": "2026-03-22", "hours": 4 }
  ],
  "employee": {
    "employee_id": 42,
    "first_name": "Avery",
    "last_name": "Taylor",
    "nickname": "Ave"
  },
  "policy": {
    "policy_id": 5,
    "name": "Vacation",
    "policy_type": "vacation",
    "is_unlimited": false
  }
}

The PTO Balance Object

A PTO balance object shows an employee's accrued, used, pending, and available PTO hours broken down by policy. The balance is computed server-side from accrual records and approved/pending PTO requests.

PTO endpoints require a premium plan.

Returned by

Endpoint	Shape
`GET /pto/balances`	List of employee balance objects
`GET /pto/balances/:employee_id`	Single employee balance object

Field Reference

Employee summary fields

Field	Type	Description
`employee_id`	integer	Unique employee identifier.
`first_name`	string	Employee's first name.
`last_name`	string	Employee's last name.
`nickname`	string \| null	Preferred name / display name.

Balance array

Field	Type	Description
`balances`	array	List of per-policy balance entries. See Policy Balance.

Nested Objects

Policy Balance

Field	Type	Description
`policy_id`	integer	PTO policy identifier.
`policy_name`	string \| null	Policy name (e.g. `"Vacation"`, `"Sick Leave"`).
`policy_type`	string \| null	Policy type (e.g. `"vacation"`, `"sick"`, `"holiday"`).
`is_unlimited`	boolean	Whether this policy has unlimited PTO.
`accrued_hours`	number	Total hours accrued to date.
`used_hours`	number	Total hours used (from approved requests).
`pending_hours`	number	Total hours in pending (not yet approved) requests.
`available_hours`	number \| null	Available balance: `accrued_hours - used_hours`. Null for unlimited policies.
`as_of`	string	Date this balance was computed (`YYYY-MM-DD`).

Example

{
  "employee_id": 42,
  "first_name": "Avery",
  "last_name": "Taylor",
  "nickname": "Ave",
  "balances": [
    {
      "policy_id": 5,
      "policy_name": "Vacation",
      "policy_type": "vacation",
      "is_unlimited": false,
      "accrued_hours": 56,
      "used_hours": 16,
      "pending_hours": 8,
      "available_hours": 40,
      "as_of": "2026-03-17"
    },
    {
      "policy_id": 8,
      "policy_name": "Sick Leave",
      "policy_type": "sick",
      "is_unlimited": true,
      "accrued_hours": 0,
      "used_hours": 4,
      "pending_hours": 0,
      "available_hours": null,
      "as_of": "2026-03-17"
    }
  ]
}