Leave Requests
This endpoint manages employee leave requests within the organization.
Overview
Leave requests allow employees to formally request time off from work. The system supports various leave types (vacation, sick leave, parental leave, etc.) and implements a multi-step approval workflow.
Workflow
- Creation: Employees submit leave requests for specific date ranges
- Manager Approval: The employee’s direct manager must first approve the request
- HR Approval: After manager approval, HR must also approve the request
- Completion: Once fully approved, the leave is deducted from the employee’s leave budget
Access Control
- Employees can create, view, and cancel their own leave requests
- Managers can approve/reject requests for their direct reports
- HR personnel can approve/reject/cancel any leave request
Supporting Documentation
Leave requests can include supporting documentation (e.g., medical certificates) as file attachments.
Endpoints
- get /api/v3/office/leave/requests
- post /api/v3/office/leave/requests
- post /api/v3/office/leave/requests/:id/approve
- post /api/v3/office/leave/requests/:id/cancel
- post /api/v3/office/leave/requests/:id/reject
- get /api/v3/office/leave/requests/:resource_id
- get /api/v3/office/leave/requests/summary
get/api/v3/office/leave/requests
Return a paginated list of office/leave/requests
Input Schema
object
page?:
object
The page number, default to 1
number?: integer
The number of items per page, default to 1000
size?: integer
The sort order, comma separated list of fields. See sorting section for more details
sort?: string
Set to true to return the total number of items in the collection
count?: boolean
filter?:
object
id?: unknown
employee_id?: unknown
status?: unknown
leave_type?: unknown
validated_by_hr_id?: unknown
validated_by_hr_at?: unknown
validations?: unknown
validated_by_manager_id?: unknown
validated_by_manager_at?: unknown
start_date?: unknown
start_half_day?: unknown
end_date?: unknown
end_half_day?: unknown
details?: unknown
related_document?: unknown
total_days?: unknown
rejection_reason?: unknown
rejected_by_id?: unknown
created_at?: unknown
force_duration_hour?: unknown
employee_id?: unknown
start_date__gte?: unknown
start_date__lte?: unknown
end_date__gte?: unknown
end_date__lte?: unknown
created_at__gte?: unknown
created_at__lte?: unknown
leave_type__in?: unknown
status__in?: unknown
by_employee?: unknown
teams__contains?: unknown
date?: unknown
overlaps?: unknown
The related resources to include in the response. Allowed resources are:
- `employee`
- `rejected_by`
- `employee.leave_budget`
- `validated_by_hr`
- `validated_by_manager`
included?: - `employee`
- `rejected_by`
- `employee.leave_budget`
- `validated_by_hr`
- `validated_by_manager`
array
Elements: string
The fields to include in the response.
The key is the resource type and the value is an array of fields.
fields?: The key is the resource type and the value is an array of fields.
dictionary
Values: array
Typescript
type InputSchema = {
page?: {
// The page number, default to 1
number?: number;
// The number of items per page, default to 1000
size?: number;
};
// The sort order, comma separated list of fields. See sorting section for more details
sort?: string;
// Set to true to return the total number of items in the collection
count?: boolean;
filter?: {
id?: any;
employee_id?: any;
status?: any;
leave_type?: any;
validated_by_hr_id?: any;
validated_by_hr_at?: any;
validations?: any;
validated_by_manager_id?: any;
validated_by_manager_at?: any;
start_date?: any;
start_half_day?: any;
end_date?: any;
end_half_day?: any;
details?: any;
related_document?: any;
total_days?: any;
rejection_reason?: any;
rejected_by_id?: any;
created_at?: any;
force_duration_hour?: any;
employee_id?: any;
start_date__gte?: any;
start_date__lte?: any;
end_date__gte?: any;
end_date__lte?: any;
created_at__gte?: any;
created_at__lte?: any;
leave_type__in?: any;
status__in?: any;
by_employee?: any;
teams__contains?: any;
date?: any;
overlaps?: any;
};
// The related resources to include in the response. Allowed resources are:
// - `employee`
// - `rejected_by`
// - `employee.leave_budget`
// - `validated_by_hr`
// - `validated_by_manager`
included?: Array<string>;
// The fields to include in the response.
// The key is the resource type and the value is an array of fields.
fields?: { [key: string]: Array<any> };
};
Output Schema
object
data:
array
Elements:
object
type: string
id?: string
attributes?:
object
id?: integer
employee_id?: integer
status?: string
leave_type?: string
validated_by_hr_at?: datetime
validations?: array
validated_by_manager_at?: datetime
start_date?: date
start_half_day?: boolean
end_date?: date
end_half_day?: boolean
details?: string or null
related_document?: string
total_days?: unknown
rejection_reason?: string or null
rejected_by_id?: integer
created_at?: datetime
force_duration_hour?: number
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: Array<{
type: string;
id?: string;
attributes?: {
id?: number;
employee_id?: number;
status?: string;
leave_type?: string;
validated_by_hr_at?: Date;
validations?: Array<any>;
validated_by_manager_at?: Date;
start_date?: Date;
start_half_day?: boolean;
end_date?: Date;
end_half_day?: boolean;
details?: string | null;
related_document?: string;
total_days?: any;
rejection_reason?: string | null;
rejected_by_id?: number;
created_at?: Date;
force_duration_hour?: number;
};
relationships?: Record<string, any>;
}>;
included?: Array<Record<string, any>>;
};
post/api/v3/office/leave/requests
Create a new office/leave/requests
Input Schema
object
data:
object
type: string
attributes:
object
id?: integer
employee_id?: integer
status?: string
leave_type?: string
validated_by_hr_at?: datetime
validations?: array
validated_by_manager_at?: datetime
start_date?: date
start_half_day?: boolean
end_date?: date
end_half_day?: boolean
details?: string or null
related_document?: string
total_days?: unknown
rejection_reason?: string or null
rejected_by_id?: integer
created_at?: datetime
force_duration_hour?: number
relationships?:
object
employee:
object
data:
object
type: string
id?: string
Typescript
type InputSchema = {
data: {
type: string;
attributes: {
id?: number;
employee_id?: number;
status?: string;
leave_type?: string;
validated_by_hr_at?: Date;
validations?: Array<any>;
validated_by_manager_at?: Date;
start_date?: Date;
start_half_day?: boolean;
end_date?: Date;
end_half_day?: boolean;
details?: string | null;
related_document?: string;
total_days?: any;
rejection_reason?: string | null;
rejected_by_id?: number;
created_at?: Date;
force_duration_hour?: number;
};
relationships?: { employee: { data: { type: string; id?: string } } };
};
};
post/api/v3/office/leave/requests/:id/approve
Approve a leave request.
This endpoint is used by managers and HR personnel to approve leave requests as part of the two-step approval process.
Approval Process
A leave request requires two sequential approvals to be fully validated:
- Manager Approval: The employee’s direct manager must first approve the request
- HR Approval: After manager approval, HR must also approve the request
System Behavior
The system automatically determines whether the current user is acting as a manager or HR based on their role:
- If the user is the employee’s manager and the request is pending, it will be marked as “manager approved”
- If the user is HR and the request is “manager approved”, it will be marked as “approved”
Effects of Final Approval
Once fully approved:
- The appropriate amount of leave is deducted from the employee’s leave budget
- A leave budget event is created to track this deduction
- Notifications are sent to the employee and relevant stakeholders
- The leave appears on team calendars and absence reports
Input Schema
object
id: integer
Typescript
type InputSchema = { id: number };
Output Schema
object
data:
object
type: string
id?: string
attributes?:
object
id?: integer
employee_id?: integer
status?: string
leave_type?: string
validated_by_hr_at?: datetime
validations?: array
validated_by_manager_at?: datetime
start_date?: date
start_half_day?: boolean
end_date?: date
end_half_day?: boolean
details?: string or null
related_document?: string
total_days?: unknown
rejection_reason?: string or null
rejected_by_id?: integer
created_at?: datetime
force_duration_hour?: number
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: {
type: string;
id?: string;
attributes?: {
id?: number;
employee_id?: number;
status?: string;
leave_type?: string;
validated_by_hr_at?: Date;
validations?: Array<any>;
validated_by_manager_at?: Date;
start_date?: Date;
start_half_day?: boolean;
end_date?: Date;
end_half_day?: boolean;
details?: string | null;
related_document?: string;
total_days?: any;
rejection_reason?: string | null;
rejected_by_id?: number;
created_at?: Date;
force_duration_hour?: number;
};
relationships?: Record<string, any>;
};
included?: Array<Record<string, any>>;
};
post/api/v3/office/leave/requests/:id/cancel
Cancel an existing leave request.
This endpoint allows either the employee who created the request or an HR administrator to cancel a leave request.
Restrictions
- Timing: Leave requests can only be cancelled before their start date
- Status: For employees, the request must be in “pending” status to be cancelled
- Permissions: HR administrators can cancel any leave request regardless of status
Effects
When a leave request is cancelled:
- The request status is updated to “cancelled”
- Any reserved leave budget is returned to the employee’s balance
- Notifications are sent to relevant stakeholders (employee, manager, HR)
Input Schema
object
id: integer
Typescript
type InputSchema = { id: number };
Output Schema
object
data:
object
type: string
id?: string
attributes?:
object
id?: integer
employee_id?: integer
status?: string
leave_type?: string
validated_by_hr_at?: datetime
validations?: array
validated_by_manager_at?: datetime
start_date?: date
start_half_day?: boolean
end_date?: date
end_half_day?: boolean
details?: string or null
related_document?: string
total_days?: unknown
rejection_reason?: string or null
rejected_by_id?: integer
created_at?: datetime
force_duration_hour?: number
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: {
type: string;
id?: string;
attributes?: {
id?: number;
employee_id?: number;
status?: string;
leave_type?: string;
validated_by_hr_at?: Date;
validations?: Array<any>;
validated_by_manager_at?: Date;
start_date?: Date;
start_half_day?: boolean;
end_date?: Date;
end_half_day?: boolean;
details?: string | null;
related_document?: string;
total_days?: any;
rejection_reason?: string | null;
rejected_by_id?: number;
created_at?: Date;
force_duration_hour?: number;
};
relationships?: Record<string, any>;
};
included?: Array<Record<string, any>>;
};
post/api/v3/office/leave/requests/:id/reject
Reject a leave request.
This endpoint allows managers and HR personnel to reject leave requests that cannot be approved.
Rejection Process
Either the employee’s manager or HR can reject a leave request at any stage of the approval process. When rejecting a request, a rejection reason can be provided to explain the decision to the employee.
Required Information
- Request ID: The unique identifier of the leave request to reject
- Rejection Reason (optional): A text explanation for why the request was rejected
Effects
When a leave request is rejected:
- The request status is updated to “rejected”
- The rejection reason is recorded (if provided)
- The user who rejected the request is recorded
- Notifications are sent to the employee and other relevant stakeholders
Input Schema
object
id: integer
data?:
object
rejection_reason?: string or null
Typescript
type InputSchema = { id: number; data?: { rejection_reason?: string | null } };
Output Schema
object
data:
object
type: string
id?: string
attributes?:
object
id?: integer
employee_id?: integer
status?: string
leave_type?: string
validated_by_hr_at?: datetime
validations?: array
validated_by_manager_at?: datetime
start_date?: date
start_half_day?: boolean
end_date?: date
end_half_day?: boolean
details?: string or null
related_document?: string
total_days?: unknown
rejection_reason?: string or null
rejected_by_id?: integer
created_at?: datetime
force_duration_hour?: number
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: {
type: string;
id?: string;
attributes?: {
id?: number;
employee_id?: number;
status?: string;
leave_type?: string;
validated_by_hr_at?: Date;
validations?: Array<any>;
validated_by_manager_at?: Date;
start_date?: Date;
start_half_day?: boolean;
end_date?: Date;
end_half_day?: boolean;
details?: string | null;
related_document?: string;
total_days?: any;
rejection_reason?: string | null;
rejected_by_id?: number;
created_at?: Date;
force_duration_hour?: number;
};
relationships?: Record<string, any>;
};
included?: Array<Record<string, any>>;
};
get/api/v3/office/leave/requests/:resource_id
Show a specific office/leave/requests
Input Schema
object
resource_id: integer
included?:
array
Elements: string
fields?:
dictionary
Values: array
Typescript
type InputSchema = {
resource_id: number;
included?: Array<string>;
fields?: { [key: string]: Array<any> };
};
Output Schema
object
data:
object
type: string
id?: string
attributes?:
object
id?: integer
employee_id?: integer
status?: string
leave_type?: string
validated_by_hr_at?: datetime
validations?: array
validated_by_manager_at?: datetime
start_date?: date
start_half_day?: boolean
end_date?: date
end_half_day?: boolean
details?: string or null
related_document?: string
total_days?: unknown
rejection_reason?: string or null
rejected_by_id?: integer
created_at?: datetime
force_duration_hour?: number
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: {
type: string;
id?: string;
attributes?: {
id?: number;
employee_id?: number;
status?: string;
leave_type?: string;
validated_by_hr_at?: Date;
validations?: Array<any>;
validated_by_manager_at?: Date;
start_date?: Date;
start_half_day?: boolean;
end_date?: Date;
end_half_day?: boolean;
details?: string | null;
related_document?: string;
total_days?: any;
rejection_reason?: string | null;
rejected_by_id?: number;
created_at?: Date;
force_duration_hour?: number;
};
relationships?: Record<string, any>;
};
included?: Array<Record<string, any>>;
};
get/api/v3/office/leave/requests/summary
Retrieve a summary of leave requests for a specific date and team.
This endpoint provides aggregated information about leave requests, useful for team planning, resource allocation, and absence management.
Available Data
The summary includes:
- Total number of employees on leave for the specified date and team(s)
- Breakdown by leave type (vacation, sick leave, etc.)
- List of absent employees with leave duration
- Department/team coverage statistics
Filtering
The summary can be filtered by:
- Date: The specific date to check for absences
- Teams: One or more team identifiers to include in the summary
This endpoint is particularly useful for managers and HR to get a quick overview of team availability.
Input Schema
object
filters:
object
date: date
teams__contains?: array
Typescript
type InputSchema = { filters: { date: Date; teams__contains?: Array<any> } };