# `BambooHR.Metadata`
[🔗](https://github.com/sgerrand/ex_bamboo_hr/blob/v0.6.0/lib/bamboo_hr/metadata.ex#L1)

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.

# `get_fields`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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"}]}

---

*Consult [api-reference.md](api-reference.md) for complete listing*