---
title: "Update Time Off as Employee"
method: PATCH
path: "/v1/employee/timeoff/{id}"
tags: ["Employee Time Off"]
---

# Update Time Off as Employee

`PATCH /v1/employee/timeoff/{id}`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/employee/timeoff/{id}`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `timeoff:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/employment.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `timeoff:write`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`

Updates a Time Off record as Employee

## Authentication

This endpoint accepts any one of the following token types:

- **Employee-scoped access token** (`OAuth2Assertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by the employee through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).

## Scopes

Any one of the scopes in a token type's row is enough. `all:write` works too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Employee-scoped access token | Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
| Company-scoped access token | Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |

## Path parameters

- `id` string, required

## Request body

- UpdateEmployeeTimeoffParams: Update timeoff params
  - `document` TimeoffDocumentParams: Timeoff document params
    - `content` string, required: The binary content of the file encoded with base64
    - `name` string, required: The file name of the document
  - `edit_reason` string, required: The reason for the update. Required when updating the time off data but not changing the status.
  - `end_date` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
  - `leave_policy_variant_id` string
  - `notes` string
  - `start_date` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
  - `timeoff_days` TimeoffDaysParams[]
    - `day` string, date: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
    - `hours` integer
  - `timezone` string: [TZ identifier](https://www.iana.org/time-zones)

## Response `200`

Success

- TimeoffResponse: Timeoff response
  - `data` object, required
    - `timeoff` Timeoff, required: A time off record for an employee, representing a period of leave (e.g., vacation, sick leave, parental leave).
      - `approved_at` string, date-time, nullable: The timestamp when the time off was approved. Null if not yet approved.
      - `approver_id` string, nullable: The field matches the `id` of a user in the Remote Platform that has permission to approve time off requests. [Available users][] can be found fetching the [List Company Manager][] endpoint. [Available users]: https://support.remote.com/hc/en-us/articles/360054668651-Approving-Declining-time-off-requests#h_01G0014GZKZ3EMN6P7C99HAK55 [List Company Manager]: https://gateway.remote.com/v1/docs/openapi.html#tag/Company-Managers
      - `automatic` boolean: Whether this time off was automatically created by the system (e.g., public holidays) rather than requested by the employee.
      - `cancel_reason` string, nullable: The reason provided when the time off was cancelled. Null if not cancelled.
      - `cancelled_at` string, datetime, nullable: Optional UTC date time in YYYY-MM-DDTHH:mm:ss format
      - `document` File: A file associated with an employment, such as a contract, tax document, or identity document.
        - `id` string, required: The unique identifier (UUID) of the file.
        - `inserted_at` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
        - `name` string, required: The file name including extension (e.g., "id.pdf", "contract.pdf").
        - `sub_type` string, nullable: A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
        - `type` string, required: The broad category of the file (e.g., "id", "contract", "tax_document").
      - `employment_id` string, required: The unique identifier (UUID) of the employment this time off belongs to.
      - `end_date` string, date, required: The last day of the time off period (ISO 8601 date).
      - `id` string, required: The unique identifier (UUID) of the time off record.
      - `leave_policy` LeavePolicy, required: The leave policy associated with a time off request. Policies define the rules and entitlements for specific types of leave.
        - `leave_policy_variant_slug` string, required: The unique identifier (slug) of the specific policy variant.
        - `leave_type` 'time_off' | 'sick_leave' | 'public_holiday' | 'unpaid_leave' | 'extended_leave' | 'in_lieu_time' | 'maternity_leave' | 'paternity_leave' | 'parental_leave' | 'bereavement' | 'military_leave' | 'other' | 'paid_time_off' | 'custom_company_leave' | 'rtt' | 'casual_leave' | 'rol' | 'ex_festivita' | 'civic_duty' | 'adoption' | 'caregiver' | 'transfer' | 'exam' | 'monkhood' | 'marriage' | 'sterilization' | 'celebration' | 'blood_donation' | 'health_day' | 'special' | 'career' | 'study' | 'voluntary' | 'adv' | 'public_duties' | 'force_majeure' | 'medical_visits' | 'marriage_child' | 'breastfeeding' | 'maternity_paid' | 'maternity_unpaid' | 'paternity_paid' | 'paternity_unpaid' | 'pregnancy_leave' | 'business_trip_eu' | 'business_trip_non_eu' | 'training' | 'sustainable_employability', required: The type of leave a time off record or leave policy represents. Responses may return any of these values. The set is a superset of the values accepted when creating a time off record (see `TimeoffType`): employments on the newer leave-type model can hold leave types that are not bookable by name.
        - `name` string, required: The display name of the leave policy (e.g., "Self-Care", "Annual Leave").
      - `leave_policy_variant_id` string, uuid, nullable: Identifier of the leave policy this time off was booked against. For employments on the leave-type model this is the leave type's UUID, the same value `GET /leave-policies/details/{employment_id}` returns and `POST /timeoff` accepts. Otherwise it is the UUID of the custom company leave policy variant, and is null for standard leave types.
      - `notes` string, nullable: Optional notes provided by the employee when requesting the time off.
      - `start_date` string, date, required: The first day of the time off period (ISO 8601 date).
      - `status` 'requested' | 'approved' | 'cancelled' | 'declined' | 'taken' | 'cancel_requested', required: The current status of a time off request. - `requested`: The employee has submitted a time off request and it is awaiting approval. - `approved`: The time off request has been approved by a manager. - `cancelled`: The time off request was cancelled by the employee or an admin. - `declined`: The time off request was declined by a manager. - `taken`: The approved time off has been taken (the dates have passed). - `cancel_requested`: The employee has requested cancellation of a previously approved time off, pending manager approval.
      - `timeoff_days` TimeoffDay[], required: The individual days and hours within this time off period.
        - `day` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
        - `hours` integer, required: The number of hours taken off on this day (e.g., 8 for a full day, 4 for a half day). For minute-precision durations (e.g., 7 hours 30 minutes), use `minutes`.
        - `minutes` integer, required: The number of minutes taken off on this day (e.g., 480 for a full 8-hour day, 450 for 7 hours 30 minutes). Minute-precision counterpart of `hours`.
      - `timeoff_type` 'time_off' | 'sick_leave' | 'public_holiday' | 'unpaid_leave' | 'extended_leave' | 'in_lieu_time' | 'maternity_leave' | 'paternity_leave' | 'parental_leave' | 'bereavement' | 'military_leave' | 'other' | 'paid_time_off' | 'custom_company_leave' | 'rtt' | 'casual_leave' | 'rol' | 'ex_festivita' | 'civic_duty' | 'adoption' | 'caregiver' | 'transfer' | 'exam' | 'monkhood' | 'marriage' | 'sterilization' | 'celebration' | 'blood_donation' | 'health_day' | 'special' | 'career' | 'study' | 'voluntary' | 'adv' | 'public_duties' | 'force_majeure' | 'medical_visits' | 'marriage_child' | 'breastfeeding' | 'maternity_paid' | 'maternity_unpaid' | 'paternity_paid' | 'paternity_unpaid' | 'pregnancy_leave' | 'business_trip_eu' | 'business_trip_non_eu' | 'training' | 'sustainable_employability', required: The type of leave a time off record or leave policy represents. Responses may return any of these values. The set is a superset of the values accepted when creating a time off record (see `TimeoffType`): employments on the newer leave-type model can hold leave types that are not bookable by name.
      - `timezone` string, required: [TZ identifier](https://www.iana.org/time-zones)
      - `total_minutes` integer, required: The total number of minutes taken off across all `timeoff_days`. Always equals the sum of the per-day `minutes` values.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Unprocessable Entity

---

[API](https://skmtc.dev/remote-com/apis/time-attendance.md) - [All operations](https://skmtc.dev/remote-com/apis/time-attendance/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/time-attendance/revisions/84de0ccef126?raw)