Leave

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query Leave Balance
Query Leave Requests
Add Leave Request
Update Leave Request
Query Leave Types

Query Leave Balance

Get the leave balance for a specific employee at a given date. Returns all leave types and their current balances for the employee.

Query Parameters:

Parameter	Type	Required	Description
`employeeId`	`ID!`	Yes	The ID of the employee to query
`asOf`	`Date`	No	The date to calculate balance as of (defaults to today)

Response Fields:

Field	Description
`employeeId`	ID of the employee
`leaveType.id`	Unique identifier for the leave type
`leaveType.name`	Name of the leave type (e.g., "Annual Leave")
`amount`	The balance amount
`unit`	Unit of measurement (e.g., "Hours", "Days")

For the complete LeaveBalance type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

The asOf parameter allows you to query historical balances at a specific date
If asOf is not provided, the current balance is returned
Different leave types may use different units (Hours, Days, etc.)
Only leave types available to the employee will be returned
Balances are calculated based on accruals, usage, and adjustments up to the specified date

GraphQL Query

query LeaveBalance($employeeId: ID!, $asOf: Date) {
  leaveBalance(employeeId: $employeeId, asOf: $asOf) {
    employeeId
    leaveType {
      id
      name
    }
    amount
    unit
  }
}

Example Variables

{
  "employeeId": "21",
  "asOf": "2024-01-01"
}

Example Response

{
  "data": {
    "leaveBalance": [
      {
        "employeeId": "21",
        "leaveType": {
          "id": "4708",
          "name": "Annual Leave"
        },
        "amount": 45,
        "unit": "Hours"
      },
      {
        "employeeId": "21",
        "leaveType": {
          "id": "4599",
          "name": "Annual Leave (Weeks)"
        },
        "amount": 99,
        "unit": "Days"
      }
    ]
  }
}

Query Leave Requests

Query leave requests within a date range. Supports filtering by approval status and leave type. This endpoint can be used to retrieve approved, declined, or pending leave requests.

Query Parameters:

Parameter	Type	Required	Description
`startTime`	`DateTime`	No	Start of the date range (inclusive)
`endTime`	`DateTime`	No	End of the date range (inclusive)
`approved`	`Boolean`	No	Filter by approval status (true/false/null for pending)
`leaveTypeId`	`String`	No	Filter by specific leave type ID
`strictRange`	`Boolean`	No	If true, only returns requests fully within the range (default: false)

Response Fields:

Field	Description
`id`	Unique identifier for the leave request
`employee.id`	Employee ID
`employee.fullName`	Full name of the employee
`leaveType.id`	Leave type ID
`leaveType.name`	Name of the leave type
`modifiedAt`	Timestamp when the request was last modified
`modifiedBy.fullName`	Name of the user who last modified the request
`startTime`	Start date/time of the leave request
`endTime`	End date/time of the leave request
`hours`	Total hours of leave
`approved`	Approval status (true/false/null for pending)
`note`	Notes or comments on the leave request
`reason`	Reason for the leave (if provided)

For the complete LeaveRequest type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

When approved is null, the query returns pending leave requests
When approved is true, only approved requests are returned
When approved is false, only declined requests are returned
The strictRange parameter controls overlap behavior:
- false (default): Returns requests that overlap with the date range
- true: Returns only requests fully contained within the date range
Times are in ISO 8601 format with timezone information
The hours field is calculated based on the employee's work schedule

GraphQL Query

query LeaveRequests($startTime: DateTime, $endTime: DateTime, $approved: Boolean, $leaveTypeId: String, $strictRange: Boolean) {
  leaveRequests(startTime: $startTime, endTime: $endTime, approved: $approved, leaveTypeId: $leaveTypeId, strictRange: $strictRange) {
    id
    employee {
      id
      fullName
    }
    leaveType {
      id
      name
    }
    modifiedAt
    modifiedBy {
      fullName
    }
    startTime
    endTime
    hours
    approved
    note
    reason
  }
}

