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

# Filters

A crucial aspect of the configurability of matchmaking inside Skill Engine API
is the use of *filters*. You can see filters as hard constraints that are
applied prior to the calculation of any Skills based match. The filters
available for a matching endpoint are described in the specification of this
endpoint, but for further clarification, this section provides a more complete
overview.

Filters can apply to one side of the matching equation, or can use both. In the
latter case, we distinguish between the **source entity** (the one you are
searching matches for) and the **target entities** (the ones you are searching
for matches within). For example, if you request matches on
`/vacancies/{vid}/matching_employees`, then the source entity is the Vacancy
with external\_id `vid`, while the target entities consist of all Employees
together.

## Single Entity Filters

Single entity filters are always applied to the target entities, irrespective of
the properties of the source entity.

### Custom Property Comparison

The `custom_property` filter is one of the base building blocks for filtering in
Skill Engine API. It filters the target entities using a value you provide
inside the filter itself, and supports equality as well as a range of greater
than / less than varieties. To know if you've applied the filter in the right
direction, it's good to phrase it as: "I want to receive all entities that have
a `property_name` that is `operator` to/than `property_value`". For example, the
filter below results in all entities that have a `wage` Custom Property above
`3000`.

```json theme={null}
{
    "filter": "custom_property",
    "property_name": "wage",
    "property_value": "3000",
    "operator": "gt"
}
```

When looking for matching vacancies, you can use the prefix `company__` before
the actual property name to apply the filter on the Custom Properties of the
external company linked to the Vacancy, rather than on the Custom Properties of
the Vacancies itself. For example if you only want the Vacancies linked to
external Companies that allow telework, the filter would like this:

```json theme={null}
{
    "filter": "custom_property",
    "property_name": "company__telework_policy",
    "property_value": "allowed"
}
```

When looking for matching external companies, the prefix `vacancy__` can be used
before the actual value of `property_name` to apply the filtering to the Custom
Properties associated to the Vacancies linked to the external Companies instead
the external Companies itself.

### Custom Property Contains Element

The `custom_property_contains_element` can be applied to `list[text]` type
Custom Properties, and selects those entities for which the Custom Property
value contains the supplied `property_value`. For example, the filter below
could be used in a situation where Employees indicate the industries they want
to work in -- in that case, the filter selects only the Employees that want to
work in `electronics`.

```json theme={null}
{
    "filter": "custom_property_contains_element",
    "property_name": "industries",
    "property_value": "electronics"
}
```

If you want to require the Custom Property value to contain multiple different
elements, you can simply append more filters, which will create the desired
effect. If you want to filter for entities containing one or more of multiple
elements, you can supply a list of options instead of just one value. To update
our example from above, the filter below selects Employees that want to work in
`electronics`, `chemicals` or both.

```json theme={null}
{
    "filter": "custom_property_contains_element",
    "property_name": "industries",
    "property_value": ["electronics", "chemicals"]
}
```

When looking for matching vacancies, you can use the prefix `company__` before
the actual property name to apply the filter on the Custom Properties of the
external company linked to the Vacancy, rather than on the Custom Properties of
the Vacancies itself. For the example above this would become
`company__industries` .

When looking for matching external companies, the prefix `vacancy__` can be used
before the actual value of `property_name` to apply the filtering to the Custom
Properties associated to the Vacancies linked to the external Companies instead
the external Companies itself.

### Custom Property Is In List

In similar fashion to the contains element filter, the
`custom_property_is_in_list` filter selects entities for which (non-list) Custom
Property `property_name` is contained in the passed list of `possible_values`.
For example, if you're looking for an Employee that wants to work either full
time or part time, you might submit a filter similar to the one below:

```json theme={null}
{
    "filter": "custom_property_is_in_list",
    "property_name": "possible_work_regimes",
    "possible_values": ["fulltime", "parttime"]
}
```

When looking for matching vacancies, you can use the prefix `company__` before
the actual property name to apply the filter on the Custom Properties of the
external company linked to the Vacancy, rather than on the Custom Properties of
the Vacancies itself. For the example above this would become
`company__possible_work_regimes`.

When looking for matching external companies, the prefix `vacancy__` can be used
before the actual value of `property_name` to apply the filtering to the Custom
Properties associated to the Vacancies linked to the external Companies instead
the external Companies itself.

### External ID is in List

This filter allows explicit filtering on external IDs of the target entities.
Any entity not mentioned in the list is excluded.

```json theme={null}
{
    "filter": "external_id_is_in_list",
    "external_ids": ["external_id_1", "external_id_2", "external_id_3"]
}
```

## Entity Relation Filters

Entity relation filters filter the target entities using some relation they may
or may not have with the source entity.

### Geo Distance

This rather simple filter allows you to filter the target entities based on
their distance from the source entity. The distance is expressed in kilometers,
and calculated in a straight line between the two points. If the source entity
has no `location` set, this filter will not have any effect. If the source
entity does have a location, then target entities without a location will not be
considered. If no geo distance filter is provided, Employee/Vacancy matching
defaults to a range of 50km.

```json theme={null}
{
    "filter": "max_geo_distance",
    "max_geo_distance": 50
}
```

### Language

The `language` filter allows you to determine how language requirements are
handled when matching between Employees and Vacancies. As each language
indicated on either of these entity types also has a level, you can tune the
strictness of this filter by modifying `max_underqualification` and
`max_overqualification`. These respective values indicate how many levels below
or above the languages in the source entity those in the target entities are
allowed to be. Checking is only done for languages present in the source entity,
so in case of an empty `languages` attribute on the source side, this filter
will not have any effect. If `max_underqualification` is equal or greater than
the level of one or more languages for the source entity, target entities that
do not mention this language will also be considered valid combinations with it.

