Remote Leave Policies API
The Leave Policies API from Remote — 4 operation(s) for leave policies.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Leave Policies API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Leave Policies
paths:
/v1/employee/leave-policies:
get:
callbacks: {}
deprecated: false
description: 'List the leave policies for the current employee
## 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_employee_leave-policies
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListLeavePoliciesDetailsResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- OAuth2Assertion:
- https://gateway.remote.com/employment.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
summary: List Employee Leave Policies
tags:
- Leave Policies
/v1/employee/leave-policies/summary:
get:
callbacks: {}
deprecated: false
description: 'List the leave policies summary (balances and entitlements) for the current employee
## 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_employee_leave-policies_summary
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListLeavePoliciesSummaryResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- OAuth2Assertion:
- https://gateway.remote.com/employment.manage
- timeoff:read
- timeoff:write
- time_and_attendance
- all:write
- all:read
summary: List Employee Leave Policies Summary
tags:
- Leave Policies
/v1/leave-policies/summary/{employment_id}:
get:
callbacks: {}
deprecated: false
description: 'List all the data related to time off for a given employment
## 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_leave-policies_summary_employment_id
parameters:
- description: Employment ID
example: ec23ebda-4b7a-4dbd-9d79-bd1eec3f83c9
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListLeavePoliciesSummaryResponse'
description: Success
'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
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 Leave Policies Summary
tags:
- Leave Policies
/v1/leave-policies/details/{employment_id}:
get:
callbacks: {}
deprecated: false
description: 'Describe the leave policies (custom or not) for a given employment
## 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_leave-policies_details_employment_id
parameters:
- description: Employment ID
example: ec23ebda-4b7a-4dbd-9d79-bd1eec3f83c9
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListLeavePoliciesDetailsResponse'
description: Success
'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
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 Leave Policies Details
tags:
- Leave Policies
components:
schemas:
TimeoffType:
enum:
- 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
example: sick_leave
title: TimeoffType
type: string
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
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
ListLeavePoliciesDetailsResponse:
description: Response schema for listing leave policies details
example:
data:
- custom: true
leave_policy_variant_id: 123e4567-e89b-12d3-a456-426614174000
name: Self-Care
uses_accrual_as_balance: false
properties:
data:
items:
$ref: '#/components/schemas/LeavePolicyDetails'
type: array
required:
- data
title: ListLeavePoliciesDetailsResponse
type: object
ListLeavePoliciesSummaryResponse:
description: Response schema for listing leave policies summary
example:
data:
- annual_balance:
days: 1
hours: 3
type: limited
annual_entitlement:
days: 1
hours: 3
type: limited
balance:
days: 1
hours: 3
type: limited
booked:
days: 1
hours: 3
type: limited
current_entitlement:
days: 1
hours: 3
type: limited
leave_policy:
description: Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque.
leave_type: sick_leave
name: Self-Care
unit: days
pending_approval:
days: 1
hours: 3
type: limited
taken:
days: 1
hours: 3
type: limited
upcoming_approved:
days: 1
hours: 3
type: limited
upcoming_requested:
days: 1
hours: 3
type: limited
used:
days: 1
hours: 3
type: limited
working_hours_per_day: 8
properties:
data:
items:
$ref: '#/components/schemas/LeavePolicySummary'
type: array
required:
- data
title: ListLeavePoliciesSummaryResponse
type: object
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
UnlimitedDaysandHoursResponse:
additionalProperties: false
example:
type: unlimited
properties:
type:
enum:
- unlimited
type: string
required:
- type
title: UnlimitedDaysandHoursResponse
type: object
LeavePolicySummary:
additionalProperties: false
description: Leave Policy Summary
example:
annual_balance:
days: 1
hours: 3
type: limited
annual_entitlement:
days: 1
hours: 3
type: limited
balance:
days: 1
hours: 3
type: limited
booked:
days: 1
hours: 3
type: limited
current_entitlement:
days: 1
hours: 3
type: limited
leave_policy:
description: Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque.
leave_type: sick_leave
name: Self-Care
unit: days
pending_approval:
days: 1
hours: 3
type: limited
taken:
days: 1
hours: 3
type: limited
upcoming_approved:
days: 1
hours: 3
type: limited
upcoming_requested:
days: 1
hours: 3
type: limited
used:
days: 1
hours: 3
type: limited
working_hours_per_day: 8
properties:
annual_balance:
anyOf:
- $ref: '#/components/schemas/UnlimitedDaysandHoursResponse'
- $ref: '#/components/schemas/LimitedDaysandHoursResponse'
description: 'The annual balance represents the balance for the current entitlement period.
Unlike the regular balance, it does not account for accrued value and only considers the annual entitlement as the basis for calculations.
'
annual_entitlement:
anyOf:
- $ref: '#/components/schemas/UnlimitedDaysandHoursResponse'
- $ref: '#/components/schemas/LimitedDaysandHoursResponse'
description: 'The annual entitlement represents what an employee is entitled to in the current entitlement period.
It does not account for any accrued value.
'
balance:
anyOf:
- $ref: '#/components/schemas/UnlimitedDaysandHoursResponse'
- $ref: '#/components/schemas/LimitedDaysandHoursResponse'
description: The balance is the entitlement minus the taken timeoff (i.e 10 entitlement - 3 taken = 7 balance)
booked:
additionalProperties: false
description: Includes all upcoming requested time off.
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
current_entitlement:
anyOf:
- $ref: '#/components/schemas/UnlimitedDaysandHoursResponse'
- $ref: '#/components/schemas/LimitedDaysandHoursResponse'
description: The current entitlement is the accrued time entitled for the employee plus any other extra entitlements (such as carryover).
leave_policy:
$ref: '#/components/schemas/EmployeeLeavePolicy'
pending_approval:
additionalProperties: false
description: Includes requested timeoffs (not approved) in the past or in the future.
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
taken:
additionalProperties: false
description: Includes all time off (past and future, pending or approved).
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
upcoming_approved:
additionalProperties: false
description: Includes all upcoming approved time off.
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
upcoming_requested:
additionalProperties: false
description: Includes all upcoming requested time off.
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
used:
additionalProperties: false
description: Includes only approved time off in the past.
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
working_hours_per_day:
type: integer
required:
- leave_policy
- annual_entitlement
- annual_balance
- current_entitlement
- balance
- upcoming_approved
- upcoming_requested
- pending_approval
- taken
- used
- booked
- working_hours_per_day
title: LeavePolicySummary
type: object
EmployeeLeavePolicy:
additionalProperties: false
description: Leave Policy abstraction representation for the employee
example:
description: Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque.
leave_type: sick_leave
name: Self-Care
unit: days
properties:
description:
nullable: true
type: string
leave_type:
$ref: '#/components/schemas/TimeoffType'
name:
nullable: false
type: string
unit:
enum:
- days
- hours
- unlimited
type: string
required:
- name
- description
- unit
- leave_type
title: EmployeeLeavePolicy
type: object
LeavePolicyDetails:
additionalProperties: false
description: Leave Policy Details
example:
custom: true
leave_policy_variant_id: 123e4567-e89b-12d3-a456-426614174000
name: Self-Care
uses_accrual_as_balance: false
properties:
custom:
example: true
type: boolean
leave_policy_variant_id:
anyOf:
- example: 123e4567-e89b-12d3-a456-426614174000
format: uuid
type: string
- enum:
- 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
example: sick_leave
title: TimeoffType
type: string
description: The ID of the leave policy variant
name:
example: Self-Care
type: string
uses_accrual_as_balance:
description: Whether leave balance is determined by accruals
example: false
type: boolean
required:
- leave_policy_variant_id
- custom
- name
title: LeavePolicyDetails
type: object
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
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
required:
- code
- message
- action
title: ActionError
type: object
LimitedDaysandHoursResponse:
additionalProperties: false
description: Includes requested timeoffs (not approved) in the past or in the future.
example:
days: 1
hours: 3
type: limited
properties:
days:
nullable: false
type: integer
hours:
nullable: false
type: integer
type:
enum:
- limited
type: string
required:
- type
- days
- hours
title: LimitedDaysandHoursResponse
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.
'
flows:
clientCredentials:
scopes:
address:read: address:read
address:write: address:write
bank_account:read: bank_account:read
bank_account:write: bank_account:write
document:read: document:read
document:write: document:write
emergency_contact:read: emergency_contact:read
emergency_contact:write: emergency_contact:write
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
expense:read: expense:read
incentive:read: incentive:read
payroll: payroll
payslip:read: payslip:read
personal_detail:read: personal_detail:read
personal_detail:write: personal_detail:write
time_and_attendance: time_and_attendance
timeoff:read: timeoff:read
timeoff:write: timeoff:write
timesheet:read: timesheet:read
tokenUrl: /auth/oauth2/token
x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
type: oauth2
OAuth2AuthorizationCode:
description: 'Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
refreshUrl: /auth/oauth2/token
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
fo
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-leave-policies-api-openapi.yml