Example Variables (Approved Requests)

{
  "startTime": "2024-04-01",
  "endTime": "2024-04-30",
  "approved": true,
  "leaveTypeId": null,
  "strictRange": false
}

Example Response

{
  "data": {
    "leaveRequests": [
      {
        "id": "502607",
        "employee": {
          "id": "73542",
          "fullName": "Kate Mallone"
        },
        "leaveType": {
          "id": "4579",
          "name": "Annual Leave"
        },
        "modifiedAt": "2024-06-05T05:41:23.114Z",
        "modifiedBy": {
          "fullName": "Roubler Support"
        },
        "startTime": "2024-04-04T14:00:00.000Z",
        "endTime": "2024-04-06T13:59:00.000Z",
        "hours": 15.2,
        "approved": true,
        "note": "AL",
        "reason": null
      }
    ]
  }
}

Add Leave Request

Create a new leave request for an employee. The request can be submitted with optional notes and attachments. The approval status will depend on the leave type's auto-approve settings.

Mutation Parameters:

Parameter	Type	Required	Description
`input`	`AddLeaveRequestInput!`	Yes	Input object containing leave request details
`input.employeeId`	`String!`	Yes	ID of the employee requesting leave
`input.leaveTypeId`	`String!`	Yes	ID of the leave type
`input.startTime`	`DateTime!`	Yes	Start date/time of the leave
`input.endTime`	`DateTime!`	Yes	End date/time of the leave
`input.notes`	`String`	No	Notes or reason for the leave request
`input.attachmentId`	`String`	No	ID of an attachment (e.g., medical certificate)

For the complete input type reference, see AddLeaveRequestInput.

Response Fields:

Field	Description
`id`	Unique identifier for the created leave request
`employeeId`	ID of the employee
`leaveTypeId`	ID of the leave type
`note`	Notes on the leave request
`startTime`	Start date/time of the leave
`endTime`	End date/time of the leave

For the complete LeaveRequest type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

The leave request will be created in a pending state unless the leave type has autoApprove enabled
Times must be in ISO 8601 format with timezone information
The system validates that the employee has sufficient leave balance (if applicable)
Start time must be before end time
You can attach supporting documents using the attachmentId parameter
The leave request will be subject to approval workflows configured for the leave type
Hours are automatically calculated based on the employee's work schedule

GraphQL Mutation

mutation AddLeaveRequest($input: AddLeaveRequestInput!) {
  addLeaveRequest(input: $input) {
    id
    employeeId
    leaveTypeId
    note
    startTime
    endTime
  }
}

Example Variables

{
  "input": {
    "employeeId": "73543",
    "leaveTypeId": "4579",
    "notes": "Interstate travel",
    "startTime": "2024-05-07T14:00:00.000Z",
    "endTime": "2024-05-10T13:59:59.999Z",
    "attachmentId": null
  }
}

Example Response

{
  "data": {
    "addLeaveRequest": {
      "id": "502644",
      "employeeId": "73543",
      "leaveTypeId": "4579",
      "note": "Interstate travel",
      "startTime": "2024-05-07T14:00:00.000Z",
      "endTime": "2024-05-10T13:59:00.999Z"
    }
  }
}

Update Leave Request

Update an existing leave request. This allows modification of dates, leave type, notes, and attachments. The request must exist and be in a modifiable state.

Mutation Parameters:

Parameter	Type	Required	Description
`input`	`UpdateLeaveRequestInput!`	Yes	Input object containing updated details
`input.id`	`String!`	Yes	ID of the leave request to update
`input.employeeId`	`String!`	Yes	ID of the employee (must match original)
`input.leaveTypeId`	`String!`	Yes	ID of the leave type
`input.startTime`	`DateTime!`	Yes	Start date/time of the leave
`input.endTime`	`DateTime!`	Yes	End date/time of the leave
`input.notes`	`String`	No	Updated notes or reason for the leave
`input.attachmentId`	`String`	No	ID of an attachment