```json theme={null}
{
    "filter": "language",
    "max_overqualification": 2,
    "max_underqualification": 1
}
```

### Custom Property Equal

The `custom_property_equal` filter simply checks for equality between properties
on the source and target entities. By providing the name of the property to be
used on the source side as `from_entity_property` and the one on the target side
as `to_entity_property`, you can flexibly choose which Custom Properties to use.

```json theme={null}
{
    "filter": "custom_property_equal",
    "from_entity_property": "employment_type",
    "to_entity_property": "employment_type"
}
```

When the filtering is applied to vacancies, either as `from_entity` or as
`to_entity`, you can use the prefix `company__` before the actual value of
`from_entity_property` or `to_entity_property` to apply the filtering on the
Custom Properties of the external company linked to the Vacancy rather than the
Vacancy itself.

When the filtering is applied to external Companies as `to_entity`, the prefix
`vacancy__` can be used before the actual value of `to_entity_property` to apply
the filtering to the Custom Properties associated to the Vacancies linked to the
external Companies instead the external Companies itself.

### Custom Property Contains

The `custom_property_contains` filter is very similar to the
`custom_property_equal` filter, but instead works with a `list[text]` and `text`
property, checking whether one contains the other. Specifically, this filter
selects the target entities for which the value of `to_entity_property` is a
part of the `from_entity_property` (which must be a list type) of the source
entity. The example below reflects the scenario where an Employee might indicate
in which countries they want to work, so that only Vacancies in one of these
countries can be returned. If the Custom Property is not set for the source
entity, the filter has no effect. If the target entities lack the
`to_entity_property`, they are ignored.

```json theme={null}
{
    "filter": "custom_property_contains",
    "from_entity_property": "allowed_countries",
    "to_entity_property": "country"
}
```

When the filtering is applied to vacancies, either as `from_entity` or as
`to_entity`, you can use the prefix `company__` before the actual value of
`from_entity_property` or `to_entity_property` to apply the filtering on the
Custom Properties of the external company linked to the Vacancy rather than the
Vacancy itself.

When the filtering is applied to external Companies as `to_entity`, the prefix
`vacancy__` can be used before the actual value of `to_entity_property` to apply
the filtering to the Custom Properties associated to the Vacancies linked to the
external Companies instead the external Companies itself.

### Custom Property Is In

The `custom_property_is_in` filter is the mirror image of the
`custom_property_contains` filter. If you apply one type in fetching Vacancies
for a given Employee, then you can transform it into the other to have the
equivalent constraint while fetching Employees for a given Vacancy. The example
below reflects the transformed version of the example given for the contains
filter above.

```json theme={null}
{
    "filter": "custom_property_is_in",
    "from_entity_property": "country",
    "to_entity_property": "allowed_countries"
}
```

When the filtering is applied to vacancies, either as `from_entity` or as
`to_entity`, you can use the prefix `company__` before the actual value of
`from_entity_property` or `to_entity_property` to apply the filtering on the
Custom Properties of the external company linked to the Vacancy rather than the
Vacancy itself.

When the filtering is applied to external Companies as `to_entity`, the prefix
`vacancy__` can be used before the actual value of `to_entity_property` to apply
the filtering to the Custom Properties associated to the Vacancies linked to the
external Companies instead of the external Companies themselves.

### Custom Property List Overlap

The `custom_property_list_overlap` filter checks for overlap between two
`list[text]` Custom Properties. Specifically, this filter selects the target
entities for which at least one of the values in `to_entity_property` (which
must be a list type) is contained in `from_entity_property` of the source
entity. The example below shows a scenario in which an Employee might indicate
in which industries they want to be involved, such that only Vacancies that are
linked to one of these industries will be returned. If the Custom Property is
not set for the source entity, the filter has no effect. Target entities that
lack the `to_entity_property` property are excluded.

```json theme={null}
{
    "filter": "custom_property_list_overlap",
    "from_entity_property": "desired_industries",
    "to_entity_property": "industries"
}
```

When the filtering is applied to Vacancies, either as `from_entity` or as
`to_entity`, you can use the prefix `company__` before the actual value of
`from_entity_property` or `to_entity_property` to apply the filtering on the
Custom Properties of the External Company linked to the Vacancy rather than the
Vacancy itself.

When the filtering is applied to External Companies as `to_entity`, the prefix
`vacancy__` can be used before the actual value of `to_entity_property` to apply
the filtering to the Custom Properties associated to the Vacancies linked to the
External Companies instead the External Companies themselves.

### Last Updated

The `last_updated` filter allows you to filter the target entities based on
`last_updated` property. The filter supports a range of greater than / less than
varieties.

```json theme={null}
{
    "filter": "last_updated",
    "operator": "gt, gte, lt, lte",
    "value": "datetime"
}
```

### Last Updated With Taxonomy Change

The `last_updated_with_taxonomy_change` filter checks if a Taxonomy change took
place within the constraints of the filter. If that it the case, all target
entities are returned, as all can be affected by a Taxonomy change. If no
Taxonomy change took place, the filter operates like a `last_updated` filter.

```json theme={null}
{
    "filter": "last_updated_with_taxonomy_change",
    "operator": "gt, gte, lt, lte",
    "value": "datetime"
}
```