openapi: 3.1.0
info:
title: Accounting subpackage_timeOff API
version: 1.0.0
servers:
- url: https://api.merge.dev/api
- url: https://api-eu.merge.dev/api
- url: https://api-ap.merge.dev/api
tags:
- name: subpackage_timeOff
paths:
/hris/v1/time-off:
get:
operationId: list
summary: List
description: Returns a list of `TimeOff` objects.{/* BEGIN_HRIS_TIMEOFF_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_TIMEOFF_FETCH_SUPPORTED_FIELDS */}
tags:
- subpackage_timeOff
parameters:
- name: approver_id
in: query
description: If provided, will only return time off for this approver.
required: false
schema:
type: string
- name: created_after
in: query
description: If provided, will only return objects created after this datetime.
required: false
schema:
type: string
format: date-time
- name: created_before
in: query
description: If provided, will only return objects created before this datetime.
required: false
schema:
type: string
format: date-time
- name: cursor
in: query
description: The pagination cursor value.
required: false
schema:
type: string
- name: employee_id
in: query
description: If provided, will only return time off for this employee.
required: false
schema:
type: string
- name: ended_after
in: query
description: If provided, will only return employees that ended after this datetime.
required: false
schema:
type: string
format: date-time
- name: ended_before
in: query
description: If provided, will only return time-offs that ended before this datetime.
required: false
schema:
type: string
format: date-time
- name: expand
in: query
description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/TimeOffGetParametersExpandSchemaItems'
- name: include_deleted_data
in: query
description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/).
required: false
schema:
type: boolean
- name: include_remote_data
in: query
description: Whether to include the original data Merge fetched from the third-party to produce these models.
required: false
schema:
type: boolean
- name: include_shell_data
in: query
description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null).
required: false
schema:
type: boolean
- name: modified_after
in: query
description: If provided, only objects synced by Merge after this date time will be returned.
required: false
schema:
type: string
format: date-time
- name: modified_before
in: query
description: If provided, only objects synced by Merge before this date time will be returned.
required: false
schema:
type: string
format: date-time
- name: page_size
in: query
description: Number of results to return per page. The maximum limit is 100.
required: false
schema:
type: integer
- name: remote_fields
in: query
description: Deprecated. Use show_enum_origins.
required: false
schema:
$ref: '#/components/schemas/TimeOffGetParametersRemoteFields'
- name: remote_id
in: query
description: The API provider's ID for the given object.
required: false
schema:
type: string
- name: request_type
in: query
description: 'If provided, will only return TimeOff with this request type. Options: (''VACATION'', ''SICK'', ''PERSONAL'', ''JURY_DUTY'', ''VOLUNTEER'', ''BEREAVEMENT'')
'
required: false
schema:
$ref: '#/components/schemas/TimeOffGetParametersRequestType'
- name: show_enum_origins
in: query
description: A comma separated list of enum field names for which you'd like the original values to be returned, instead of Merge's normalized enum values. [Learn more](https://help.merge.dev/en/articles/8950958-show_enum_origins-query-parameter)
required: false
schema:
$ref: '#/components/schemas/TimeOffGetParametersShowEnumOrigins'
- name: started_after
in: query
description: If provided, will only return time-offs that started after this datetime.
required: false
schema:
type: string
format: date-time
- name: started_before
in: query
description: If provided, will only return time-offs that started before this datetime.
required: false
schema:
type: string
format: date-time
- name: status
in: query
description: 'If provided, will only return TimeOff with this status. Options: (''REQUESTED'', ''APPROVED'', ''DECLINED'', ''CANCELLED'', ''DELETED'')
'
required: false
schema:
$ref: '#/components/schemas/TimeOffGetParametersStatus'
- name: Authorization
in: header
description: Token-based authentication with required prefix "Bearer"
required: true
schema:
type: string
- name: X-Account-Token
in: header
description: Token identifying the end user.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTimeOffList'
post:
operationId: create
summary: Create
description: Creates a `TimeOff` object with the given values.{/* BEGIN_HRIS_TIMEOFF_CREATE_SUPPORTED_FIELDS */}{/* END_HRIS_TIMEOFF_CREATE_SUPPORTED_FIELDS */}
tags:
- subpackage_timeOff
parameters:
- name: is_debug_mode
in: query
description: Whether to include debug fields (such as log file links) in the response.
required: false
schema:
type: boolean
- name: run_async
in: query
description: Whether or not third-party updates should be run asynchronously.
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Token-based authentication with required prefix "Bearer"
required: true
schema:
type: string
- name: X-Account-Token
in: header
description: Token identifying the end user.
required: true
schema:
type: string
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffEndpointRequest'
/hris/v1/time-off/{id}:
get:
operationId: retrieve
summary: Retrieve
description: Returns a `TimeOff` object with the given `id`.{/* BEGIN_HRIS_TIMEOFF_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_TIMEOFF_FETCH_SUPPORTED_FIELDS */}
tags:
- subpackage_timeOff
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: expand
in: query
description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/TimeOffIdGetParametersExpandSchemaItems'
- name: include_remote_data
in: query
description: Whether to include the original data Merge fetched from the third-party to produce these models.
required: false
schema:
type: boolean
- name: include_shell_data
in: query
description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null).
required: false
schema:
type: boolean
- name: remote_fields
in: query
description: Deprecated. Use show_enum_origins.
required: false
schema:
$ref: '#/components/schemas/TimeOffIdGetParametersRemoteFields'
- name: show_enum_origins
in: query
description: A comma separated list of enum field names for which you'd like the original values to be returned, instead of Merge's normalized enum values. [Learn more](https://help.merge.dev/en/articles/8950958-show_enum_origins-query-parameter)
required: false
schema:
$ref: '#/components/schemas/TimeOffIdGetParametersShowEnumOrigins'
- name: Authorization
in: header
description: Token-based authentication with required prefix "Bearer"
required: true
schema:
type: string
- name: X-Account-Token
in: header
description: Token identifying the end user.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOff'
/hris/v1/time-off/meta/post:
get:
operationId: meta-post-retrieve
summary: Meta Post Retrieve
description: Returns metadata for `TimeOff` POSTs.{/* BEGIN_HRIS_TIMEOFF_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_TIMEOFF_FETCH_SUPPORTED_FIELDS */}
tags:
- subpackage_timeOff
parameters:
- name: Authorization
in: header
description: Token-based authentication with required prefix "Bearer"
required: true
schema:
type: string
- name: X-Account-Token
in: header
description: Token identifying the end user.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetaResponse'
components:
schemas:
ErrorValidationProblem:
type: object
properties:
source:
$ref: '#/components/schemas/ValidationProblemSource'
title:
type: string
detail:
type: string
problem_type:
type: string
block_merge_link:
type: boolean
raw_error:
type: string
error_code:
type: integer
required:
- title
- detail
- problem_type
title: ErrorValidationProblem
TimeOffGetParametersStatus:
type: string
enum:
- APPROVED
- CANCELLED
- DECLINED
- DELETED
- REQUESTED
title: TimeOffGetParametersStatus
TimeOffRequest:
type: object
properties:
employee:
type:
- string
- 'null'
format: uuid
description: The employee requesting time off.
approver:
type:
- string
- 'null'
format: uuid
description: The Merge ID of the employee with the ability to approve the time off request.
status:
oneOf:
- $ref: '#/components/schemas/TimeOffStatusEnum'
- type: 'null'
description: The status of this time off request.
employee_note:
type:
- string
- 'null'
description: The employee note for this time off request.
units:
oneOf:
- $ref: '#/components/schemas/UnitsEnum'
- type: 'null'
description: The measurement that the third-party integration uses to count time requested.
amount:
type:
- number
- 'null'
format: double
description: The time off quantity measured by the prescribed “units”.
request_type:
oneOf:
- $ref: '#/components/schemas/RequestTypeEnum'
- type: 'null'
description: The type of time off request.
start_time:
type:
- string
- 'null'
format: date-time
description: The day and time of the start of the time requested off.
end_time:
type:
- string
- 'null'
format: date-time
description: The day and time of the end of the time requested off.
integration_params:
type:
- object
- 'null'
additionalProperties:
description: Any type
linked_account_params:
type:
- object
- 'null'
additionalProperties:
description: Any type
description: '# The TimeOff Object
### Description
The `TimeOff` object is used to represent all employees'' Time Off entries.
### Usage Example
Fetch from the `LIST TimeOffs` endpoint and filter by `ID` to show all time off requests.'
title: TimeOffRequest
TimeOff:
type: object
properties:
id:
type: string
format: uuid
remote_id:
type:
- string
- 'null'
description: The third-party API ID of the matching object.
created_at:
type: string
format: date-time
description: The datetime that this object was created by Merge.
modified_at:
type: string
format: date-time
description: The datetime that this object was modified by Merge.
employee:
type:
- string
- 'null'
format: uuid
description: The employee requesting time off.
approver:
type:
- string
- 'null'
format: uuid
description: The Merge ID of the employee with the ability to approve the time off request.
status:
oneOf:
- $ref: '#/components/schemas/TimeOffStatusEnum'
- type: 'null'
description: The status of this time off request.
employee_note:
type:
- string
- 'null'
description: The employee note for this time off request.
units:
oneOf:
- $ref: '#/components/schemas/UnitsEnum'
- type: 'null'
description: The measurement that the third-party integration uses to count time requested.
amount:
type:
- number
- 'null'
format: double
description: The time off quantity measured by the prescribed “units”.
request_type:
oneOf:
- $ref: '#/components/schemas/RequestTypeEnum'
- type: 'null'
description: The type of time off request.
start_time:
type:
- string
- 'null'
format: date-time
description: The day and time of the start of the time requested off.
end_time:
type:
- string
- 'null'
format: date-time
description: The day and time of the end of the time requested off.
remote_was_deleted:
type: boolean
description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/).
field_mappings:
oneOf:
- $ref: '#/components/schemas/TimeOffFieldMappings'
- type: 'null'
remote_data:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/RemoteData'
description: '# The TimeOff Object
### Description
The `TimeOff` object is used to represent all employees'' Time Off entries.
### Usage Example
Fetch from the `LIST TimeOffs` endpoint and filter by `ID` to show all time off requests.'
title: TimeOff
TimeOffGetParametersExpandSchemaItems:
type: string
enum:
- approver
- employee
title: TimeOffGetParametersExpandSchemaItems
TimeOffGetParametersShowEnumOrigins:
type: string
enum:
- request_type
- request_type,status
- request_type,status,units
- request_type,units
- status
- status,units
- units
title: TimeOffGetParametersShowEnumOrigins
PaginatedTimeOffList:
type: object
properties:
next:
type:
- string
- 'null'
previous:
type:
- string
- 'null'
results:
type: array
items:
$ref: '#/components/schemas/TimeOff'
title: PaginatedTimeOffList
TimeOffIdGetParametersRemoteFields:
type: string
enum:
- request_type
- request_type,status
- request_type,status,units
- request_type,units
- status
- status,units
- units
title: TimeOffIdGetParametersRemoteFields
TimeOffFieldMappings:
type: object
properties:
organization_defined_targets:
type: object
additionalProperties:
description: Any type
linked_account_defined_targets:
type: object
additionalProperties:
description: Any type
title: TimeOffFieldMappings
WarningValidationProblem:
type: object
properties:
source:
$ref: '#/components/schemas/ValidationProblemSource'
title:
type: string
detail:
type: string
problem_type:
type: string
block_merge_link:
type: boolean
raw_error:
type: string
error_code:
type: integer
required:
- title
- detail
- problem_type
title: WarningValidationProblem
TimeOffEndpointRequest:
type: object
properties:
model:
$ref: '#/components/schemas/TimeOffRequest'
required:
- model
title: TimeOffEndpointRequest
UnitsEnum:
type: string
enum:
- HOURS
- DAYS
title: UnitsEnum
DebugModeLog:
type: object
properties:
log_id:
type: string
dashboard_view:
type: string
log_summary:
$ref: '#/components/schemas/DebugModelLogSummary'
required:
- log_id
- dashboard_view
- log_summary
title: DebugModeLog
MetaResponse:
type: object
properties:
request_schema:
type: object
additionalProperties:
description: Any type
status:
$ref: '#/components/schemas/LinkedAccountStatus'
has_conditional_params:
type: boolean
has_required_linked_account_params:
type: boolean
remote_fields:
type: array
items:
type: string
format: uuid
description: Remote field values to populate
required:
- request_schema
- has_conditional_params
- has_required_linked_account_params
title: MetaResponse
TimeOffGetParametersRequestType:
type: string
enum:
- BEREAVEMENT
- JURY_DUTY
- PERSONAL
- SICK
- VACATION
- VOLUNTEER
title: TimeOffGetParametersRequestType
TimeOffIdGetParametersExpandSchemaItems:
type: string
enum:
- approver
- employee
title: TimeOffIdGetParametersExpandSchemaItems
TimeOffStatusEnum:
type: string
enum:
- REQUESTED
- APPROVED
- DECLINED
- CANCELLED
- DELETED
title: TimeOffStatusEnum
RequestTypeEnum:
type: string
enum:
- VACATION
- SICK
- PERSONAL
- JURY_DUTY
- VOLUNTEER
- BEREAVEMENT
title: RequestTypeEnum
TimeOffResponse:
type: object
properties:
model:
$ref: '#/components/schemas/TimeOff'
warnings:
type: array
items:
$ref: '#/components/schemas/WarningValidationProblem'
errors:
type: array
items:
$ref: '#/components/schemas/ErrorValidationProblem'
logs:
type: array
items:
$ref: '#/components/schemas/DebugModeLog'
required:
- model
- warnings
- errors
title: TimeOffResponse
RemoteData:
type: object
properties:
path:
type: string
description: The third-party API path that is being called.
data:
description: The data returned from the third-party for this object in its original, unnormalized format.
required:
- path
description: '# The RemoteData Object
### Description
The `RemoteData` object is used to represent the full data pulled from the third-party API for an object.
### Usage Example
TODO'
title: RemoteData
ValidationProblemSource:
type: object
properties:
pointer:
type: string
required:
- pointer
title: ValidationProblemSource
TimeOffIdGetParametersShowEnumOrigins:
type: string
enum:
- request_type
- request_type,status
- request_type,status,units
- request_type,units
- status
- status,units
- units
title: TimeOffIdGetParametersShowEnumOrigins
TimeOffGetParametersRemoteFields:
type: string
enum:
- request_type
- request_type,status
- request_type,status,units
- request_type,units
- status
- status,units
- units
title: TimeOffGetParametersRemoteFields
DebugModelLogSummary:
type: object
properties:
url:
type: string
method:
type: string
status_code:
type: integer
required:
- url
- method
- status_code
title: DebugModelLogSummary
LinkedAccountStatus:
type: object
properties:
linked_account_status:
type: string
can_make_request:
type: boolean
required:
- linked_account_status
- can_make_request
title: LinkedAccountStatus
securitySchemes:
tokenAuth:
type: http
scheme: bearer
description: Token-based authentication with required prefix "Bearer"