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

Filtering Matches

You can restrict the suitable matches 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.

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:

{
  "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.

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 tune the matching score calculation. 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.

{
  "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.

{
  "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.

{
  "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.