Added Time Off Requests + Admin Approval Flow

We're launching comprehensive time off request and approval capabilities for Gusto Embedded partners, including a new admin management flow and a full suite of REST APIs for the complete time off request lifecycle.

Employees can now submit, track, and cancel time off requests through the API, while admins get a dedicated flow for reviewing, approving, declining, and editing requests—all integrated with payroll so approved time off is automatically reflected. Read more in our Time Off Requests guide.

Why this matters

Managing time off previously required partners to build their own request and approval workflows, reconcile balances manually, and handle payroll adjustments separately. The new flow and endpoints provide a structured, end-to-end approach — from employee submission through admin approval and automatic payroll application — reducing integration complexity and keeping time off state consistent across the platform.

New flow type

time_off_request_management, a dedicated admin interface for reviewing, approving, declining, editing, and recording time off requests. Requires entity_type: "Company" and entity_uuid: <company_uuid>.

To get started, create a flow using the Create a flow endpoint with flow_type: "time_off_request_management".

New scopes

time_off_requests:read, time_off_requests:write, time_off_requests:manage

New endpoints

Time off requests

• GET /v1/companies/{company_uuid}/time_off/requests
  • List time off requests, filterable by employee, status, and date range
• GET /v1/companies/{company_uuid}/time_off/requests/{time_off_request_uuid}
  • Get a single time off request
• POST /v1/companies/{company_uuid}/time_off/requests
  • Create a time off request in pending status
• POST /v1/companies/{company_uuid}/time_off/requests/preview
  • Preview balance impact before submitting a request
• POST /v1/companies/{company_uuid}/time_off/admin_approved_requests
  • Create an admin-initiated time off request; auto-approved
• PUT /v1/time_off/requests/{time_off_request_uuid}/approve
  • Approve a pending request; admin may edit dates or hours during approval
• PUT /v1/time_off/requests/{time_off_request_uuid}/decline
  • Decline a pending request; requires an employer note
• DELETE /v1/time_off/requests/{time_off_request_uuid}
  • Cancel a time off request

Time off balances

• GET /v1/companies/{company_uuid}/time_off_balances
  • Check employee time off balances: accrued, used, pending, and available hours

New webhooks and notifications

Webhooks

• time_off_request.created — fired when a time off request is created
• time_off_request.updated — fired when a time off request is updated, including status changes
• time_off_request.deleted — fired when a time off request is cancelled

Notifications (delivered via webhook)

• time_off_request.approved — employee notification when their request is approved
• time_off_request.declined — employee notification when their request is declined
• pending_time_off_requests — actionable admin notification when there are pending requests to review