@spec add_time_off_history(BambooHR.Client.t(), integer(), map()) ::
  BambooHR.Client.response()

Creates a time off history item for an employee.

For "used" entries, "timeOffRequestId" referencing an approved request is required. For override (balance adjustment) entries submitted via this path, provide "amount" and "timeOffTypeId" directly.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• employee_id - The ID of the employee
• history_data - Map describing the history item

Examples

iex> history_data = %{"timeOffRequestId" => 1348}
iex> BambooHR.TimeOff.add_time_off_history(client, 123, history_data)
{:ok, %{}}

@spec adjust_time_off_balance(BambooHR.Client.t(), integer(), map()) ::
  BambooHR.Client.response()

Creates a balance adjustment for an employee's time off type.

The adjustment is recorded as an override history item. Cannot adjust balances for discretionary (unlimited) time off types.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• employee_id - The ID of the employee
• adjustment_data - Map describing the adjustment (time off type, amount, date)

Examples

iex> adjustment_data = %{"timeOffTypeId" => 1, "amount" => 8, "date" => "2024-01-15"}
iex> BambooHR.TimeOff.adjust_time_off_balance(client, 123, adjustment_data)
{:ok, %{}}

@spec assign_employee_policies(BambooHR.Client.t(), integer(), [map()]) ::
  BambooHR.Client.response()

Assigns time off policies to an employee.

A nil accrualStartDate removes an existing assignment. On success, returns the current list of assigned policies.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• employee_id - The ID of the employee to assign policies to
• policies - List of maps with "timeOffPolicyId" and "accrualStartDate"

Examples

iex> policies = [%{"timeOffPolicyId" => 4, "accrualStartDate" => "2024-02-01"}]
iex> BambooHR.TimeOff.assign_employee_policies(client, 123, policies)
{:ok, [%{"timeOffPolicyId" => 4, "timeOffTypeId" => 1, "accrualStartDate" => "2024-02-01"}]}

@spec calculate_balances(BambooHR.Client.t(), integer(), map()) ::
  BambooHR.Client.response()

Calculates an employee's time off balances across all assigned categories.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• employee_id - The ID of the employee
• params - Optional query params: "end" (date to calculate as of, defaults to today) and "precision" (decimal places, 0-4, defaults to 2)

Examples

iex> BambooHR.TimeOff.calculate_balances(client, 123)
{:ok, [%{"timeOffType" => "1", "name" => "Vacation", "units" => "hours", "balance" => "24.50"}]}

@spec change_request_status(BambooHR.Client.t(), integer(), map()) ::
  BambooHR.Client.response()

Updates the status of an existing time off request.

Valid statuses are "approved", "denied" (or "declined"), and "canceled".

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• request_id - The ID of the time off request to update
• status_data - Map with "status" (and optionally a note)

Examples

iex> BambooHR.TimeOff.change_request_status(client, 1348, %{"status" => "approved"})
{:ok, %{}}

@spec create_time_off_request(BambooHR.Client.t(), integer(), map()) ::
  BambooHR.Client.response()

Creates a time off request for an employee.

The request can be submitted with a status of "approved", "denied", or "requested". Approved and denied requests are recorded directly without triggering approval notifications.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• employee_id - The ID of the employee to create the request for
• request_data - Map describing the request (time off type, dates, amount, status)

Examples

iex> request_data = %{"status" => "approved", "start" => "2024-02-01", "end" => "2024-02-03"}
iex> BambooHR.TimeOff.create_time_off_request(client, 123, request_data)
{:ok, %{}}

@spec get_employee_policies(BambooHR.Client.t(), integer()) ::
  BambooHR.Client.response()

Retrieves the time off policies currently assigned to an employee.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• employee_id - The ID of the employee

Examples

iex> BambooHR.TimeOff.get_employee_policies(client, 123)
{:ok, [%{"timeOffPolicyId" => 4, "timeOffTypeId" => 1, "accrualStartDate" => "2024-02-01"}]}

@spec get_time_off_requests(BambooHR.Client.t(), map()) :: BambooHR.Client.response()

Retrieves time off requests within a date range.

Both "start" and "end" are required in params (YYYY-MM-DD). The search is inclusive: requests whose date range overlaps the query window are returned. Results can be filtered by "status", "employeeId", "type", or limited via "action" ("view", "approve", "myRequests").

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• params - Map of query params, must include "start" and "end"

Examples

iex> BambooHR.TimeOff.get_time_off_requests(client, %{"start" => "2024-01-01", "end" => "2024-01-31"})
{:ok, [%{"id" => 1348, "employeeId" => 5, "status" => %{"status" => "approved"}}]}

@spec get_who_is_out(BambooHR.Client.t(), map()) :: BambooHR.Client.response()

Retrieves a date-sorted list of employees who are out and company holidays.

Defaults to today through 14 days out when "start"/"end" are omitted from params.

Parameters

• client - Client configuration created with BambooHR.Client.new/1
• params - Optional query params: "start", "end", "filter" (set to "off" to disable the Who's Out visibility filter)

Examples

iex> BambooHR.TimeOff.get_who_is_out(client)
{:ok, [%{"id" => 1, "type" => "timeOff", "employeeId" => 5, "name" => "Jane Smith"}]}