Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Time Off Requests

List time off requests for a company

Get all time off requests for a company. Supports filtering by status, employee, and date ranges.

Possible statuses:

  • pending — awaiting approval
  • approved — approved by an admin but not yet processed in a payroll
  • declined — declined by an admin
  • consumed — processed in a completed payroll

Allowed values for status: pending, approved, declined, consumed.

scope: time_off_requests:read

get/v1/companies/{company_uuid}/time_off/requests

Path parameters

company_uuidstring required

The UUID of the company

Query parameters

employee_uuidsstring

Filter by employee UUIDs. Comma-separated for multiple values.

statusstring

Filter by request status. Comma-separated for multiple values (e.g. pending,approved,declined,consumed).

start_datestring

Filter requests that overlap with this start date

end_datestring

Filter requests that overlap with this end date

sort_orderstring

Sort order by start_date (asc or desc, defaults to desc)

pageinteger

The page that is requested

perinteger

Number of objects per page

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Response

successful

uuidstring required

The UUID of the time off request.

status'pending' | 'approved' | 'declined' | 'consumed' required

The status of the time off request.

employee_notestring nullable required

A note about the time off request, from the employee to the employer.

employer_notestring nullable required

A note about the time off request, from the employer to the employee.

policy_typestring nullable required

The type of the time off policy (e.g. vacation, sick).

policy_uuidstring nullable required

The UUID of the time off policy associated with this request.

daysobject required

An object where keys are dates in YYYY-MM-DD format and values are hours as string decimals (e.g. {"2025-01-20": "8.000"}).

Example response

[
  {
    "uuid": "ad158cfb-99e4-4741-9db3-0bd3a267f222",
    "status": "pending",
    "employee_note": "Family vacation",
    "policy_type": "vacation",
    "policy_uuid": "c2d9b1bd-3f36-4c2d-a727-b2af057d6a7f",
    "days": {
      "2026-10-20": "8.000",
      "2026-10-21": "8.000"
    },
    "employee": {
      "uuid": "51924fa0-26c6-4d4c-8832-3ef0b422c67e",
      "full_name": "Alex Johnson"
    },
    "initiator": {
      "uuid": "51924fa0-26c6-4d4c-8832-3ef0b422c67e",
      "full_name": "Alex Johnson"
    },
    "approver": {
      "uuid": "21d8dff4-ce09-4120-a274-3a5628bf6769",
      "full_name": "Morgan Chen"
    }
  }
]