> ## 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.

# Configuring Matches

Two different types of matching configuration are supported: <b>filters</b> and
<b>weights</b>. Filters oppose a hard constraint on the match results, while
weights are a soft constraint.

## Filtering Matches

You can <b>restrict the suitable matches</b> by using filters in the request
body. Below you'll find a concrete example of using filters - if you want to
have the exhaustive list of filters, you can check the Filters section at the
[API reference](</reference/latest/Matching Configuration/Filters/Filters>).

For example, if you want to restrict matching to all the Employees that

* live within 50 km of a Vacancy
* speak the required language level of the Vacancy (or are 2 levels
  overqualified)
* desire a yearly salary less than or equal (`lte`) to €45000
* have the required driving license

you need to submit the following `POST` request to
`vacancies/<external_id>/matching_employees`:

```json theme={null}
{
  "filters": [
    {
      "filter": "max_geo_distance",
      "max_geo_distance": 50
    },
    {
      "filter": "language",
      "max_overqualification": 2,
      "max_underqualification": 0
    },
    {
      "filter": "custom_property",
      "property_name": "desired_salary",
      "operator": "lte",
      "property_value": 45000
    },
    {
      "filter": "custom_property_equal",
      "from_entity_property": "required_driver_license",
      "to_entity_property": "driver_license"
    }
  ],
  "weights": []
}
```

This assumes that you have added the custom properties `required_driver_license`
and `driver_license` upfront (to respectively Vacancy & Employee) as well as the
custom property `desired_salary` to Employees - more info on this can be found
at [the Custom Properties Tutorial](/tutorials/custom-properties/overview/).

If the Employee does not have the custom property `desired_salary` or
`driver_license`, the Employee is not included for matching. If other or more
strict comparisons are needed for the `custom_property` filter on
`desired_salary`, any of the `lt`, `lte`, `eq`, `gte`, `gt` or `neq` operators
are also supported.

In case you want to compare custom properties that are `list[text]` and `text`,
you can also use the `custom_property_is_in` and `custom_property_contains`
filters.

## Match weights

Via the `weights` attribute in the `POST` request body, you can <b>tune the
matching score calculation</b>. You can configure both the contribution of the
skills-match as the (non-)desired functions for Employees. You can also increase
the match score of an entity based on the location or on a custom property.

### The skills-match

The skills-match will provide a score contribution of up to the passed weight,
scaling linearly with the skills-match score

### (Non-)Desired functions

A (non-)desired function will provide a score contribution of up to the passed
weight, with the contribution scaling linearly with the relevancy of the
function title to the matching vacancy. In case of multiple relevant functions,
the most relevant one is used.

In the example below, matching scores will be increased by up to `0.1` when a
Vacancy title resembles a desired function of an Employee.

```json theme={null}
{
  "filters": [],
  "weights": [
    {
      "weight": "skills_match",
      "value": 1.0
    },
    {
      "weight": "desired_functions",
      "value": 0.1
    }
  ]
}
```

### Geo distance

The geo-distance will provide a score contribution when two entities (e.g.
Vacancies and Employees) are in close proximity of each other. A full boost is
applied when the entities are within `full_score_distance` of each other. No
boost is applied when the entities are further away than `zero_score_distance`.
Between the `full_score_distance` and `zero_score_distance`, the boost value
decreases linearly.

In the example below, matching scores will be increased by:

* `0.1` when a Vacancy is within 10km of an Employee.
* `0.05` when a Vacancy is within 30km of an Employee.
* `0.0` when a Vacancy is farther away than 50km of an Employee.

```json theme={null}
{
  "filters": [],
  "weights": [
    {
      "weight": "geo_distance",
      "value": 0.1,
      "full_score_distance": 10,
      "zero_score_distance": 50
    }
  ]
}
```

### Custom properties

The custom property weight will provide a score contribution when the target
entities meet the custom property criteria specified by you.

For example, when submitting a `POST` request to
`vacancies/<external_id>/matching_employees` with the following content, the
Skill Engine API will:

* Increase the match score by `0.05` for the employees that have a desired
  salary less than €45000.
* Increase the match score by `0.1` for the employees that are immediately
  available (assuming the current date is 2021-04-13).
* Increase the match score by `0.05` for the employees that are not a
  freelancer.

```json theme={null}
{
  "filters": [],
  "weights": [
    {
      "weight": "custom_property",
      "property_name": "desired_salary",
      "operator": "lt",
      "property_value": 45000,
      "value": 0.05
    },
    {
      "weight": "custom_property",
      "property_name": "available_from",
      "operator": "lte",
      "property_value": "2021-04-13",
      "value": 0.1
    },
    {
      "weight": "custom_property",
      "property_name": "freelancer",
      "operator": "eq",
      "property_value": false,
      "value": 0.05
    }
  ]
}
```

Note that employees that do not have the custom properties `desired_salary` ,
`available_from` and `freelancer` set, will still be included in the final match
results, but without a boost to their match score.