View Source BambooHR.Client (bamboo_hr v0.1.0)

Client for interacting with the BambooHR API.

Configuration

To use this client, you'll need information from BambooHR:

  • Your company's subdomain
  • An API key

Usage

config = BambooHR.Client.new("your_company", "your_api_key")
{:ok, company_info} = BambooHR.Client.get_company_information(config)

Summary

Functions

Records a clock-in event for an employee.

Records a clock-out event for an employee.

Retrieves company EINs (Employer Identification Numbers).

Retrieves company information.

Retrieves information about a specific employee.

Retrieves the company's employee directory.

Retrieves timesheet entries within a specified date range.

Creates a new client configuration.

Stores timesheet clock entries for employees.

Updates information for an existing employee.

Types

config()

@type config() :: %{
  company_domain: String.t(),
  api_key: String.t(),
  base_url: String.t()
}

response()

@type response() :: {:ok, map()} | {:error, any()}

Functions

add_employee(config, employee_data)

@spec add_employee(config(), map()) :: response()

Adds a new employee.

Parameters

  • config - Client configuration
  • employee_data - Map containing the employee information (firstName and lastName are required)

Examples

iex> employee_data = %{"firstName" => "Jane", "lastName" => "Smith"}
iex> BambooHR.Client.add_employee(config, employee_data)
{:ok, %{"id" => 124}}

clock_in_employee(config, employee_id, clock_data)

@spec clock_in_employee(config(), integer(), map()) :: response()

Records a clock-in event for an employee.

Parameters

  • config - Client configuration
  • employee_id - The ID of the employee to clock in
  • clock_data - Map containing clock-in details (date, start time, timezone, etc.)

Examples

iex> clock_data = %{
...>   "date" => "2024-01-15",
...>   "start" => "09:00",
...>   "timezone" => "America/New_York"
...> }
iex> BambooHR.Client.clock_in_employee(config, 123, clock_data)
{:ok, %{"message" => "Successfully clocked in"}}

clock_out_employee(config, employee_id, clock_data)

@spec clock_out_employee(config(), integer(), map()) :: response()

Records a clock-out event for an employee.

Parameters

  • config - Client configuration
  • employee_id - The ID of the employee to clock out
  • clock_data - Map containing clock-out details (date, end time, timezone)

Examples

iex> clock_data = %{
...>   "date" => "2024-01-15",
...>   "end" => "17:00",
...>   "timezone" => "America/New_York"
...> }
iex> BambooHR.Client.clock_out_employee(config, 123, clock_data)
{:ok, %{"message" => "Successfully clocked out"}}

get_company_eins(config)

@spec get_company_eins(config()) :: response()

Retrieves company EINs (Employer Identification Numbers).

Returns a list of EINs associated with the company.

Examples

iex> BambooHR.Client.get_company_eins(config)
{:ok, %{
  "eins" => [
    %{"ein" => "12-3456789", "name" => "Acme Corp"},
    %{"ein" => "98-7654321", "name" => "Acme Subsidiary"}
  ]
}}

get_company_information(config)

@spec get_company_information(config()) :: response()

Retrieves company information.

Returns basic company details including name, address, and employee count.

Examples

iex> BambooHR.Client.get_company_information(config)
{:ok, %{
  "name" => "Acme Corp",
  "employeeCount" => 100,
  "city" => "San Francisco"
}}

get_employee(config, employee_id, fields)

@spec get_employee(config(), integer(), [String.t()]) :: response()

Retrieves information about a specific employee.

Parameters

  • config - Client configuration
  • employee_id - The ID of the employee to retrieve
  • fields - List of field names to retrieve (e.g., ["firstName", "lastName", "jobTitle"])

Examples

iex> BambooHR.Client.get_employee(config, 123, ["firstName", "lastName", "jobTitle"])
{:ok, %{
  "firstName" => "John",
  "lastName" => "Doe",
  "jobTitle" => "Software Engineer"
}}

get_employee_directory(config)

@spec get_employee_directory(config()) :: response()

Retrieves the company's employee directory.

Returns a list of all employees with basic information like name and contact details.

Examples

iex> BambooHR.Client.get_employee_directory(config)
{:ok, %{
  "employees" => [
    %{
      "id" => 123,
      "displayName" => "John Doe",
      "jobTitle" => "Developer",
      "workEmail" => "john@example.com"
    }
  ]
}}

get_timesheet_entries(config, params)

@spec get_timesheet_entries(config(), map()) :: response()

Retrieves timesheet entries within a specified date range.

Parameters

  • config - Client configuration
  • params - Map containing query parameters (start, end dates, and optional employee IDs)

Examples

iex> params = %{
...>   "start" => "2024-01-01",
...>   "end" => "2024-01-31",
...>   "employeeIds" => "123,124"
...> }
iex> BambooHR.Client.get_timesheet_entries(config, params)
{:ok, %{
  "entries" => [
    %{
      "id" => "1",
      "employeeId" => "123",
      "date" => "2024-01-15",
      "hours" => 8.0
    }
  ]
}}

new(company_domain, api_key, base_url \\ nil)

@spec new(String.t(), String.t(), String.t() | nil) :: config()

Creates a new client configuration.

Parameters

  • company_domain - Your company's subdomain
  • api_key - Your API key
  • base_url - Optional custom base URL for the API (defaults to BambooHR's standard API URL)

Examples

iex> config = BambooHR.Client.new("acme", "api_key_123")
%{
  company_domain: "acme",
  api_key: "api_key_123",
  base_url: "https://api.bamboohr.com/api/gateway.php"
}

# With custom base URL
iex> config = BambooHR.Client.new("acme", "api_key_123", "https://custom-api.example.com")
%{
  company_domain: "acme",
  api_key: "api_key_123",
  base_url: "https://custom-api.example.com"
}

store_timesheet_clock_entries(config, entries)

@spec store_timesheet_clock_entries(config(), [map()]) :: response()

Stores timesheet clock entries for employees.

Parameters

  • config - Client configuration
  • entries - List of clock entry maps containing employee ID, date, start and end times

Examples

iex> entries = [
...>   %{
...>     "employeeId" => "123",
...>     "date" => "2024-01-15",
...>     "start" => "09:00:00",
...>     "end" => "17:00:00"
...>   }
...> ]
iex> BambooHR.Client.store_timesheet_clock_entries(config, entries)
{:ok, %{"message" => "Entries stored successfully"}}

update_employee(config, employee_id, employee_data)

@spec update_employee(config(), integer(), map()) :: response()

Updates information for an existing employee.

Parameters

  • config - Client configuration
  • employee_id - The ID of the employee to update
  • employee_data - Map containing the updated employee information

Examples

iex> update_data = %{"firstName" => "Jane", "lastName" => "Smith-Jones"}
iex> BambooHR.Client.update_employee(config, 124, update_data)
{:ok, %{}}