Remote Time Off API
The Time Off API from Remote — 8 operation(s) for time off.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Time Off API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Time Off
paths:
/v1/timeoff/{timeoff_id}/cancel:
post:
callbacks: {}
deprecated: false
description: 'Cancel a time off request that was already approved.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: post_v1_timeoff_timeoff_id_cancel
parameters:
- description: Time Off ID
example: 93t3j-timeoff-id-9suej43
in: path
name: timeoff_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CancelTimeoffParams'
description: CancelTimeoff
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Cancel Time Off
tags:
- Time Off
/v1/timeoff/{timeoff_id}/cancel-request/decline:
post:
callbacks: {}
deprecated: false
description: 'Decline a time off cancellation request.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: post_v1_timeoff_timeoff_id_cancel-request_decline
parameters:
- description: Time Off ID
example: 93t3j-timeoff-id-9suej43
in: path
name: timeoff_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeclineTimeoffParams'
description: Timeoff
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Decline a time off cancellation request
tags:
- Time Off
/v1/timeoff/types:
get:
callbacks: {}
deprecated: false
description: 'Lists all time off types that can be used for the `timeoff_type` parameter.
**Backward compatibility:** Calling this endpoint without the `type` query parameter returns the same response as before (time off types for full-time employments). Existing integrations do not need to change.
Optionally, pass `type=contractor` to get time off types for contractor employments, or `type=full_time` for full-time employments (same as omitting the parameter).
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |
'
operationId: get_v1_timeoff_types
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: 'Optional. Employment type to list time off types for: `contractor` or `full_time`. Omit for backward-compatible behavior (full-time types).'
example: full_time
in: query
name: type
required: false
schema:
$ref: '#/components/schemas/TimeoffTypesEmploymentType'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListTimeoffTypesResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
summary: List Time Off Types
tags:
- Time Off
/v1/timeoff/{id}:
get:
callbacks: {}
deprecated: false
description: 'Shows a single Time Off record
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |
'
operationId: get_v1_timeoff_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Timeoff ID
example: 93t3j-timeoff-id-9suej43
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
summary: Show Time Off
tags:
- Time Off
patch:
callbacks: {}
deprecated: false
description: 'Updates a Time Off record.
Warning: Updating the status of a time off through this endpoint is deprecated and will be removed on January 13, 2025.
To approve or cancel an approved time off, use the `/approve` and `/cancel` endpoints instead.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: patch_v1_timeoff_id (2)
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Timeoff ID
example: 93t3j-timeoff-id-9suej43
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApprovedTimeoffParams'
description: UpdateTimeoff
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Update Time Off
tags:
- Time Off
put:
callbacks: {}
deprecated: false
description: 'Updates a Time Off record.
Warning: Updating the status of a time off through this endpoint is deprecated and will be removed on January 13, 2025.
To approve or cancel an approved time off, use the `/approve` and `/cancel` endpoints instead.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: patch_v1_timeoff_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Timeoff ID
example: 93t3j-timeoff-id-9suej43
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApprovedTimeoffParams'
description: UpdateTimeoff
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Update Time Off
tags:
- Time Off
/v1/timeoff/{timeoff_id}/decline:
post:
callbacks: {}
deprecated: false
description: 'Decline a time off request. Please note that only time off requests on the `requested` status can be declined.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: post_v1_timeoff_timeoff_id_decline
parameters:
- description: Time Off ID
example: 93t3j-timeoff-id-9suej43
in: path
name: timeoff_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeclineTimeoffParams'
description: DeclineTimeoff
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Decline Time Off
tags:
- Time Off
/v1/timeoff/{timeoff_id}/approve:
post:
callbacks: {}
deprecated: false
description: 'Approve a time off request.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: post_v1_timeoff_timeoff_id_approve
parameters:
- description: Time Off ID
example: 93t3j-timeoff-id-9suej43
in: path
name: timeoff_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApproveTimeoffParams'
description: ApproveTimeoff
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Approve Time Off
tags:
- Time Off
/v1/timeoff:
get:
callbacks: {}
deprecated: false
description: 'Lists all Time Off records.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |
'
operationId: get_v1_timeoff
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Only show time off for a specific employment
example: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d
in: query
name: employment_id
required: false
schema:
type: string
- description: Filter time off by its type
example: sick_leave
in: query
name: timeoff_type
required: false
schema:
$ref: '#/components/schemas/TimeoffType'
- description: Filter time off by its status
example: approved
in: query
name: status
required: false
schema:
$ref: '#/components/schemas/TimeoffStatus'
- description: 'ISO 8601 date. When combined with `end_date`, returns all time off records that overlap the `[start_date, end_date]` window — including records that only partially overlap at either boundary. When used alone, returns records whose `start_date` is on or after this date.
'
example: '2024-01-01'
in: query
name: start_date
required: false
schema:
$ref: '#/components/schemas/Date'
- description: 'ISO 8601 date. When combined with `start_date`, returns all time off records that overlap the `[start_date, end_date]` window — including records that only partially overlap at either boundary. When used alone, returns records whose `end_date` is on or before this date.
'
example: '2024-12-31'
in: query
name: end_date
required: false
schema:
$ref: '#/components/schemas/Date'
- description: Sort order
example: asc
in: query
name: order
required: false
schema:
enum:
- asc
- desc
type: string
- description: Field to sort by
example: timeoff_type
in: query
name: sort_by
required: false
schema:
enum:
- timeoff_type
- status
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
default: 1
minimum: 1
type: integer
- description: Number of items per page
example: 20
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListTimeoffResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
summary: List Time Off
tags:
- Time Off
post:
callbacks: {}
deprecated: false
description: 'Creates a Time Off record
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: post_v1_timeoff
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApprovedTimeoffParams'
description: Timeoff
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeoffResponse'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Create Time Off
tags:
- Time Off
/v1/timeoff/{timeoff_id}/cancel-request/approve:
post:
callbacks: {}
deprecated: false
description: 'Approve a time off cancellation request.
In order to approve a time off cancellation request, the timeoff status must be `cancel_requested`.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage timeoffs (`time_and_attendance`) | - | Manage timeoffs (`timeoff:write`) |
'
operationId: post_v1_timeoff_timeoff_id_cancel-request_approve
parameters:
- description: Time Off ID
example: 93t3j-timeoff-id-9suej43
in: path
name: timeoff_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- timeoff:write
- time_and_attendance
- all:write
summary: Approve a time off cancellation request
tags:
- Time Off
components:
schemas:
CreateApprovedTimeoffParams:
additionalProperties: false
allOf:
- $ref: '#/components/schemas/CreateTimeoffParams'
- properties:
approved_at:
$ref: '#/components/schemas/DateTimeIso8601'
approver_id:
$ref: '#/components/schemas/NullableApproverId'
status:
enum:
- approved
type: string
required:
- status
- approver_id
- approved_at
type: object
description: Approved timeoff creation params
example:
approved_at: '2021-07-15T18:18:17Z'
approver_id: 123e4567-e89b-12d3-a456-426614174000
employment_id: 5e55386e-4f4f-4def-92f4-bdc19a5ce77d
end_date: '2021-12-21'
start_date: '2021-12-20'
status: approved
timeoff_days:
- day: '2021-12-20'
hours: 8
- day: '2021-12-21'
hours: 8
timeoff_type: paid_time_off
timezone: Asia/Kolkata
title: CreateApprovedTimeoffParams
type: object
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
TimeoffResponse:
description: Timeoff response
example:
data:
timeoff:
automatic: fal
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-time-off-api-openapi.yml