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.

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "filter": "last_updated_with_taxonomy_change",
    "operator": "gt, gte, lt, lte",
    "value": "datetime"
}