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

# Introduction

> Learn what the filtering feature is and when to use it.

The filtering feature allows your customers to specify which employees they wish to share based on criteria such as work location, employment type, departments, and more. It features a user-friendly configuration interface that you can expose to your customers. We only persist data that belongs to employees matching the configured filters afterward.

<img src="https://mintcdn.com/kombo/wgjPsGjJZE2PEhQP/images/filtering_feature_filtering_ui.gif?s=87678d4d76cbfe1a3a9e04ceb471a585" alt="Filtering UI" width="600" height="303" data-path="images/filtering_feature_filtering_ui.gif" />

# Implementation

## Configuring the Filters

There are two ways to configure the filters: as part of the connection flow and as a standalone configuration.

### As Part of the Connection Flow

To enable filtering for a specific connection flow link, you can use the [create connection link endpoint](/hris/v1/post-connect-create-link) with `enable_filtering` set to `true`. Alternatively, you can do this in the dashboard by flipping the toggle in the connection link creation dialog.

<img src="https://mintcdn.com/kombo/wgjPsGjJZE2PEhQP/images/filtering-enabled.png?fit=max&auto=format&n=wgjPsGjJZE2PEhQP&q=85&s=da5ec175ad0d11acec13f6e1a9b0bc2b" alt="Filtering enabled" width="602" height="194" data-path="images/filtering-enabled.png" />

The filtering UI will open after completing the connection flow. Once the connection is successful, the integration will enter the `SETUP` state and remain there until the filters are configured or confirmed. If the connection flow is closed, you can reopen the old link, which remains valid until the filters are configured, or create a new provisioning link as described below.

### Standalone Configuration

You can also offer the filtering configuration as a standalone feature to set up filters for your existing integrations or to update filters at any time.
You can do this via API with the [create provisioning link endpoint](/hris/v1/post-provisioning-groups-group-id-setup-links) or in the dashboard at the bottom of any integration overview page.

<img src="https://mintcdn.com/kombo/OkxC1UMu0PfEDAZt/images/configure-filters.png?fit=max&auto=format&n=OkxC1UMu0PfEDAZt&q=85&s=5b4421901ab088e580c4adfaee2c845d" alt="Configure Filters" width="1638" height="278" data-path="images/configure-filters.png" />

### Custom Fields

Many customers have custom fields that they want to use for filtering. Common fields include `benefits_eligibility`, `seniority_level`, and `team_name`.
To enable filtering by custom fields, you must [map the fields beforehand](/hris/features/custom-fields). You can also enable your customers to map the custom fields themselves using our [field mapping UI](/hris/features/setup-flow/introduction#field-mapping)

### Active Filters

Once the filters are set, you can view and manage them on the integrations page of the dashboard.

<img src="https://mintcdn.com/kombo/wgjPsGjJZE2PEhQP/images/filtering_feature_expose_dashboard.png?fit=max&auto=format&n=wgjPsGjJZE2PEhQP&q=85&s=51e950053bbfa68b311003a0f657298d" alt="View active filters in the dashboard" width="1458" height="1082" data-path="images/filtering_feature_expose_dashboard.png" />

## Querying the Data

After setting the filters, you can query the data through our API. Our [employees](/hris/v1/get-employees), [absences](/hris/v1/get-absences), and [employments](/hris/v1/get-employments) endpoints will return only the data that belongs to the employees matching the configured filters. However, we will still return all groups, legal entities, work locations, and teams, even if no employee belongs to them. The data is persisted as described [here](/hris/features/filtering/data-policy).

We recommend setting up [webhooks](/hris/guides/webhooks) and reacting to finished syncs to get the filtered data back to your system. By using our `updated_after` and `include_deleted` query params, you can significantly decrease your ingress for big integrations. Employees that go out of scope are treated as deleted.
