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

# Overview

![Beta](https://img.shields.io/badge/Status-Experimental-yellow)

> Filtering is in an experimental phase and breaking changes are possible
> without announcements. Errors occurring when using filters will not be handled
> with the highest priority.

The SkillEngine API provides a syntax to filter the entities returned and used
for a response.

It allows you to find entities with specific properties easily.

Because the SkillEngine API is developed in Django the syntax is fairly similar
to the one used by Django.

{/* Seperator comments are added to prevent back-to-back code blocks being displayed in a tab */}

```php theme={null}
GET /employees?$employees=external_id='1'
# Will only display the employee with external id equal to `1`
# in the response
```

[separator]: #

```php theme={null}
GET /reports/count?$employees=external_id='1'&$jobs=external_id='2'
# Will only use the employee with external id equal to `1` and
# the job with external id equal to `2` when calculating its response
```

Current filterable entities are

* `employees`
* `jobs`
* `job_families`
* `vacancies`
* `courses`

## Operators

The following operators are supported.

* `exact` (default)
* `iexact`
* `contains`
* `icontains`
* `startswith`
* `istartswith`
* `endswith`
* `iendswith`
* `gt`
* `gte`
* `lt`
* `lte`
* `is_null`

The operators can be used by separating the field and operators with `__` like
this

```php theme={null}
GET /employees?$employees=external_id__contains='1'
# Will only display employees of which the external id contains '1'
```

More information on the workings of these operators can be found at
[Django filter reference](https://docs.djangoproject.com/en/5.1/ref/models/querysets/#field-lookups).

For some entities additional operators may be available; in those cases the
behavior of the additional property will be explained in the API reference of
that entity.

## Logical operators (AND, OR, NOT)

Multiple filters can be combined using `and` and `or`; filters can also be
negated by using `not`.

```php theme={null}
GET /employees?$employees=(external_id__startswith='1' or external_id__startswith='2')
# Will only display employees of which the external id either starts with '1' or with '2'
```

[separator]: #

```php theme={null}
GET /employees?$employees=(external_id__contains='1' and external_id__contains='2')
# Will only display employees of which the external id both contains '1' and '2'
```

> The precedence of the operators is `not`, `and`, `or` equal to the operator
> precedence of Python and most other programming languages.

## Related fields

Related fields can also be filtered, meaning you can limit the jobs returned by
filtering on a property of the related job family as follow.

```php theme={null}
GET /jobs?$jobs=job_family__external_id='1'
# Will only display jobs which have the job family with external id equal to '1'
```

## Custom properties

Custom properties can also be used for filtering entities by using the `cp_`
prefix.

```php theme={null}
GET /employees?$employees=cp_language='de'
# Will only display employees that have value 'de' for the customer property
# with property name 'language'
```

## Nuances

When requesting an entity that is filtered out, you will get a 404 Not Found
response, while trying to create this entity will result in a 409 Already Exists
response.

## Addition to other filters

If you have a credential that already has certain filters bound to it, all these
filters will be added on top.

## Limitations

Complex filters might significantly increase response times and database load,
for that reason, the following limitations are in place.

* The number of logical operators can not exceed 5
* Fields allowed for filtering are specified per entity