BambooHR.Metadata (BambooHR v0.5.0)

Functions for retrieving metadata about fields available in the BambooHR API.

These endpoints describe what fields exist on employees and other resources — useful for discovering field names to pass to BambooHR.Employee.get/3, building UIs, or auditing schema drift.

Summary

Functions

get_fields(client)

Retrieves metadata for available employee fields.

get_lists(client)

Retrieves metadata for available list fields.

get_tabular_fields(client)

Retrieves metadata for available tabular fields.

get_time_off_policies(client)

Retrieves all non-deleted time off policies for the company, sorted alphabetically by name.

get_time_off_types(client, params \\ %{})

Retrieves active time off types for the company.

Functions

get_fields(client)

@spec get_fields(BambooHR.Client.t()) :: BambooHR.Client.response()

Retrieves metadata for available employee fields.

Returns a map with a "fields" list; each entry describes a field's id, name, type, and description.

Parameters

client - Client configuration created with BambooHR.Client.new/1

Examples

iex> BambooHR.Metadata.get_fields(client)
{:ok, %{
  "fields" => [
    %{
      "id" => "1",
      "name" => "firstName",
      "type" => "text",
      "description" => "First name"
    }
  ]
}}

get_lists(client)

@spec get_lists(BambooHR.Client.t()) :: BambooHR.Client.response()

Retrieves metadata for available list fields.

List fields hold enumerated values (departments, divisions, etc.). Returns a map with an "items" list; each entry describes a list field's options.

Parameters

client - Client configuration created with BambooHR.Client.new/1

Examples

iex> BambooHR.Metadata.get_lists(client)
{:ok, %{
  "items" => [
    %{
      "fieldId" => "1610",
      "alias" => "department",
      "manageable" => "yes",
      "name" => "Department",
      "options" => [
        %{"id" => "1", "name" => "Engineering", "archived" => "no"}
      ]
    }
  ]
}}

get_tabular_fields(client)

@spec get_tabular_fields(BambooHR.Client.t()) :: BambooHR.Client.response()

Retrieves metadata for available tabular fields.

Tabular fields back tables on the employee record (employment history, compensation, etc.). Returns a map with a "tabularFields" list.

Parameters

client - Client configuration created with BambooHR.Client.new/1

Examples

iex> BambooHR.Metadata.get_tabular_fields(client)
{:ok, %{
  "tabularFields" => [
    %{
      "id" => "employmentStatus",
      "name" => "Employment Status",
      "type" => "list",
      "description" => "History of employment status changes"
    }
  ]
}}

get_time_off_policies(client)

@spec get_time_off_policies(BambooHR.Client.t()) :: BambooHR.Client.response()

Retrieves all non-deleted time off policies for the company, sorted alphabetically by name.

Parameters

client - Client configuration created with BambooHR.Client.new/1

Examples

iex> BambooHR.Metadata.get_time_off_policies(client)
{:ok, [%{"id" => 4, "timeOffTypeId" => 1, "name" => "Standard Vacation", "type" => "accruing"}]}

get_time_off_types(client, params \\ %{})

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

Retrieves active time off types for the company.

Includes the company's default hours-per-day schedule.

Parameters

client - Client configuration created with BambooHR.Client.new/1
params - Optional query params: "mode" — set to "request" to limit results to time off types the authenticated employee can request

Examples

iex> BambooHR.Metadata.get_time_off_types(client)
{:ok, [%{"id" => 1, "name" => "Vacation", "icon" => "calendar"}]}