For the complete input type reference, see UpdateLeaveRequestInput.

Response Fields:

Field	Description
`id`	Unique identifier for the leave request
`employeeId`	ID of the employee
`leaveTypeId`	ID of the leave type
`note`	Updated notes on the leave request
`startTime`	Updated start date/time of the leave
`endTime`	Updated end date/time of the leave

For the complete LeaveRequest type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

The leave request ID must be valid and belong to the specified employee
You cannot change the employee on an existing leave request
Approved leave requests may have restrictions on modifications depending on company settings
If the dates are changed, the system will recalculate the hours based on the work schedule
Updating a leave request may reset its approval status depending on company workflows
Times must be in ISO 8601 format with timezone information

GraphQL Mutation

mutation UpdateLeaveRequest($input: UpdateLeaveRequestInput!) {
  updateLeaveRequest(input: $input) {
    id
    employeeId
    leaveTypeId
    note
    startTime
    endTime
  }
}

Example Variables

{
  "input": {
    "id": "502644",
    "employeeId": "73543",
    "leaveTypeId": "4579",
    "notes": "Interstate travel + adding additional day",
    "startTime": "2024-05-07T14:00:00.000Z",
    "endTime": "2024-05-11T13:59:59.999Z",
    "attachmentId": null
  }
}

Example Response

{
  "data": {
    "updateLeaveRequest": {
      "id": "502644",
      "employeeId": "73543",
      "leaveTypeId": "4579",
      "note": "Interstate travel + adding additional day",
      "startTime": "2024-05-07T14:00:00.000Z",
      "endTime": "2024-05-11T13:59:00.999Z"
    }
  }
}

Query Leave Types

Retrieve all leave types configured for the company. Leave types define the categories of leave available to employees (e.g., Annual Leave, Sick Leave, etc.) and their associated settings.

Query Parameters:

This query takes no parameters and returns all leave types configured for the company.

Response Fields:

Field	Description
`id`	Unique identifier for the leave type
`name`	Name of the leave type (e.g., "Annual Leave")
`displayBalance`	Whether to display balance for this leave type
`minimumBalance`	Minimum balance required (if applicable)
`autoApprove`	Whether requests for this leave type are auto-approved
`createTimesheet`	Whether approved requests create timesheet entries
`available`	Whether this leave type is currently available for use
`serviceKey`	External service identifier (if integrated with external systems)

For the complete LeaveType type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

Only active leave types are returned by default
The displayBalance field indicates if balances should be shown to employees for this leave type
When autoApprove is true, leave requests are automatically approved when created
The createTimesheet setting determines if approved leave creates corresponding timesheet entries
Some leave types (like LWOP - Leave Without Pay) may not track balances
The serviceKey field is used for integration with payroll or other external systems
Leave types are configured at the company level and may vary by location

GraphQL Query

query LeaveTypes {
  leaveTypes {
    id
    name
    displayBalance
    minimumBalance
    autoApprove
    createTimesheet
    available
    serviceKey
  }
}

Example Variables

{}

Example Response

{
  "data": {
    "leaveTypes": [
      {
        "id": "4579",
        "name": "Annual Leave",
        "displayBalance": true,
        "minimumBalance": null,
        "autoApprove": false,
        "createTimesheet": true,
        "available": true,
        "serviceKey": null
      },
      {
        "id": "4581",
        "name": "LWOP",
        "displayBalance": false,
        "minimumBalance": null,
        "autoApprove": true,
        "createTimesheet": false,
        "available": true,
        "serviceKey": null
      },
      {
        "id": "4580",
        "name": "Personal/Carers Leave",
        "displayBalance": true,
        "minimumBalance": null,
        "autoApprove": false,
        "createTimesheet": true,
        "available": true,
        "serviceKey": null
      }
    ]
  }
}