> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Enum values

> Read an enum field that can still return an unmapped value.

Every HR, payroll, ATS and LMS system describes the same concept in its own words. One marks a full-time employee as `Full-Time`, another as `FT`, another as a numeric type code. For a set of fields on the unified models, Bindbee defines a fixed vocabulary and maps each provider's value into it during sync, so your application reads `FULL_TIME` whichever connector is behind the request.

The provider's own value stays available through `include_raw_data=true` or through [custom fields](/guides/extending/custom-fields).

## Enum fields are open, not closed

When a connector returns a value Bindbee has no mapping for, **the original value is passed through unchanged**. Bindbee never drops or guesses a value it cannot classify, so an enum field can legitimately return a string that is not in the documented list. Forty-eight field descriptions in the API spec say exactly that.

## `null`, `-`, and an unmapped value

| You receive              | It means                                          | Do                           |
| ------------------------ | ------------------------------------------------- | ---------------------------- |
| `null`                   | The provider did not supply the field at all      | Treat as unknown             |
| `-`                      | Present, but not classifiable into the vocabulary | Render as "not specified"    |
| A string not in the list | The provider uses a term Bindbee does not map     | Display it as-is, and log it |

To see what the provider actually sent, add `include_raw_data=true` to any list or retrieve request - see [Raw Data](/guides/reading-writing/raw-data).

```json theme={null}
{
  "employment_status": "ACTIVE",
  "marital_status": "SINGLE",
  "raw_data": {
    "employmentStatus": "Active",
    "maritalStatus": "S"
  }
}
```

## Finding the values for a field

Look at the field in the API reference. The values it accepts are listed under `enum` and always matches what the API returns today.

## Filtering by enum values

Several list endpoints accept an enum field as a query parameter, such as `employment_status` on `GET /employees`, `employment_type` on `GET /employments`, and `status` on `GET /time-off`.

Filters accept the standard values & any connector-specific value that appears in the response. If a connector returns `Seasonal` on `employment_type`, you can filter on `Seasonal`.

```bash theme={null}
curl -G https://api.bindbee.dev/api/hris/v1/employees \
  -H "Authorization: Bearer <BINDBEE_API_KEY>" \
  -H "X-Connector-Token: <CONNECTOR_TOKEN>" \
  -d employment_status=ACTIVE
```

## Related

<CardGroup cols={2}>
  <Card title="Custom fields" icon="puzzle" href="/guides/extending/custom-fields">
    Surface provider-specific values the unified schema does not represent.
  </Card>

  <Card title="Raw data" icon="file-search" href="/guides/reading-writing/raw-data">
    The untouched upstream payload beside the normalized fields.
  </Card>

  <Card title="Reading data" icon="funnel" href="/guides/reading-writing/reading-data">
    How enum filters combine with `expand`, `modified_after` and pagination.
  </Card>

  <Card title="Get Employees" icon="users" href="/hris/employee/get-employees">
    A generated reference page, with the `enum` list on each field.
  </Card>
</CardGroup>