> ## 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. # Get the Skill inventory report > ![Beta](https://img.shields.io/badge/-Experimental-orange) Get your Skill inventory, the Skill Clusters of your entities, and where these originate from. This report generates a zip file containing the following files: - `dim_{entity_type}.csv` : A list of all entities in the system, containing external IDs and Custom Properties provided in `entity_columns`. - `fact_{entity_type}_property.csv` : A list of Custom Property mappings containing external IDs of the entity, Custom Property name and Custom Property value for all the Custom Properties provided in `entity_properties`. - `dim_skill.csv` : A list of all Skills referred to in the files above containing the external IDs, the name and the description. - `dim_skill_cluster.csv` : A list of all Skill Clusters in the system, containing the name, the Domain name and their Skills. - `fact_{entity_type}_skill_cluster.csv` : A list of the validation state and proficiency level for each combination of Employee and Skill Cluster. - `fact_skill_cluster.csv` : A list of all Skills in each Skill Cluster, containing the Skill Cluster external IDs and Skill external IDs. - `fact_skill_source.csv` : A list containing the source of each Skill of an Employee. ## OpenAPI ````yaml POST /reports/skill_inventory openapi: 3.1.1 info: version: latest contact: name: API Support url: https://www.techwolf.ai/ email: support@techwolf.ai title: Skill Engine API description: > The Skill Engine API is your single stop for continuous Skill tracking, matching, learning management and strategic insights. This API specification describes how to augment your existing data sources with Skills to build your workforce of tomorrow. servers: - description: Skill Engine API url: https://{tenant_name}.{region}.techwolf.ai variables: tenant_name: default: tenant_name region: default: eu3 enum: - eu3 - us3 security: - application: - read - write tags: - name: TaxonomyDomains x-displayName: Domains description: > Domains in the Skill Engine API allow enterprise customers to adapt Domains in their Taxonomy. [Custom Properties]() are supported for this entity. - name: TaxonomySubdomains x-displayName: Subdomains description: > Subdomains in the Skill Engine API allow enterprise customers to adapt Subdomains in their Taxonomy. By default, **Subdomains are disabled**. The 3-level Taxonomy only consists of Domains, Skill Clusters and Skills. Enabling Subdomains allows a 4-level Taxonomy consisting of Domains, Subdomains, Skill Clusters and Skills. To enable Subdomains on your tenants, contact support@techwolf.ai! [Custom Properties]() are supported for this entity. - name: TaxonomySkillClusters x-displayName: Skill Clusters description: > Skill Clusters in the Skill Engine API allow enterprise customers to adapt Skill Clusters in their Taxonomy. [Custom Properties]() are supported for this entity. - name: TaxonomySkills x-displayName: Skills description: > Skills in the Skill Engine API allow enterprise customers to get Skills in their Taxonomy. [Custom Properties]() are supported for this entity. - name: Taxonomy x-displayName: Taxonomy operations description: > Taxonomy operations can be used to view or edit large parts of the Taxonomy. - name: TaxonomyExport x-displayName: Taxonomy description: '' - name: EmployeeCRUD x-displayName: CRUD description: > Employees in the Skill Engine API represent either a person within your organisation or a candidate within the Job market. More info about entities can be found on the [How it Works page](/technology/entities/). [Custom Properties]() are supported for this entity. - name: EmployeeProfile x-displayName: Skill Profile - name: EmployeeMetrics x-displayName: Metrics description: > A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . - name: EmployeeSearch x-displayName: Search - name: EmployeeInteractions x-displayName: Interactions description: >- Interactions can be used to handle Employees interacting with Vacancies or titles in ways that express their desired functions. - name: EmployeeSuggestions x-displayName: Suggestions - name: SkillEvents x-displayName: Skill Events description: > A Skill Event influences the Skillset of an Employee. When an Employee finishes a Course, receives feedback, starts a new function, or when another event occurs that gives additional info to an Employee's Skill Profile, a Skill Event can be generated. Skill Events allow you to monitor the evolution of an Employee's Skill Profile and allow you to pinpoint exactly what Skills your Employees had at a certain time. Skill Events also enable an easy method of adding new information to a profile. Check the how it works article to find out everything you need to know about Skill Events. [How it Works](/technology/skill_events/) - name: VacancyCRUD x-displayName: CRUD description: > Vacancies in the Skill Engine API correspond to Job postings or open positions. More info about entities can be found on the [How it Works page](/technology/entities/). [Custom Properties]() are supported for this entity. - name: VacancyProfile x-displayName: Skill Profile - name: VacancyMetrics x-displayName: Metrics description: > A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . - name: VacancySearch x-displayName: Search - name: CourseCRUD x-displayName: CRUD description: > Courses in the Skill Engine API correspond to internal/external training or education. More info about entities can be found on the [How it Works page](/technology/entities/). [Custom Properties]() are supported for this entity. - name: OrganisationalUnits x-displayName: Organisational Units description: > Organisational Units in the Skill Engine API represent groupings of Employees arranged in a hierarchical structure. [Custom Properties]() are supported for this entity. - name: OrganisationalUnitMetrics x-displayName: Metrics description: > A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . - name: CourseProfile x-displayName: Skill Profile - name: CourseMetrics x-displayName: Metrics description: > A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . - name: SkillClusterCRUD x-displayName: CRUD description: > Skill Clusters in the Skill Engine API allow enterprise customers to use their own Skill Cluster framework. More info about Skill Clusters can be found at the [How it Works page](/technology/skill-clusters/) and the [Skill Cluster Tutorial](/tutorials/skill-clusters/overview/). [Custom Properties]() are supported for this entity. - name: SkillClusterProfile x-displayName: Skill Profile - name: SkillClusterMetrics x-displayName: Metrics description: > A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . - name: CompanyCRUD x-displayName: CRUD description: > An External Company in the Skill Engine API represents **any external company**. They can be used to match against, using the Vacancies that are linked to them. Employment and staffing customers can match candidates with external companies, even when they do not have an explicitly advertised position. Enterprise customers can use External Companies too to profile and compare themselves to other External Companies. More info about External Companies can be found on the [How it Works page](/technology/companies/) and the [External Company tutorial](/tutorials/companies/overview/). [Custom Properties]() are supported for this entity. - name: CompanySearch x-displayName: Search - name: Skill Search - name: Skill Lookup - name: Skill Gaps - name: Vacancy Matching description: > The Skill Engine API allows you to fetch matching entities and External Companies with a wide range of different configurations. The system leverages a set of _filters_ (constraints that are applied before matching, making a binary decision for each entity whether they should be considered) and _weights_ (reweighting of the match scores) to let you tailor results to your wishes. You can find more information about how filters work [here](). Match results can be queried in a paginated manner, allowing you to iteratively fetch all relevant results for a match query using the common `limit` and `offset` setup. Under the hood, the Skill Engine API uses a two-step process to enable paginated results: first, _approximate matching_ is applied to create an initial ordering of results, followed by _refinement_ of these results into the final scores. The ordering of the results, and therefore also the contents of any given page, are determined entirely by the approximate matching. This allows us to provide high volumes of matches without the delay caused by refining all possible matches for every single query. As approximate and refined scores can in some cases deviate from each other slightly, it is expected that in some cases the last result of a given page can have a lower score than the first result of the next -- if this is problematic for your use case (i.e. you want the exact top 10), then we recommend using a higher limit and trimming down results, as this suffices to capture any reordering caused by refinement. By default, a geographic distance filter is applied by default such that only entities within a 50 km range are considered. This range can be adapted by configuring the `max_geo_distance` filter. To retain fast response times, any matching request that has more than 10.000 entities fulfilling all filter criteria will be cut off at the 10.000 entities that are geographically closest to the search point. - name: Job Matching - name: Job Family Matching - name: Task Matching - name: Match Feedback - name: External Company Matching - name: Course Recommendations - name: Export Matching - name: ExportEmployeesSkillClusters x-displayName: Employees description: > Export data from the API through pagination. Request the first page of an export by not specifying the `starting_after` field. Next pages can be requested by setting the `starting_after` field to the last `external_id` from the previous page. When there is no more data after the requested page, `has_next` will be `false`. - name: ExportEmployeeAssignedPosition x-displayName: Employees Assigned Position - name: CoursesExportSkillProfiles x-displayName: Courses description: '' - name: VacanciesExportSkillProfiles x-displayName: Vacancies description: '' - name: JobArchitectureExport x-displayName: Job Architecture description: '' - name: OrganisationalStructureExport x-displayName: Organisational Structure - name: JobFamilyCRUD x-displayName: CRUD description: > Job Families in the Skill Engine API represent a group of Jobs that are related within your organisation. More info about Job Families can be found at the [Job Architecture Tutorial](/tutorials/job_architecture/overview/). [Custom Properties]() are supported for this entity. - name: JobCRUD x-displayName: CRUD description: > Jobs in the Skill Engine API represent a specific role within your organisation. They are linked to Job Families. More info about Jobs can be found at the [Job Architecture Tutorial](/tutorials/job_architecture/overview/). [Custom Properties]() are supported for this entity. - name: Job Family Profile Data description: > Job Family Profile Data influences the Skillset of a Job Family. Profile Data enables an easy method of adding new information to a Job Family. - name: Job Profile Data description: > Job Profile Data influences the skillset of a Job. Profile Data enables an easy method of adding new information to a Job. - name: JobIssues x-displayName: Issues description: |- A Job Issue represents a data issue identified for a particular job, e.g. a missing or short Job description. - name: JobChanges x-displayName: Changes description: >- Job changes represent data changes that were suggested and/or applied to Jobs in the Job Architecture. - name: JobSuggestions x-displayName: Suggestions description: >- Job architecture suggestions represent AI-generated recommendations for changes to job skill profiles, such as adding or removing skills, or updating proficiency levels and criticality flags. - name: JobFamilyProfile x-displayName: Skill Profile - name: JobProfile x-displayName: Skill Profile - name: JobMetrics x-displayName: Metrics description: > A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . - name: PeerGroups x-displayName: Peer Groups description: >- A peer group consists of a list of companies used to create external market Skill Profiles for Jobs. More information about external market Skill Profiles can be found in the documentation of the relevant [endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-skill-profiles). - name: General Reports description: | Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . - name: Employee Reports description: | Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . - name: Vacancy Reports description: | Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . - name: Job Reports description: | Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . - name: Data Maturity Scan description: | Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . - name: Versioning Overview description: > import { ExperimentalBadge } from '/snippets/ExperimentalBadge.mdx' The SkillEngine API is a date-based versioned API system, such that each integrator interacts with a certain version of our product. To know your own version, you can call the `/version` endpoint (description can be found [here](/reference/latest/Version/Version/get-version)). Your version is set by us at the time your tenant is created. This version controls how your API will behave (in terms of supported parameters, response formats, etc.). As it is possible that we introduce breaking changes in future updates that may break your code, we will not update your version **unless you specifically request this**. Breaking changes will always be released under a new date and can be tracked in the documentation [here](). Deprecations will be announced in the documentation and will be supported for a certain period of time. After this period, the deprecation will become a breaking change. Deprecations can be tracked in the documentation [here](). Non-breaking changes, on the other hand, will be supported by your API, **regardless of your version**. An overview can also be found [here](). In case you want to test a specific version of the API, e.g. when switching versions, you can add the header `X-API-Version` to your requests. The value of this header is the version of the API you want to use, for example `2021-03-19`. When you see an endpoint marked with it is considered experimental or in beta. These endpoints can undergo breaking changes without any notice or promises on backwards compatibility. You should not use them in production. - name: Breaking Changes description: > The list below provides an overview of breaking changes to the SkillEngine API. Breaking changes are modifications that may cause your existing integrations to stop working. These changes are only applied to your tenant when you request a version update. ### March 2026 - The `proficiency_level`, `proficiency_float`, and `critical` response fields have been replaced with `governed_proficiency_level`, `inferred_proficiency_level`, `governed_proficiency_float`, `inferred_proficiency_float`, `governed_critical`, and `inferred_critical` on the following endpoints: - `GET /job_architecture/jobs/{job_external_id}/skill_profile` - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` - `POST /job_architecture/export/jobs/skill_profiles` - `POST /job_architecture/export/job_families/skill_profiles` - The `validation_state` field is now always returned on each Skill in the Skill Profile response for the above endpoints. The `include=skill_validation_state` query/body parameter has been removed. - Suggested Skills (with `validation_state: "suggested"`) are now included alongside governed Skills in the Skill Profile response for the above endpoints. ### December 2025 - Changed the `GET /reports/data_maturity_scan/employee_quality_matrix` endpoint to `POST` and added optional `filters` request body to filter by Employee external IDs. - Changed the `GET /reports/data_maturity_scan/job_quality_matrix` endpoint to `POST` and added optional `filters` request body to filter by Job external IDs. ### September 2025 - Removed `translation_found` field from the `GET /employees/suggestions/skills` endpoint. - Removed skill names from unsupported languages from the output of the `GET /employees/suggestions/skills` endpoint. ### August 2025 - Deprecated the `domains` response format from the `GET /courses/{course_external_id}/skill_profile` and the `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints. ### March 2025 - Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/skills` endpoint - Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/skills/{skill_id}` endpoint - Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint - Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/export` endpoint ### February 2025 - Removed the `POST /integrations/file_load_task` endpoint. - Removed the `GET /integrations/file_load_task/{task_id}` endpoint. - Removed the `/job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint. ### January 2025 - Removed the `response_format=trending` query paramter option for all `GET //skill_profile` endpoints. ### December 2024 - Removed the `GET /employees/{external_id}/metrics/position_alignment` endpoint. ### November 2024 - Removed the `POST /vacancies/{external_id}/metrics/fillability` endpoint. - Renamed the value of query parameter `include=description` to `include=skill_description` in the `GET /taxonomy/skills` endpoint. ### October 2024 - Changed the format for duplicate data examples from the `GET /reports/data_maturity_scan/data_improvement_actions` endpoint. - Removed the `POST /reports/skills_alignment` endpoint. - Removed the `POST /reports/workforce_alignment` endpoint. - Removed the `POST /reports/strategy_map` endpoint. - Removed the `POST /reports/skill_frequencies` endpoint. - Removed the `POST /reports/organization_names` endpoint. - Removed the `POST /reports/employee_skill_distribution` endpoint. - Removed the `POST /reports/vacancy_skill_distribution` endpoint. ### September 2024 - Renamed the field `name` to `skill_name` in the `GET /employees/{external_id}/skill_profile` endpoint when the `response_format` query parameter is set to `skill_clusters` or `domains`. ### August 2024 - Removed the `GET /reports/succession_risk` endpoint. - Removed the `GET /reports/employees/skills` endpoint. - Removed the `GET /reports/employees/position_alignment` endpoint. - Removed the `POST /reports/replacement_risk` endpoint. - Removed `count` response body field from the `POST /employees/search` endpoint. - Removed `count` response body field from the `POST /vacancies/search` endpoint. - Removed `count` response body field from the `POST /companies/search` endpoint. - Removed `count` response body field from the `POST /employees/{external_id}/recommended_courses` endpoint. - Removed `count` response body field from the `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` endpoint. - Removed `count` response body field from the `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` endpoint. - Removed `count` response body field from the `POST /employees/{external_id}/matching_vacancies` endpoint. - Removed `count` response body field from the `POST /employees/{external_id}/matching_companies` endpoint. - Removed `count` response body field from the `POST /employees/{external_id}/matching_jobs` endpoint. - Removed `count` response body field from the `POST /employees/{external_id}/matching_job_families` endpoint. - Removed `count` response body field from the `POST /vacancies/{external_id}/matching_employees` endpoint. - Removed `count` response body field from the `POST /companies/{external_id}/matching_employees` endpoint. - Removed `count` response body field from the `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint. - Removed `count` response body field from the `POST /job_architecture/job_families/{external_id}/matching_employees` endpoint. ### July 2024 - Removed the `GET /reports/employees/employability` endpoint. - Removed the `GET /employees/{external_id}/metrics/employability` endpoint. - Removed the `GET /vacancies/{external_id}/metrics/fillability` endpoint. ### June 2024 - Removed support for the `language` filter in the `POST /companies/{external_id}/matching_employees` endpoint. - Removed `feedback_format=skill_clusters` support for the `PATCH /vacancies/{external_id}/skill_profile` endpoint. - Removed `feedback_format=skill_clusters` support for the `PATCH /courses/{external_id}/skill_profile` endpoint. - Removed `response_format=skill_clusters` support for the `GET /vacancies/{external_id}/skill_profile` endpoint. - Removed `response_format=skill_clusters` support for the `GET /courses/{external_id}/skill_profile` endpoint. - Removed the `POST /reports/clustered_trending_skills` endpoint. - Removed the `POST /reports/emerging_skills` endpoint. - Removed the `POST /employees/{external_id}/similar` endpoint. - Removed the `POST /vacancies/{external_id}/similar` endpoint. - Removed the `POST /courses/{external_id}/similar` endpoint. - Removed Occupation entity and its functionalities, along with the Reskilling & Deployment report ### May 2024 - Removed the `include=skill_match_scores` query parameter of `POST /employees/{external_id}/matching_job_families` - Replaced the `skill_type` field with `skill_types` for the `skills` response body field of the `GET /job_architecture/job/{job_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_id}/skill_profile` endpoints. - Replaced the `skill_type` field with `skill_types` for the `skills` field of the `records` response body field of the `POST /job_architecture/export/jobs/skill_profiles`, and `POST /job_architecture/export/job_families/skill_profiles` endpoints. - Replaced the `skill_type` field with `skill_types` for the `skills` field of `skill_clusters` field of the `records` response body field of the `POST /job_architecture/export/jobs/skill_clusters`. ### February 2024 - Removed the `include=skill_clusters` query parameter of `POST /vacancies/{external_id}/matching_employees` and `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`. - Moved the `relevant_experience` response body field of the `response_format=explained` query parameter to the newly added `include=relevant_experience` query parameter of the `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` endpoint. - Renamed the `skill` response body field to `skill_name` of the `GET employees/{external_id}/vacancies/{external_id}/gap` endpoint. ### January 2024 - The `GET /job_architecture/job/{job_id}/skill_profile` endpoint has a new Skill type called `Family-Specific`. - The `GET /job_architecture/job_families/{job_family_id}/skill_profile` endpoint has a new Skill type called `Family-Specific`. ### December 2023 - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /employees/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /occupations/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. - The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /occupations/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. ### November 2023 - Removed the deprecated `GET /employees/{external_id}/profile/related` endpoint. - Removed the deprecated `POST /employees/{external_id}/profile/related` endpoint. - Removed the deprecated `GET /vacancies/{external_id}/profile/related` endpoint. - Removed the deprecated `POST /vacancies/{external_id}/profile/related` endpoint. - Removed the deprecated `GET /courses/{external_id}/profile/related` endpoint. - Removed the deprecated `POST /courses/{external_id}/profile/related` endpoint. - Removed the deprecated `GET /occupations/{external_id}/profile/related` endpoint. - Removed the deprecated `POST /occupations/{external_id}/profile/related` endpoint. - Removed the deprecated `GET /skills/{skill_name}/related` endpoint. ### October 2023 - Remove `POST /skill_clusters` in favor of `POST /taxonomy/skill_clusters`. - Remove `DELETE /skill_clusters/{skill_cluster_id}` in favor of `DELETE /taxonomy/skill_clusters/{skill_cluster_id}`. - Remove `PATCH /skill_clusters/{skill_cluster_id}` in favor of `PATCH /taxonomy/skill_clusters/{skill_cluster_id}`. ### June 2023 - Removed the deprecated `PUT {entity}/{external_id}/skill_profile` endpoint. ### April 2023 - A `skill_event` with `project_content` now assumes a textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). The previous functionality of general project descriptions is removed. ### February 2023 - The `desired_functions` and `non_desired_functions` fields of the Employee have been changed from lists of titles to list of Function objects. A Function object consists of a Function title and a relative importance. ### January 2023 - All instances of `competency`, `competencies` or capitalized alternatives have been renamed to `skill_cluster` and `skill_clusters`, and their capitalized versions. - All instances of `category`, `categories` or capitalized alternatives have been renamed to `domain` and `domains`, and their capitalized versions. ### October 2022 - The `competency` and `score` fields in `PUT, PATCH /{entity}/{external_id}/skill_profile` in `competencies` format are now renamed to `competency_name` and `proficiency_level` respectively. - The `score` fields in `PUT, PATCH /{entity}/{external_id}/skill_profile` in `skills` format is replaced by `has_skill` which is a boolean instead of number. - The `competency` and `score` fields in `GET /{entity}/{external_id}/skill_profile` in `competencies` format are now renamed to `competency_name` and `proficiency_level` respectively. ### July 2022 - The `score` field in `GET /{entity}/{external_id}/skill_profile` in `list` format is now optional. ### June 2022 - Deprecated `GET /employees/{external_id}/recommended_courses` and added POST instead. - Removed `POST /competencies/{external_id}/similar` and `POST /competencies/{external_id}/profile/related` endpoints. ### May 2022 - Removed `PUT /competencies/{external_id}/skill_profile` feedback endpoint. ### November 2021 - Removed Document Entity and all its functionalities. ### July 2021 - Similar Entity endpoints are now `POST` instead of `GET`. - The response format of Similar Entity endpoints has changed from a list to an object containing two fields: the list of results and the total number of results available. ### June 2021 - Search endpoints now require weights in the body, in the same manner as matching endpoints. - Search endpoints now support a `score_min_threshold` query parameter, and defaults to 0.5 for this value instead of the previously internal 0.0. ### April 2021 - The language query parameter has become required for the creation and update of an entity. ### March 2021 - The response format of matching results (`GET/POST /employees/{external_id}/matching_vacancies` , `GET/POST /vacancies/{external_id}/matching_employees` , `GET /employees/{external_id}/matching_companies` and `GET /companies/{external_id}/matching_employees`) has changed from a list to an object containing two fields: the list of results and the total number of results available. - The response format of search results (`POST /employees/search` , `POST /vacancies/search` and `POST /companies/search`) has changed from a list to an object containing two fields: the list of search results and the total number of results available from the free text search. - The response format of list results (`GET /employees/`, `GET /vacancies/` , `GET /companies/`, `GET /courses/`, `GET /competencies/`, `GET /documents/` and `GET /occupations/`) has changed from a list to an object containing two fields: the list of results and the total number of results available. ### February 2021 - Employee creation (`POST /employees`) and updates (`PATCH /employees/{external_id}`) no longer support uploading individual resumes (as `employee_resume`) in favour of accepting a list of multiple resumes (as `employee_documents`) with the same format. - The list entity endpoints (`GET /employees`, `GET /vacancies`, `GET /courses` , `GET /occupations`, `GET /competencies` and `GET /documents`) no longer support the `response_format` query parameter. The response now corresponds to the former `objects` response format for all endpoints. ### January 2021 - The version endpoint now returns a body with a single field `version`, indicating the current version of your tenant. The version is returned as a date (ISO-8601, ex. 2021-01-19) and no longer as a number. - name: Deprecations description: > This section lists all currently deprecated features in the SkillEngine API. Deprecated features will be supported for a certain period of time before being removed. We recommend updating your integration to use the newer alternatives as soon as possible. ### March 2026 - Deprecated the Suggested Skill Profile endpoints. Use the corresponding Skill Profile endpoints instead. The following endpoints are affected: - `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` - `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile` - `POST /job_architecture/export/jobs/suggested_skill_profiles` - `POST /job_architecture/export/job_families/suggested_skill_profiles` ### January 2026 - Deprecated the `GET /taxonomy/changes` endpoint. This endpoint will be replaced by the newly introduced `POST /taxonomy/changes` endpoint. ### December 2023 - Introduced a `skill_id` field alongside Skill names in our API endpoints to avoid ambiguities and conflicts. Using Skill names in a request body to denote or update a Skill is deprecated, please use `skill_id` instead. Existing functionality is backward-compatible. The following endpoints are affected: - `PATCH /employees/{external_id}/skill_profile` - `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` - `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` - `PATCH /vacancies/{external_id}/skill_profile` - `PATCH /courses/{external_id}/skill_profile` - `PATCH /occupations/{external_id}/skill_profile` - name: Compatible Changes description: > The list below gives a sorted overview of non-breaking changes to the SkillEngine API. These changes are immediately available to you and will be supported by your API, regardless of your version. ### June 2026 - Added the `response_format` query parameter to the Job Family task-based matching endpoints (`POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks` and `GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match`). - Added the `match_type` field to each entry in the `similar_tasks` array of the `POST /tasks/validate` response, indicating how the similar Task was found. - Added `skill_source` as an `include` value on `GET /job_architecture/jobs/{job_external_id}/skill_profile`, `GET /employees/{external_id}/skill_profile`, `POST /job_architecture/export/jobs/skill_profiles`, and `POST /export/employees/skill_profiles`. When requested, each Skill in the response gains a `skill_source` field indicating whether the Skill is a custom Skill or originates from the TechWolf vocabulary. - Added the `GET /tasks/{task_id}` endpoint that fetches a single Task by id. - Added the `DELETE /tasks/{task_id}` endpoint that deletes a custom Task. - Added the `POST /tasks` endpoint that creates a custom Task. - Added the optional `source` body parameter to `POST /tasks` that records free-text attribution for a custom Task. - Added the `POST /tasks/validate` endpoint that screens candidate Task names for quality and uniqueness. - Added `task_source` and `enrichment_status` as `include[]` values on `GET /tasks/search` and `POST /export/tasks`, plus `ai_impact` and `hierarchy` on `GET /tasks/search`. - Added the `response_format` query parameter to the task-based matching endpoints (`POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks`, `GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match`, and `POST /tasks/matching`). ### May 2026 - Added a new `POST /tasks/matching` endpoint that returns the symmetric task-based match score between two caller-supplied task sets. - Added a new `POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks` endpoint that returns the Jobs whose task profiles best match the given Job, ranked by task-match score. - Added a new `GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match` endpoint that returns the symmetric task-based match score between two Jobs. - Added a new `POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks` endpoint that returns the Job Families whose task profiles best match the given Job Family, ranked by task-match score. - Added a new `GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match` endpoint that returns the symmetric task-based match score between two Job Families. - Added the `normalized` query parameter to `POST /skills/lookup`. When set to `true`, the endpoint matches Skill names case-insensitively and diacritic-insensitively (Latin diacritics only), so inputs like `Café`, `café`, and `cafe` all resolve to the same Skill. Defaults to `false` (exact match). - Added the `query` field to every entry in the response of `POST /skills/lookup`. It echoes the Skill name as provided in the request body. When `normalized=false`, `query` always equals `skill_name`. When `normalized=true` and the Skill is matched, `query` may differ from `skill_name` in casing or Latin diacritics. On a miss, `skill_name` falls back to the input value, so the field is always non-null. ### April 2026 - Added a new `GET /taxonomy/skills/languages` endpoint that returns the list of language codes available for Skills in the tenant's vocabulary. An optional `external_vendor` query parameter can be provided to retrieve languages for a specific vendor vocabulary. - Extended the `vocab_language` query parameter to support 12 additional language codes **when scoped to the `workday` vendor** (via `external_vendor=workday`): `es` (Spanish), `fr_ca` (French Canadian), `it` (Italian), `ja` (Japanese), `ko` (Korean), `pt_br` (Brazilian Portuguese), `zh_cn` (Simplified Chinese), `zh_tw` (Traditional Chinese), `sv` (Swedish), `fi` (Finnish), `da` (Danish), and `no` (Norwegian). The default TechWolf vocabulary continues to support only `en`, `en_uk`, `en_us`, `de`, `fr`, and `nl`. Use the new `GET /taxonomy/skills/languages` endpoint to discover the exact set of languages available for a given vendor in your tenant. Additionally, IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`, `nb-NO`) are now accepted and mapped to their internal equivalents. This applies to all endpoints that accept the `vocab_language` parameter. ### March 2026 - Added the `low_data_availability` filter to matching endpoints. When `exclude_low_data_availability` is set to `true`, entities with insufficient data for qualitative Skill inference are excluded from matching results. This filter is available on the following endpoints: - `POST /employees/{external_id}/matching_vacancies` - `POST /employees/{external_id}/matching_jobs` - `POST /vacancies/{external_id}/matching_employees` - `POST /job_architecture/jobs/{job_external_id}/matching_employees` - `POST /job_architecture/jobs/{job_external_id}/matching_source_jobs` - `POST /job_architecture/jobs/{job_external_id}/matching_target_jobs` - `POST /job_architecture/job_families/{job_family_external_id}/matching_employees` - `POST /companies/{external_id}/matching_employees` - `POST /employees/{external_id}/metrics/employability` - `POST /export/employees/matching_vacancies` - `POST /export/employees/matching_jobs` - `POST /export/vacancies/matching_employees` - `POST /job_architecture/export/jobs/matching_employees` - Added the `active_only` query parameter to `GET /reports/data_maturity_scan/data_improvement_actions`. When set to `true`, only active Employees and Jobs are included in the Data Improvement Actions. - Added the `category` query parameter to `POST /job_architecture/export/suggestions` and `POST /job_architecture/suggestions/interactions`. Set `category=tasks` to export or interact with task suggestions instead of the default skill suggestions. - Added the `429 Too Many Requests` response to all API endpoints. The API now returns this status code when rate limits are exceeded. - Added a new **Working History Dates** action generator to the Data Improvement Actions report (`GET /reports/data_maturity_scan/data_improvement_actions`). It identifies Working History Skill Events where a duration cannot be calculated due to missing `start_date`, missing `end_date`, or identical start and end dates. Examples are grouped by Employee. - The `include=proficiency_level` parameter on Job and Job Family Skill Profile endpoints now returns `governed_proficiency_level` and `inferred_proficiency_level` fields (instead of `proficiency_level`). Similarly, `include=proficiency_float` returns `governed_proficiency_float` and `inferred_proficiency_float`, and `include=critical` returns `governed_critical` and `inferred_critical`. This applies to the following endpoints: - `GET /job_architecture/jobs/{job_external_id}/skill_profile` - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` - `POST /job_architecture/export/jobs/skill_profiles` - `POST /job_architecture/export/job_families/skill_profiles` - The `validation_state` field is now always included on each Skill in the response of the above endpoints. The `include=skill_validation_state` parameter is no longer needed. - Suggested Skills (with `validation_state: "suggested"`) are now returned alongside governed Skills in the Skill Profile response for the above endpoints. - Added the `strict` query parameter to `POST /employees/{employee_external_id}/skill_events`. When `strict` is enabled, Skill Event creation will fail if the referenced Job has an empty Skill Profile. - Added the `end_active_jobs` query parameter to `POST /employees/{employee_external_id}/skill_events`. When enabled, any currently active working history Skill Event (without an `end_date`) for the Employee will be ended automatically when the new Skill Event is created. ### February 2026 - Added the `include=business_relevant` query parameter to the `POST /export/skills` endpoint to include whether a Skill is marked as business relevant. - Added the `output_skills_sorting` query parameter to `GET /employees/{external_id}/skill_profile` to sort Skills alphabetically or by decreasing confidence. - The `output_skills_sorting` body parameter on `POST /export/employees/skill_profiles` now also works when an external vendor is specified. - Added the `vocab_language` query parameter to the following matching endpoints to specify the display language for Skill names in the response: - `POST /employees/{external_id}/matching_vacancies` - `POST /employees/{external_id}/matching_jobs` - `POST /employees/{external_id}/matching_job_families` - `GET /employees/{employee_external_id}/match_assigned_position` - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` - `GET /employees/{employee_external_id}/jobs/{job_external_id}/match` - `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match` - `POST /vacancies/{external_id}/matching_employees` - `POST /job_architecture/jobs/{job_external_id}/matching_employees` - `GET /job_architecture/jobs/{job_external_id}/market_alignment` - `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` - `POST /job_architecture/jobs/{job_external_id}/matching_source_jobs` - `POST /job_architecture/jobs/{job_external_id}/matching_target_jobs` - `POST /job_architecture/job_families/{job_family_external_id}/matching_employees` - `POST /export/employees/match_assigned_position` - `POST /export/vacancies/matching_employees` - `POST /export/employees/matching_vacancies` - `POST /export/employees/matching_jobs` - `POST /job_architecture/export/jobs/matching_employees` - `POST /job_architecture/export/jobs/market_alignment` - `POST /job_architecture/export/job_families/suggested_skill_profiles` - `POST /job_architecture/export/suggestions` - `POST /employees/{employee_external_id}/recommended_courses` - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` - `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` - `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` - `POST /skills/lookup` - `POST /export/employees/skill_profiles` - `POST /job_architecture/export/jobs/suggested_skill_profiles` - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/gap` - Added the **Work Intelligence Task Profile** endpoints (experimental): - `GET /tasks/search` - Search for Tasks using a fuzzy text query with AI impact information - `GET /employees/{employee_external_id}/task_profile` - Retrieve an Employee's Task Profile with optional AI impact and source event information - `GET /job_architecture/jobs/{job_external_id}/task_profile` - Retrieve a Job's Task Profile with optional AI impact and source data information - `POST /export/employees/task_profiles` - Export Task Profiles for all Employees with pagination and filters - `POST /job_architecture/export/jobs/task_profiles` - Export Task Profiles for all Jobs with pagination and filters - `PATCH /employees/{employee_external_id}/task_profile` - Provide feedback on tasks in an Employee's Task Profile, setting each task's `validation_state` to `validated` or `rejected` - `PATCH /job_architecture/jobs/{job_external_id}/task_profile` - Provide feedback on tasks in a Job's Task Profile, setting each task's `validation_state` to `validated` or `rejected` - `POST /export/tasks` - Bulk export of Tasks. - Added the `inferred_proficiency_level` field to the return of the `POST /employees/suggestions/skills` endpoint when `include=proficiency` is set as a query parameter - Added the `include=inference_enabled` query parameter to indicate whether the Skill can be inferred, applicable to the following endpoints: - `GET /taxonomy/skills` - `GET /taxonomy/skills/{skill_id}` - `GET /taxonomy/export` - `POST /export/skills` ### January 2026 - Added the `vocab_language` query parameter to the following endpoints to specify the display language for Skill names in the response: - `POST /job_architecture/jobs/metrics/adoption_metrics` - `POST /job_architecture/export/job_families/skill_profiles` - `POST /job_architecture/export/jobs/skill_profiles` - `POST /job_architecture/export/jobs/market_skill_profiles` - `POST /employees/metrics/adoption_metrics` - Added the `merge_request` Skill Event type for Employees. When creating or updating Skill Events via `POST /employees/{employee_external_id}/skill_events` or `PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id}`, the `event_type` can now be `merge_request` with content containing `title`, `description`, and `commits` (list of objects with `message`). Merge request events are processed asynchronously to infer skills from the title, description, and commit messages. - Changed the `POST /taxonomy/skills` endpoint to require write_skills scope access. - Added the `DELETE /taxonomy/skills/{skill_id}` endpoint which allows for deleting custom Skills from the system. This endpoint requires write_skills scope access. - Added the `vocab_language` query parameter to the `PATCH /taxonomy/skills/{skill_id}` endpoint to support updating descriptions and names of Skills in different languages. - Added the `skill_source` to the output of the following endpoints: - `GET /taxonomy/skills/{skill_id}` - `GET /taxonomy/skills` - `GET /taxonomy/export` - `POST /export/skills` - Added the `default_skill_name` and `default_skill_description` to the output of the following endpoints: - `GET /taxonomy/skills/{skill_id}` - `GET /taxonomy/skills` - `GET /taxonomy/export` - Added the `include=default_skill_name` and `include=default_skill_description` to the `POST /export/skills` endpoint to add the `default_skill_name` and `default_skill_description` to the output. - Added the `filters` body parameter with the `skill_id_is_in_list` and `skill_source` filters to the `POST /export/skills` endpoint. - Added pagination to the `POST /export/skills` endpoint using the `limit` and `starting_after` body parameters. - Added the `external_vendor` query parameter to the `GET /taxonomy/changes` endpoint to support retrieving Taxonomy Changes in an external vendor's Skill vocabulary. - Added the `create_skill` and `delete_skill` operation types to the `GET /taxonomy/changes` and `POST /taxonomy/apply` endpoints. - Added the `POST /taxonomy/changes` endpoint. - Added the `vocab_update_add_skill` operation type to the `GET /taxonomy/changes` and `POST /taxonomy/changes` endpoint. ### December 2025 - Added the `include_overqualified` and `min_critical_skills_match_ratio` parameters to the employee-job matching endpoints to filter matches based on their overqualification status and on the matching ratio of critical skills. - Enhanced the employee-job matching and match endpoints (`POST /employees/{external_id}/matching_jobs`, `POST /job_architecture/jobs/{job_external_id}/matching_employees`, `POST /matching/export/employees/matching_jobs`, `POST /job_architecture/export/jobs/matching_employees`, `GET /employees/{employee_external_id}/match_assigned_position`, `GET /employees/{employee_external_id}/jobs/{job_external_id}/match`, and `POST /export/employees/match_assigned_position`) to automatically include additional fields when proficiency matching or criticality matching is enabled on the tenant. When proficiency matching is enabled, responses include `overqualified` status (for matching endpoints only), `skill_proficiency`, and `adjacent_skill_proficiency` fields. When criticality matching is enabled, responses include `critical` and `gap_impact` fields. - Added the `include` query parameter to the `GET /reports/data_maturity_scan/job_maturity_overview` and `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints to include additional metrics in the response. - For Jobs: `job_data_count` and `data_distribution`. - For Employees: `valid_assigned_position`, `has_business_data`, and `sufficient_working_history`. - Removed `MIN_SOURCE_CONFIRMATION` from the list of possible reasons in the Data Maturity Scan maturity overview endpoints. - Added the `is_active` query parameter to the `GET /reports/data_maturity_scan/job_maturity_overview` and `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints to filter entities by their active status. - Removed the `force_recalculate` parameter from the `GET /reports/data_maturity_scan/job_maturity_overview` and `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints as the underlying data is now updated continuously. ### November 2025 - Added the `low_data_availability` query paremeter to the `GET /employees` endpoint. - Added the `low_data_availability` and `job_family` query parameters to the `GET /job_architecture/jobs` endpoint. - Added the `job_count` to the output of the `GET /job_architecture/export` endpoint. ### October 2025 - Added the `external_vendor` query parameter to the `PUT /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}` and `DELETE /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}` endpoints to support applying Taxonomy Changes in an external vendor's Skill vocabulary. - Added the `external_vendor` query parameter to the `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills`, `GET /taxonomy/export` and `GET /taxonomy/skills` endpoints to display Skills in an external vendor's Skill vocabulary. - Added the `include=properties` query parameter to the following endpoints to show properties of each Skill: - `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` (List skills in a skill cluster) - `GET /taxonomy/skills` (List all skills) - `POST /export/skills` (Export all skills) - `GET /taxonomy/export` (Taxonomy export) - `GET /taxonomy/skills/{skill_id}` (Get Skill endpoint) - `GET /employees/{external_id}/skill_profile` (Get Employee Skill profile) - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` (Get Skill Profile Job Family) - `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile` (Get suggested skill profile Job Family) - `GET /job_architecture/jobs/{job_external_id}/skill_profile` (Get Skill Profile Job) - `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` (Get suggested skill profile Job) - `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` (Get external market profiles for Job) - `POST /export/employees/skill_profiles` (Export Employee Skill Profile) - `POST /job_architecture/export/jobs/skill_profiles` (Export Job Skill Profile) - `POST /job_architecture/export/jobs/suggested_skill_profiles` (Export Suggested Job Skill Profile) - `POST /job_architecture/export/jobs/market_skill_profiles` (Export Market Job Skill Profile) - `POST /job_architecture/export/job_families/skill_profiles` (Export Job Family Skill Profile) - `POST /job_architecture/export/job_families/suggested_skill_profiles` (Export Job Family Skill Suggested Profile) - Added the `properties` query parameter to the following endpoints to filter skills by their properties: - `POST /employees/suggestions/skills` (Get suggestions, validated and rejected Skills for selected Employees) - `GET /skills/search` (Search for Skills similar to the text provided) The parameter uses the format `properties[property_name]=value` to filter skills that have a specific property with a specific value. For example, `properties[sap_status]=active` will only return skills that have the `sap_status` property set to `active`. - Added the `external_vendor` query parameter to the `PATCH /taxonomy/skills/{skill_id}` endpoint to support updating descriptions and properties of Skills in an external vendor's Skill vocabulary. - Added the `POST /taxonomy/skills` endpoint which allows for creating new Skills in the system, either in TechWolf Skill vocabulary or an external vendor's Skill vocabulary. This endpoint requires admin scope access. - Added the `restore` query parameter to the `POST /employees` endpoint to enable support for restoration of soft deleted Employees during the grace period. - Added the `include=proficiency` and `include=job_critical` to the query parameters of the `GET /employees/{employee_external_id}/suggestions/skills` endpoint to allow the `self_rated_proficiency_level` and `is_job_critical_skill` attributes to be included in the response. - Added the `external_vendor` query parameter to all matching endpoints and some additional endpoints: - `POST /employees/{external_id}/matching_vacancies` - `POST /vacancies/{external_id}/matching_employees` - `POST /employees/{external_id}/matching_jobs` - `POST /job_architecture/jobs/{external_id}/matching_employees` - `POST /job_architecture/jobs/{external_id}/matching_source_jobs` - `POST /job_architecture/jobs/{external_id}/matching_target_jobs` - `POST /employees/{external_id}/matching_job_families` - `POST /job_architecture/job_families/{external_id}/matching_employees` - `POST /employees/{external_id}/matching_companies` - `POST /companies/{external_id}/matching_employees` - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` - `GET /employees/{employee_external_id}/jobs/{job_external_id}/match` - `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match` - `GET /employees/{employee_external_id}/match_assigned_position` - `POST /employees/{employee_external_id}/recommended_courses` - `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` - `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` - `POST /export/employees/match_assigned_position` - `POST /export/employees/matching_jobs` - `POST /export/employees/matching_vacancies` - `POST /export/vacancies/matching_employees` - `POST /job_architecture/export/jobs/matching_employees` - `POST /employees/search` - `POST /companies/search` - `POST /vacancies/search` - `POST /skills/lookup` ### September 2025 - Added the `GET /export/vacancies/skill_profiles` endpoint to paginate through all Skill Profiles of Vacancies in the API in bulk. - Added support to display Skill Profiles in external vendor Skills with the `response_format=list` response format in the `POST /export/courses/skill_profiles` and `POST /export/vacancies/skill_profiles` - Added support to display hierarchical Skill profiles with the `response_format=hierarchy` response format, for the `POST /export/courses/skill_profiles` and the `POST /export/vacancies/skill_profiles` endpoints, both for TechWolf Skills and external vendor Skills. - Added an experimental `POST /export/skills` endpoint that exports the information for all Skills in the system. - Added the `POST /export/employees/matching_jobs` endpoint to export the top matching Jobs for Employees. - Added the `POST /job_architecture/export/jobs/matching_employees` endpoint to export the top matching Employees for Jobs. - Added the `POST /export/employees/matching_vacancies` endpoint to export the top matching Vacancies for Employees. - Added the `POST /export/vacancies/matching_employees` endpoint to export the top matching Employees for Vacancies. - Added the `external_vendor` query parameter to the `POST /taxonomy/apply` endpoint to support applying Taxonomy Changes in an external vendor's Skill vocabulary. ### August 2025 - Added instructions on how to set up OAuth authentication to the Workday Skill Sync Integration documentation. - Added support to display descriptions and domains for external vendor Skills in the `GET /taxonomy/skills/{skill_id}` endpoint. - Added support to display Skill Profiles in external vendor Skills with the `response_format=hierarchy` response format in the `GET /employees/skill_profiles` and `POST /export/employees/skill_profiles` endpoints. - Added support to display hierarchical Skill profiles with the `response_format=hierarchy` response format, for the `GET /courses/{course_external_id}/skill_profile` and the `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints, both for TechWolf Skills and external vendor Skills. ### July 2025 - Add support to display adoption metrics in external vendor Skills in the `POST /job_architecture/jobs/metrics/adoption_metrics` and `POST employees/metrics/adoption_metrics` endpoints. - Add support to display Skill Profiles in external vendor Skills with the `response_format=hierarchy` response format in the `GET /job_architecture/jobs/skill_profiles` and `GET /job_architecture/job_families/skill_profiles` endpoints. - Add support to display Skill Profiles in external vendor Skills in the `POST /job_architecture/export/jobs/skill_profiles` and `POST /job_architecture/export/job_families/skill_profiles` endpoints. - Add support to display the market Skill Profiles in external vendor Skills in the `GET /job_architecture/jobs/market_skill_profiles` and `POST /job_architecture/export/jobs/market_skill_profiles` endpoints. ### June 2025 - Update the `include` parameter in the `GET /employees/{employee_external_id}/skill_profile` endpoint to allow `inferred_proficiency_level` and `inferred_proficiency_float` to be included with `response_format=list`. - Update the `include` body parameter in the `POST export/employees/skill_profiles` endpoint to allow the `self_rated_proficiency_level`, `self_rated_proficiency_float` ,`inferred_proficiency_level` and `inferred_proficiency_float` fields to be included. - Add the `GET /job_architecture/issues` endpoint to fetch Job issues. - Add the `GET /job_architecture/issues/summary` endpoint to get a summary of the number of Job issues per type. - Add the `include=issues` parameter to the `GET /job_architecture/export` endpoint. - Add the `GET /job_architecture/changes` endpoint to fetch Job architecture changes. - Add the `POST /job_architecture/changes` endpoint to start the batch generation of Job changes. - Add the `PATCH /job_architecture/changes` endpoint to bulk update multiple job architecture changes at once. - Add the `GET /job_architecture/changes/summary` endpoint to get a summary of the number of Job changes per type. - Add the `POST /job_architecture/changes/preview` endpoint to generate a preview Job change. - Add the `GET /job_architecture/changes/{change_id}` endpoint to get detailed information about a specific Job architecture change. - Add the `PATCH /job_architecture/changes/{change_id}` endpoint to update a specific Job architecture change with new data. ### May 2025 - Add the `self_rated_proficiency_level` and `self_rated_proficiency_float` attributes to the request body of the `PATCH /employees/{employee_external_id}/skill_profile` endpoint for the `skills` and `external_vendor_skills` feedback formats. - Update the `include` parameter in the `GET /employees/{employee_external_id}/skill_profile` endpoint to allow `self_rated_proficiency_level` and `self_rated_proficiency_float` to be included with `response_format=list`. ### April 2025 - Add the `GET /job_architecture/jobs/market_alignment` and `POST job_architecture/export/jobs/market_alignment` endpoints. ### March 2025 - Add `ticket_system` field to the `ticket` event type to be able to specify the ticketing system where the ticket originated from. This field is important for skill inference as different models may be used for different ticketing systems. ### February 2025 - Allow patching of Organisational Units with `parent_id=null` to become a root Organisational Unit in the `PATCH /organisational_units/{external_id}` endpoint. - Add `GET /job_architecture/peer_groups` endpoint. ### January 2025 - Add the optional `proficiency_float` field to the request body of the `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` and `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. - Add the `include=proficiency_float` option to the include query parameter of the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. - Add the `include=proficiency_float` option to the include body parameter of the `POST /job_architecture/export/jobs/skill_profiles` and `POST /job_architecture/export/job_families/skill_profiles` endpoints. - Add the `external_vendor` query parameter to the `POST /employees/suggestions/skills` endpoint - Remove the `strict` query parameter from the `POST /employees/suggestions/skills` endpoint - Add the `include=critical` option to the include query parameters to the `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` endpoint. - Update the `include` parameter in the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints to allow `proficiency_level` and `critical` to be included with `response_format=hierarchy` - Make the `skill_cluster_description` optional and set it to an empty string by default. Additionally, save any placeholder value or a description that exactly matches the Skill Cluster name as an empty string. ### December 2024 - Add the `include=proficiency_level` and `include=critical` options to the include body parameter of the `POST /job_architecture/export/jobs/skill_profiles` endpoint. - Add the `include=proficiency_level` and `include=critical` options to the include body parameter of the `POST /job_architecture/export/job_families/skill_profiles` endpoint. - Add the `external_vendor` query parameter to the `GET /skills/search` endpoint. - Return the default proficiency level when no proficiency level is set in the `GET /job_architecture/jobs/{job_external_id}/skill_profile`, `POST /job_architecture/export/jobs/skill_profiles`, `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`, and `POST /job_architecture/export/job_families/skill_profiles` endpoints. - Add the `force_recalculate` query parameter to all report endpoints. ### November 2024 - Add `limit`, `offset`, and `update_low_data_availability` query parameters to the `GET /reports/data_maturity_scan/employee_maturity_overview` and `GET /reports/data_maturity_scan/job_maturity_overview` endpoints. - Add `include=skill_cluster_description` parameter to the `GET /taxonomy/skill_clusters` endpoint. - Add `skill_cluster_description` response body field and query parameter `include=skill_cluster_description` to the `GET taxonomy/export` endpoint. - Add the `PATCH /taxonomy/skills/{skill_id}` endpoint. - Return the custom Skill description in the `GET /taxonomy/skills`, `GET /taxonomy/skills/{skill_id}`, and `GET /taxonomy/export` endpoints if one is set. - Add the `update_skill` operation type to the `GET /taxonomy/changes` and `POST /taxonomy/apply` endpoints. - Add `include=skill_description` parameter to the `/taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint. - Add `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` and `POST /job_architecture/export/jobs/market_skill_profiles` endpoints. - Add the `proficiency_level` and `critical` attributes to the request body of the `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` endpoint. - Add the `proficiency_level` and `critical` attributes to the request body of the `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoint. - Add the `include=proficiency_level` and `include=critical` query parameters to the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. ### October 2024 - Add `POST /job_architecture/jobs/metrics/adoption_metrics` endpoint. - Add `POST /employees/metrics/adoption_metrics` endpoint. - Add `source_data` to `skills` returned in `GET/job_architecture/jobs/{job_external_id}/skill_profile` and `GET/job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. - Add CRUD operations for Custom Properties and Custom Property Definitions for Organisational Units. - Add `active` attribute to the Organisational Unit entity. - Add `hierarchy` as a possible response format for the `GET /employees/{employee_external_id}/skill_profile` endpoint. - Add `include=custom_properties` parameter to `GET/job_architecture/job_families`, `GET/job_architecture/jobs`, `GET/courses`, `GET/vacancies`, `GET/employees`, `GET/companies`, `GET/taxonomy/domains`, `GET/taxonomy/subdomains`, `GET/taxonomy/skill_clusters` and `GET/taxonomy/skills` endpoints. - Add `output_skills_sorting` parameter to `GET /job_architecture/export/job_families/suggested_skill_profiles`, `GET /job_architecture/export/job_families/skill_profiles`, `GET /job_architecture/export/jobs/suggested_skill_profiles` and `GET /job_architecture/export/jobs/skill_profiles` endpoints. - Deprecate the `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint. - Add the `vocab_update_rename_skill`, `vocab_update_merge_skill`, and `vocab_update_remove_skill` operation types to the `GET /taxonomy/changes` endpoint. ### September 2024 - Add `GET /job_architecture/jobs/{job_external_id}/matching_source_jobs` endpoint. - Add `GET /job_architecture/jobs/{job_external_id}/matching_target_jobs` endpoint. - Add error code 400 as possible response code for `DELETE /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}` for `DELETE /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}` when trying to delete Skill Profile Feedback instances and respective examples for this - Add `GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}` endpoint. - Add `skill_profile_feedback` as a `data_type` to the Job Family Profile Data of a Job Family. This new `data_type` may be included the responses of `GET /job_architecture/job_families/{job_family_external_id}/profile_data` and `GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}`. - Add `GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}` endpoint. - Add `skill_profile_feedback` as a `data_type` to the Job Profile Data of a Job. This new `data_type` may be included the responses of `GET /job_architecture/jobs/{job_external_id}/profile_data` and `GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}`. - Add `skill_id` query parameter to the `GET /employees` and `GET /organisational_units/export` endpoints that allows for filtering the returned entities on whether their Skill Profile contains a certain Skill. - Add an experimental `POST /employees/suggestions/skill` endpoint that allows to find suggested, validated, and rejected Skill suggestions for Employees. - Add `en_us`, `de`, and `fr` to the list of supported values for the `vocab_language` query parameters in the `GET /{entity}/{external_id}/skill_profile`, `GET /taxonomy/skill_clusters/{external_id}/skills`, `GET /taxonomy/skill/`, and `GET /taxonomy/export/` endpoints. - Add the `low_data_availability_flag` to the possible values of the `include` query parameter of the `GET /organisational_units/export` and `GET /job_architecture/export` endpoints. - Add `skill_id` query parameter to the `GET /job_architecture/export` endpoint that allows for filtering the entities on whether their Skill Profile contains a certain Skill. - Add `source_coverage` metric to the response of the `GET /reports/data_maturity_scan/job_quality_matrix` and `GET /reports/data_maturity_scan/employee_quality_matrix` endpoints. - Add `skill_name`, `skill_cluster_name`, `subdomain_name`, and `domain_name` to the output of `GET /taxonomy/changes`. - Add `subdomain_name` to output of the `POST /job_architecture/export/jobs/skill_clusters`, `POST /export/employees/skill_clusters` and `GET /employees//skill_profile?response_format=skill_clusters` endpoints for 4-level Taxonomies. - Add `source_data` to the output of `GET /jobs/{job_external_id}/suggested_skill_profile`, `GET /job_families/{job_family_external_id}/suggested_skill_profile`, `POST /job_architecture/export/jobs/suggested_skill_profiles`, and `POST /job_architecture/export/job_families/suggested_skill_profiles`. - Add endpoints `POST /integrations/file_load_task` to upload a CSV-file from S3 into the system and `GET /integrations/file_load_task/{task_id}` to get the status of the File Load Task. ### August 2024 - Add `skill_validation_state` to the possible values of the `include` query parameter of the `GET /job_architecture/export/jobs/skill_profiles`, `GET /job_architecture/export/jobs/suggested_skill_profiles`, `GET /job_architecture/export/job_families/skill_profiles`, and `GET /job_architecture/export/job_families/suggested_skill_profiles` endpoints. - Add `skill_validation_state` to the possible values of the `include` query parameter of the `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile` endpoints. - Add `skill_validation_state` to the possible values of the `include` query parameter of the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` endpoints. - Add Employee and Job key metric reports. `GET /reports/employees/key_metrics` `GET /reports/jobs/key_metrics` `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` ### July 2024 - Add CRUD operations for Organisational Units. - Add export endpoint `GET /organisational_units/export` to get the full hierarchy of the Organisational Units including the `total_nr_of_employees` field. - Added `organisational_unit` field to Employees that is returned in `GET /employees` and `GET /employees/{external_id}`. - Added query parameter `organisational_unit` to `GET /employees` to filter Employees on their linked Organisational Unit. - Added the `low_data_availability_flag` to the possible values of the `include` query parameter of the `GET /employees/{external_id}/skill_profile` and `GET /job_architecture/jobs/{job_external_id}/skill_profile` endpoints. - Added the `low_data_availability_flag` to the possible values of the `include` body parameter of the `POST /export/employees/skill_profiles` and `POST /job_architecture/export/jobs/skill_profiles` endpoints that allows including the low data availability flag in the output. - Added the option to upload files of data type `job_description` as Job Profile Data. Available in the `POST /job_architecture/jobs/{job_external_id}/profile_data` and `PATCH /job_architecture/jobs/{job_external_id}/profile_data` endpoint. - Added the option to upload files of data type `job_family_description` as Job Family Profile Data. Available in the `POST /job_architecture/job_families/{job_family_external_id}/profile_data` and `PATCH /job_architecture/job_families/{job_family_external_id}/profile_data` endpoint. ### June 2024 - Add `low_data_availability` attribute to the Employee entity. - Add `low_data_availability` attribute to the Job entity. - Added Data Maturity Scan reporting endpoints: - `GET /reports/data_maturity_scan/employee_quality_matrix` - `GET /reports/data_maturity_scan/job_quality_matrix` - `GET /reports/data_maturity_scan/employee_maturity_overview` - `GET /reports/data_maturity_scan/job_maturity_overview` - `GET /reports/data_maturity_scan/data_improvement_actions` - Added `rejected_skills` to the possible values of the `include` body parameter of the `POST /export/employees/skill_profiles` endpoint that allows including rejected Skills in the output. ### May 2024 - Add `GET /employees/{employee_external_id}/jobs/{job_external_id}/match` endpoint that allows to match an Employee with a Job. - Add `POST /employees/{employee_external_id}/matching_jobs` endpoint that allows to find the top matching Jobs for an Employee. - Add `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint that allows to find the top matching Employees for a Job. - Add `POST /job_architecture/job_families/{external_id}/matching_employees` endpoint that allows to find the top matching Employees for a Job Family. - Add `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` endpoint that recommends Courses to address the Skill Gap between the Employee and the Job. - Add `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match` endpoint that allows to match an Employee with a Job Family. - Add `GET /employees/{employee_external_id}/match_assigned_position` endpoint that allows to match an Employee with their assigned position. - Add `POST /export/employees/match_assigned_position` endpoint that allows to match Employees with their assigned position in bulk. - Add `output_skills_sorting` body parameter to the `POST /export/employees/skill_profiles` endpoint, allowing `alphabetical` to sort the Skills in the resulting profiles alphabetically, or `confidence` to sort them by decreasing confidence. - Add `is_active` filter to the `POST /job_architecture/export/jobs/skill_profiles`, `POST /job_architecture/export/jobs/suggested_skill_profiles`, `POST /job_architecture/export/jobs/skill_clusters`, `POST /job_architecture/export/job_families/skill_profiles`, `POST /job_architecture/export/job_families/suggested_skill_profiles`, `POST /export/employees/skill_profiles`, `POST /export/employees/skill_clusters`, `POST /export/courses/skill_profiles` export endpoints to only include active or inactive entities in the result based on the filter value. - Add `is_active` query parameter to the `GET /job_architecture/export` export endpoint to only include active or inactive jobs and job families in the result. - Add `is_active` query parameter to the `GET /employees`, `GET /vacancies`, `GET /courses`, `GET /job_architecture/jobs`, `GET /job_architecture/job_families` list endpoints to only include active or inactive entities in the result. - Add `include=entity` and `include=custom_properties` query parameter to `POST /employees/{external_id}/matching_job_families`. - Removed `Core` as a possible value of the `skill_type` field of a Skill in the Job Family Skill Profile. - Add `response_format=explained` query parameter to `POST /employees/{external_id}/matching_vacancies`, `POST /vacancies/{external_id}/matching_employees` and `POST /employees/{external_id}/matching_job_families`, that includes `missing_skills` and `present_skills` response body fields as additional information about the matches. - Add `include=adoption` query parameter to the `taxonomy/skills/{skill_id}` endpoint to include the adoption of the Skill in Jobs and Employees in the response. - Add `assigned_position_id` attribute to the Employee entity. - Allow `PATCH /employees//skill_events/` on the `resume_document`, `feedback`, `goal`, `project`, `certificate`, `learning` and `ticket` event types. ### April 2024 - Add `active` attribute to Course, Employee, Job and Job Family entity. - Add support to display Skill Profiles in external vendor Skills on GET, using the query parameter `external_vendor`, for Course, Employee, Job and Job Family entities. Usage: - `GET /employee/{employee_id}/skill_profile?external_vendor={external_vendor}` - `GET /job_architecture/jobs/{job_external_id}/skill_profile?external_vendor={external_vendor}` - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile?external_vendor={external_vendor}` - `GET /courses/{external_id}/skill_profile?external_vendor={external_vendor}` - Add support to provide feedback to Skill Profiles in external vendor Skills, using the query parameter `feedback_format=external_vendor_skills`, for Course, Employee, Job and Job Family entities. Usage: - `PATCH /employee/{employee_id}/feedback_format=external_vendor_skills` - `PATCH /job_architecture/jobs/{job_external_id}/skill_profile?feedback_format=external_vendor_skills` - `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile?feedback_format=external_vendor_skills` - `PATCH /courses/{external_id}/skill_profile?feedback_format=external_vendor_skills` - Deprecate `GET /employee{employee_external_id}/vacancy/{vacancy_external_id}/recommend_courses` - Add `POST /employee{employee_external_id}/vacancy/{vacancy_external_id}/recommend_courses` endpoint which makes use of an updated and improved methodology to recommend Courses. - Update `POST /employee{employee_external_id}/recommend_courses` endpoint in line with the updated and improved methodology to recommend Courses. ### March 2024 - Add `POST /job_architecture/export/jobs/suggested_skill_profiles` endpoint to paginate through all suggested Skill Profiles of Jobs in the API in bulk. - Add `POST /job_architecture/export/job_families/suggested_skill_profiles` endpoint to paginate through all suggested Skill Profiles of Job Families in the API in bulk. - The `domain_namespace` query parameter is available on the `job_architecture/export/jobs/skill_profiles` and `job_architecture/export/job_families/skill_profiles` endpoints. - When requesting an Employee Skill Profile through either `GET /employee/{employee_id}/skill_profile` or `POST /export/employees/skill_profiles`, the response will now include the `source_events` field on all Skills, when requesting sources. `source_events` provides more insights into which Skill Event contributes to which skill. ### February 2024 - Add `GET /employees/{employee_id}/skill_events/{skill_event_id}` endpoint to be able to get a single Skill Event of an Employee. - Add `POST /job_architecture/export/jobs/skill_profiles` endpoint to paginate through all Skill Profiles of Jobs in the API in bulk. - Add `POST /job_architecture/export/job_families/skill_profiles` endpoint to paginate through all Skill Profiles of Job Families in the API in bulk. - Add support for `ticket` Skill Events. - Add support for `skill_notes` Job Profile Data. - Deprecated the `POST /job_architecture/export/job/skill_clusters` endpoint and added the `POST /job_architecture/export/jobs/skill_clusters`. ### January 2024 - A `source` attribute can now be added to each Skill Profile feedback endpoint to indicate the source of the feedback. See all `PATCH /{entity}/{entity_id}/skill_profile` endpoints. - An `include` query parameter can now be added to the `GET /employees/{external_id}/skill_profile` endpoint to include the source Skill Events where the reported Skills are inferred from. - Add `POST /export/employees/skill_profiles` endpoint to get the Skill profiles of all Employees in the API through pagination. - Add the `POST /skills/lookup` endpoint to get corresponding UUIDs for a list of Skill names. - Add `GET /job_architecture/job/{job_id}/suggested_skill_profile` to get suggested skills for a Job. - Add `GET /job_architecture/job_families/{job_family_id}/suggested_skill_profile` to get suggested skills for a Job Family. ### December 2023 - Add the `include=custom_properties` query parameter to the `GET /taxonomy/skills/{skill_id}` endpoint to include the Custom Properties of a Skill in the response. - Add the `include=custom_properties` query parameter to the `GET /taxonomy/skill_clusters/{skill_cluster_id}` endpoint to include the Custom Properties of Skill Clusters in the response. - Add the `include=custom_properties` query parameter to the `GET /taxonomy/subdomains/{subdomain_id}` endpoint to include the Custom Properties of Subdomains in the response. - Add the `include=custom_properties` query parameter to the `GET /taxonomy/domains/{domain_id}` endpoint to include the Custom Properties of Domains in the response. - Introduced a `skill_id` field alongside Skill names in our API endpoints to avoid ambiguities and conflicts. All endpoints that return Skill names will now also return a `skill_id` field. Using Skill names in a request body to denote an update of a Skill is deprecated, please use `skill_id` instead. - Mark all `/occupations` endpoints as deprecated. - Add the `vocab_language` query parameter to the `GET /{entity}/{external_id}/skill_profile` endpoints to specify the language of the Skill names in the Skill Profile response. - Add the `vocab_language` query parameter to the `GET /taxonomy/skill_clusters/{external_id}/skills` endpoint to specify the language of the Skill names in the Skill Profile response. - Add the `vocab_language` query parameter to the `GET /taxonomy/skill/` endpoints to specify the language of the Skill names in the Skill Profile response. - Add the `vocab_language` query parameter to the `GET /taxonomy/export/` endpoints to specify the language of the Skill names in the Skill Profile response. ### November 2023 - Add the `domain_namespace` query parameter to `GET /job_architecture/jobs/{job_external_id}/skill_profile` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. - Add the `domain_namespace` query parameter to `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. - Add the `domain_namespace` query parameter to `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoint to express the Skill domains in either TechWolf or Taxonomy Domains. - Add `domain_name` response body field and `domain_namespace` query parameter to `GET /taxonomy/skills/{skill_id}` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. - Add `domain_name` response body field and `domain_namespace` query parameter to `GET /taxonomy/skills` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. - Add the `domain_namespace` query parameter to `GET /skills/search` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. - Add `POST /export/courses/skill_profiles` endpoint to paginate through all Skill Profiles of Courses in the API in bulk. - Add `last_updated_with_taxonomy_changes` filter to the POST `/export/employees/skill_clusters` and POST `/job_architecture/export/job/skill_clusters` endpoints. - Add `next_starting_after` field to response of `POST /export/employees/skill_clusters` endpoint. ### October 2023 - Add `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint to get the market Skill Profile of a Job. - Update request sample for `POST /reports/job_architecture_benchmark` endpoint. - Mark all `/skill_clusters` endpoints as deprecated. ### September 2023 - Add `skill_description` response body field and query parameter `include=skill_description` to `GET taxonomy/export`. - Add a `vacancy` data type for Job Profile Data. Available in the POST `/job_architecture/jobs/{job_external_id}/profile_data` endpoint. - Add the `taxonomy/changes` endpoint to view all changes to the Taxonomy within a certain timeframe. - Add `skill_id` and `skill_sources` to Skills of response body field in `GET export/employees/skill_clusters`. - Add a `POST /job_architecture/export/job/skill_clusters` endpoint to fetch Job Skill clusters and Skills in bulk. - Add the `Subdomain` entity to enable a 4-level Taxonomy hierarchy. - Add CRUD operations for Custom Properties and Custom Property Definitions for the following Taxonomy entities: `taxonomy/domains`, `taxonomy/subdomains`, `taxonomy/skill_clusters`, and `taxonomy/skills`. - Add `external_id` and `skill_vocab` fields to the `taxonomy/export` and `taxonomy/skill_cluster//skills` endpoints. ### August 2023 - Add `skill_id` response body field and query parameter `search_method` to `POST skills/search`. - Add `GET` and `POST /taxonomy/domains` to see all Domains and create a new Domain respectively. Add `GET`, `PATCH` and `DELETE /taxonomy/domains/{external_id}` to see a single Domain, update a Domain and delete a Domain respectively. - Add `GET` and `POST /taxonomy/skill_clusters` to see all Skill Clusters and create a new Skill Cluster respectively. Add `GET`, `PATCH` and `DELETE /taxonomy/skill_clusters/{external_id}` to see a single Skill Cluster, update a Skill Cluster and delete a Skill Cluster respectively. - Add `GET /taxonomy/skill_clusters/{external_id}/skills` to see all Skills in a Skill Cluster. Add `PUT` and `DELETE /taxonomy/skill_clusters/{external_id}/skills/{skill_external_id}` to add a Skill to a Skill Cluster and remove a Skill from a Skill Cluster respectively. - Add `GET /taxonomy/skills/{concept_uuid}` and `GET /taxonomy/skills` to get meta information of a single Skill or multiple Skills. - Add `GET /taxonomy/export` to export the full structure of the Taxonomy. - Add `POST /taxonomy/apply` to apply a set of changes to the Taxonomy. - Add `skill_id` to the response body of `GET job_architecture/jobs/{job_external_id}/skill_profile` and `GET job_architecture/job_families/{job_family_external_id}/skill_profile`. - Add functionality for Jobs to not be linked to a Job Family. - Skill Profile feedback in Skill Cluster format (`PATCH /employees/{external_id}/skill_profile?feedback_format=skill_clusters`) can now be given with a `skill_cluster_id`. - Add `GET /job_architecture/export`. ### July 2023 - Add `POST /reports/job_architecture_benchmark`. - Add the `include=skill_match_scores` query parameter to the `POST /employees/{external_id}/matching_job_families`, which includes match scores between the Employee and individual Skills in the response. ### June 2023 - Add `POST /reports/internal_talent_mobility`. - Update `POST /reports/skill_inventory`. - Add `GET /employees/{employee_external_id}/interactions` and `GET /employees/{employee_external_id}/interactions/{interaction_external_id}` endpoints, which allow for listing all interactions of an Employee and getting a single Interaction respectively. - Deprecated the `PUT /employees/{external_id}/skill_profile`, `PUT /vacancies/{external_id}/skill_profile`, `PUT /courses/{external_id}/skill_profile` and `PUT /occupations/{external_id}/skill_profile` endpoints. - Add `POST /employees/{employee_external_id}/matching_job_families` endpoint, which calculates and returns matching Job Families for an Employee. Weights are not customizable, but filtering on Custom Properties, external IDs and the `last_updated` field is allowed. - Add the `used_event_types` body parameter to the `POST /employees/{employee_id}/matching_vacancies` endpoint, allowing to use only events of certain types to be taken into account when calculating matching Vacancies for an Employee. ### May 2023 - Vacancy searching now works based on literal text matching by default. Skills based searching is still possible, as well as a combination of both. - Allow `PATCH` on SkillEvents with type `skill_notes`. - Add progress to the `POST /reports/skill_inventory` endpoint. - Add `skill_cluster_id` to the output of Employee, Vacancy, Course, Occupation `GET /{entity}/{external_id}/skill_profile?response_format=skill_clusters` endpoints, the `POST /export/employees/skill_clusters` endpoint, and the `POST /vacancies/{external_id}/matching_employees?include=skill_clusters` endpoint. - Add `POST /employees/{employee_external_id}/interactions` and `DELETE /employees/{employee_external_id}/interactions/{interaction_external_id}` endpoints, which allow the creation and deletion of Interactions between the Employee and a title or Vacancy. - Add `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` and `PATCH /job_architecture/job/{job_external_id}/skill_profile` which allow feedback on the Skill Profile of Job Families and Jobs respectively. - Add a breakdown of the matching Vacancies for a company in the results of the `/companies/search` endpoint. ### April 2023 - Courses can now have a `source` field. When creating Skill Events from a Course with a source, the source of the Course will be used if no source is provided in the Skill Event. - Add `POST /reports/skill_inventory` endpoint to get the Skill Inventory report. ### March 2023 - Add Update `/employees/{employee_external_id}/skill_events/{skill_event_external_id}` endpoint to support updating an Employee's Skill Event. - Add Job and Job Family entities to `job_architecture/jobs` and `job_architecture/job_families` endpoints respectively. - Add Job Profile Data and Job Family Profile Data to the `job_architecture/job_families/{job_family_external_id}/profile_data` and `job_architecture/jobs/{job_external_id}/profile_data` endpoints respectively. - Add `custom_property_is_in_list` filter to `POST employees/{employee_external_id}/recommended_courses`. - Add the `property_value` and `assigned_position` fields of an Employee to the Skill Cluster Adoption report (`reports/employees/skill_cluster_adoption`). - Add `GET job_architecture/jobs/{job_external_id}/skill_profile` and `GET job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints - Add `match_feedback` option for the `include` parameter of the `/employees/{employee_external_id}/matching_vacancies` and `/vacancies/{vacancy_external_id}/matching_employees` endpoints, which includes feedback given to a match in the result if applicable. - Custom Properties have been added to the Job and Job Family entities. They can be requested by using the `custom_properties` include option when sending to the `GET job_architecture/jobs/{job_external_id}` and `GET job_architecture/job_families/{job_family_external_id}` endpoints. - Add Update `/job_architecture/jobs/{job_external_id}/profile_data/{profile_data_external_id}` and Update `/job_architecture/job_families/{job_family_external_id}/profile_data/{profile_data_external_id}` endpoints to support updating Job Profile Data and Job Family Profile Data. - Create or update working history Skill Events using a `job_id` at `POST /employees/{employee_external_id}/skill_events` and `PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id}` respectively ### February 2023 - Add the multi_max_geo_distances filter in matching for endpoints `/employees/{external_id}/matching_vacancies` and `/vacancies/{external_id}/matching_employees`. - Add the Succession Risk Report available under the `/reports/succession_risk` endpoint. - Add the `rejected_skills` include option to the `POST /export/employees/skill_clusters` endpoint. - Add the option to create learning Skill Events from a `course_id` ### January 2023 - Add `competency_type` in `GET /competencies` and `GET /competencies/{external_id}`. - Add support for specifying the location in LocationAddress format in the MaxGeoDistanceFilter. - Add the Replacement Risk Report available under the `/reports/replacement_risk` endpoint. ### December 2022 - The Get Skill Profile endpoints `/entity_type/{external_id}/skill_profile` with `response_format=competencies` now return Skill information. - Add `custom_property_list_overlap` filter for Employee and Vacancy matching. - Add `GET vacancies/{vacancy_external_id}/metrics/fillability` endpoint, which calculates the fillability metric of a Vacancy. The fillability is influenced by the number of matching Employees and the number of Vacancies that can be filled by those Vacancies. More matching Employees will result in a higher fillability, and more matching Vacancies will result in a lower fillability. - Add `POST vacancies/{vacancy_external_id}/metrics/fillability` endpoint which allows for filtering the used entities on maximal allowed distance and Custom Properties, and assigning weights to the different factors used in the fillability calculation. - Add `exclude_match_feedback` filter to `POST employees/{employee_external_id}/recommended_courses` and `POST employees/{employee_external_id}/matching_vacancies` - Add `DELETE` endpoints to `employees/{employee_external_id}/vacancies/{vacancy_external_id}/match_feedback` and `employees/{employee_external_id}/courses/{course_external_id}/match_feedback` - Add `include=competencies` query parameter to `vacancies/{vacancy_external_id}/matching_employees`. - Add `include` query parameter for the `employees/{employee_external_id}/similar` endpoint. Possible values are: `entity`, `competencies` and `custom_properties`. - Add `validation_state` to Skills returned from `GET employees/{employee_external_id}/skill_profile` endpoint in `list` and `competency` format. - Add `validation_state` to Skills returned from `POST export/employees/competencies` endpoint. - Add `exclude_match_feedback` filter to the `employees/search` and `vacancies/search` endpoints. - Add `related_skills` to `include` in `POST export/employees/competencies` endpoint. - Adding a `proficiency_level` to a competency in the body is no longer required when sending feedback via `PUT` or `PATCH` to `/employees/{employee_external_id}/skill_profile?feedback_format=competencies` - Add `score_breakdown` option for the `include` parameter of the `/employees/{employee_external_id}/matching_vacancies` and `/vacancies/{vacancy_external_id}/matching_employees` endpoints, which includes a breakdown of the contribution of all input weights to the total match score in the response body. ### November 2022 - Add the `skill_notes` event type. - Add the Competency Adoption Report available under the `/reports/employees/competency_adoption` endpoint. - Add `POST employees/{employee_external_id}/metrics/employability` endpoint which allows for filtering the used entities on maximal allowed distance and Custom Properties, and assigning weights to the different factors used in the calculation. - Add `PATCH` endpoint to `vacancies/{external_id}/skill_profile`, `occupations/{external_id}/skill_profile` and `courses/{external_id}/skill_profile`. - Add `include=relevant_experience` query parameter to `employees/{employee_external_id}/matching_vacancies` and `vacancies/{vacancy_external_id}/matching_employees`. - For `LocationAddress` inputs, `city` can be used instead of `postal_code` now, making one of them required instead of having `postal_code` required. - The Get Skill Profile endpoints `/entity_type/{ID}/skill_profile` with `response_format=competencies` now return Skill category information. ### October 2022 - Add a not equals option (`neq`) to the `custom_property` filter. - Add `sources` in the `/export/employees/competencies` endpoint, to be able to track from which Skill Events the given competencies originate from. - Add support for addresses as an alternative for location coordinates. ### August 2022 - Add `include` query parameter to `vacancies/{vacancy_external_id}/matching_employees` to allow retrieving Employee information without extra calls. - Add `include=location` query parameter option to `employees/{employee_external_id}/matching_vacancies` - Add a `validation_state` field to the `/export/employees/competencies` response. Indicating whether the competencies linked to Employees are already validated by a manager or Employee or still suggested. ### July 2022 - Add a category field to the `POST /competencies` and `PATCH /competencies/{external_id}` endpoints to change the category of a competency. ### June 2022 - Add a PATCH endpoint for Skill Profile feedback on Employees such that Skill profiles can be partially updated. - Add `last_updated` filter for Employee and Vacancy matching. - Add an experimental `POST /export/employees/competencies` endpoint for extracting Employee competencies and Skills from the API. ### May 2022 - Change how the `GET /competencies/{external_id}/skill_profile` endpoint returns Skill Profiles for clients who use a Taxonomy managed by TechWolf. ### April 2022 - Add support for `project` and `certificate` Skill Events. - Add support for explicit `working_history`, `education_history`, and `resume_document` Skill Events. ### March 2022 - Add support for `feedback` and `goal` Skill Events. ### February 2022 - Add `include` query parameter to `employees/{employee_external_id}/recommended_courses` to allow retrieving Course information without extra calls. ### January 2022 - Add Delete `/employees/{employee_external_id}/skill_events/{skill_event_external_id}` endpoint to support removing an Employee's Skill Event from the API. - Add GET `/employees/{employee_external_id}/skill_events` endpoint to support fetching an Employee's Skill Events of a specified type in the API. The only allowed event type is a `learning_event`. - Add POST `/employees/{employee_external_id}/skill_events` endpoint to support the creation of Skill Events in the API. The only allowed event type is a `learning_event`. ### December 2021 - Add `/employees/{employee_external_id}/recommended_courses` endpoint, returning the recommended Courses to improve an Employee's Skill Profile. - Removed Certificates from Employees and all its functionalities. - The Custom Property weights for the matching endpoints now support the `custom_property_contains`, `custom_property_contains_element` , `custom_property_is_in` and `custom_property_is_in_list` configurations. Match scores are increased when the applied condition on the matching entities' specified Custom Property checks out. - The matching endpoints now support the `language` weight configurations. Match scores are increased when the matching entities' language levels fall between a range of the source entity language levels. ### October 2021 - All endpoints supporting the `explained` response format now return additional category information when the explained response format is requested. - The Get Skill Profile endpoints `/entity_type/{ID}/skill_profile` now support `response_format=categories` and thereby return Skill category information. - The Skill Search endpoint `/skills/search` now returns Skill category information. - The Search endpoints now support German (`de`) language. - You can now create and update entities in German with the `language=de` query parameter. - The Reskilling & Deployment report now provides information for key missing Skills on an Employee-level. ### September 2021 - The `/employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` endpoint with `response_format=explained` query parameter now returns the body with missing Skills included under the `missing_skills` key. - Add external Company hiring activity profiling with NACE-codes under the `/companies/{external_id}/nace` endpoint. - Add the Reskilling & Deployment Report available under the `/reports/reskilling_and_deployment` endpoint. - Reskilling & Deployment report now supports a Qlik-friendly CSV output format. - Reskilling & Deployment report now supports `score_min_threshold`. - The `external_id_is_in_list` filter is now supported for the Job Matching and external Company Matching endpoints. Additionally, this filter is also supported for the Search and Similar endpoints of Employee, Vacancy, and external Company. ### August 2021 - The Employability metric now takes into account the supply of Employees that could fill in the demand as well. - The Search endpoints now support an optional `language` query parameter, to indicate the language of the input text. ### July 2021 - `companies/:external_id/desired_functions` now supports the `PUT` method. Calling this method replaces all existing desired function Vacancies with the new set. - Similar Entity endpoints now support `score_min_threshold`. - Similar Entity endpoints now support Custom Property filters. - Similar Entity endpoints for Employees and Vacancies now support location and language based filters. - Similar Entity endpoints now support Custom Property weights. - Similar Entity endpoints for Employees and Vacancies now support location weight. ### June 2021 - Add the option to override the location used for geo-distance calculation in matching request filters. - `max_geo_distance` field on Employee entities was deprecated. - remove `max_geo_distance` field on Employee entities. ### May 2021 - You can now use a Vacancy-prefix when looking for matching external Companies such that filtering and weighting is based on the Custom Properties of the Vacancies associated with the external company, rather than the external company itself. ### April 2021 - Add strict parameter to entity creation and update operations (Employees, Competencies, Courses, Documents, Occupations, Vacancies). - Change the outward facing side of (non-)desired functions during Employee creation. Output and input now better reflect internal results. - Add languages field to external Companies. - You can now add a geo distance weight to the matching endpoints. Match scores are increased when two entities are in proximity to each other. - You can now add Custom Property weights to the matching endpoints. Match scores are increased when the applied condition on the matching entities' specified Custom Property checks out. - Extraction language can now be specified for the POST `companies/{external_id}/desired_functions` endpoint. ### March 2021 - You can now specify the non-desired functions when creating or updating an Employee to take their negative preference into account when matching to new positions. - You can now modify the non-desired functions boost used during matching by setting the appropriate weight on the match endpoints `employees/{external_id}/matching_vacancies` and `vacancies/{external_id}/matching_employees`. - You can now submit multiple desired functions linked to a given External Company through a single multiline string using the new `request_format=free_text` query parameter on the `/companies/{external_id}/desired_functions` endpoint. - You can now submit free text, multiline strings desired functions & non-desired functions for an Employee through the `desired_functions` & `non_desired_functions` attributes. - You can now search for Vacancies and external Companies based on free text, through the endpoints `/vacancies/search` and `/companies/search`. - You can now add datetime-typed Custom Properties. - You can now provide a list of filters when searching for entities using free text through the endpoints `/employees/search`, `/vacancies/search` and `/companies/search`. - You can now provide multiple values (as a list) when using the `custom_property_contains_element` filter. Entities will not be filtered out if they contain at least one of the provided values in the list Custom Property. - You can now specify the comparison operator when using the `custom_property` filter. If no operator is specified, the filter defaults to the `equals` operator. - You can now specify an offset on matching endpoints for `employees` ,`vacancies` and `companies`. - You can now specify an offset on search endpoints for `employees`,`vacancies` and `companies`. - You can now pass the `null` value for optional fields during creation and updating of all entities. Passing the `null` value during an update will unset the entity's attribute. Objects will be unset as `null`, arrays as the empty array `[]` and strings as the empty string `''`. - External Companies now support Custom Properties. - (Non-)desired function score boosting is now calculated relative to the relevancy of the function title, instead of a binary boost on occurrence of a title. - You can now provide a list of filters at the match endpoints `employees/{external_id}/matching_companies` and `companies/{external_id}/matching_employees`. This will be used to filter out entities that do not need to be considered during matching. - You can now provide a list of weights at the match endpoints `employees/{external_id}/matching_companies` and `companies/{external_id}/matching_employees`. The weights can override some default weights during matching (e.g. desired functions boost). - Custom Property definitions are no longer allowed to contain double underscores in their name. - You can now set the weight of the skills-related match component contributing to the final match score (this was previously hard-coded to 1.0). - You can now filter on the Custom Properties of External Companies linked to a Vacancy, when matching Employees to Vacancies and vice versa. ### February 2021 - You can now search for Employees based on free text, through the endpoint `/employees/search`. - You can add an (optional) External Company link to a Vacancy, through the endpoint `/vacancies` and attribute `company`. - You can now list, create, retrieve, update and delete External Companies through the endpoints `/companies/*`. - You can now optionally mark Vacancies as inactive using the field `active`. When this is field has the value `false`, the Vacancy will not be used for matching. - Deleting External Companies now deletes all linked inactive Vacancies in cascade. - You can now find the best Employees for a given External Company with an overview of its matching Vacancies, through the endpoint `/companies/{external_id}/matching_employees`. - You can now find the best External Companies for a given Employee with an overview of the matching Vacancies per External Company, through the endpoint `/employees/{external_id}/matching_companies`. - You can now upload desired functions as inactive Vacancies linked to a given External Company, through the endpoint `/companies/{external_id}/desired_functions`. - You can now see when an entity was last updated by checking the attribute `last_updated` upon entity retrieval. - You can now provide a list of filters at the match endpoints `employees/{external_id}/matching_vacancies` and `vacancies/{external_id}/matching_employees`. This will be used to filter out entities that do not need to be considered during matching. - You can now provide a list of languages with proficiency levels during Vacancy creation. - You can now provide a list of weights at the match endpoints `employees/{external_id}/matching_vacancies` and `vacancies/{external_id}/matching_employees`. The weights can override some default weights during matching (e.g. desired functions boost). - The POST-type methods on `matching_vacancies` and `matching_employees` are now the preferred way to request the matches. - You can now add a list of strings as a Custom Property. - You can now explicitly provide the language used in Skill Profile extraction during entity creation/update using the `language` query parameter. Supported languages are `auto`, `nl`, `fr` and `en`. - You can now optionally add a Job description to the entries in the working_history of an Employee. These descriptions will also be used for Skill extraction. ### January 2021 - You can add a (optional) `max_geo_distance` attribute when creating an Employee through the endpoint `/employees`. This is used for matching if there is no `max_geo_distance`. provided as query parameter. The default distance in our system when nothing is provided, is 50 km. - name: Authentication description: '' - name: Introduction description: '' - name: Version - name: Filters description: > 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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 { "filter": "last_updated_with_taxonomy_change", "operator": "gt, gte, lt, lte", "value": "datetime" } ``` - name: CustomPropertiesDefinitions x-displayName: Definitions description: > Custom Properties within the Skill Engine API offer users the capability to finely customize attributes for a wide array of entities, including: - [taxonomy/domains](/reference/latest/Taxonomy/TaxonomyDomains) - [taxonomy/subdomains](/reference/latest/Taxonomy/TaxonomySubdomains) - [taxonomy/skill_clusters](/reference/latest/Taxonomy/TaxonomySkillClusters) - [taxonomy/skills](/reference/latest/Taxonomy/TaxonomySkills) - [employees](/reference/latest/Employees) - [organisational_units]() - [job_architecture/job_families]() - [job_architecture/jobs](/reference/latest/Jobs) - [vacancies](/reference/latest/Vacancies) - [courses](/reference/latest/Courses) - [skill_clusters]() - [companies]() More info about entities can be found on the [How it Works page](/technology/entities/). - name: CustomPropertiesProperties x-displayName: Properties - name: TasksCRUD x-displayName: CRUD - name: TaskSearch x-displayName: Task search - name: TaskValidation x-displayName: Task validation - name: ExportTasks x-displayName: Tasks - name: EmployeeTaskProfile x-displayName: Task Profile - name: JobTaskProfile x-displayName: Task Profile paths: /reports/skill_inventory: post: tags: - General Reports summary: Get the Skill inventory report description: > ![Beta](https://img.shields.io/badge/-Experimental-orange) Get your Skill inventory, the Skill Clusters of your entities, and where these originate from. This report generates a zip file containing the following files: - `dim_{entity_type}.csv` : A list of all entities in the system, containing external IDs and Custom Properties provided in `entity_columns`. - `fact_{entity_type}_property.csv` : A list of Custom Property mappings containing external IDs of the entity, Custom Property name and Custom Property value for all the Custom Properties provided in `entity_properties`. - `dim_skill.csv` : A list of all Skills referred to in the files above containing the external IDs, the name and the description. - `dim_skill_cluster.csv` : A list of all Skill Clusters in the system, containing the name, the Domain name and their Skills. - `fact_{entity_type}_skill_cluster.csv` : A list of the validation state and proficiency level for each combination of Employee and Skill Cluster. - `fact_skill_cluster.csv` : A list of all Skills in each Skill Cluster, containing the Skill Cluster external IDs and Skill external IDs. - `fact_skill_source.csv` : A list containing the source of each Skill of an Employee. parameters: - in: query name: force_recalculate required: false schema: type: boolean default: false description: >- Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten. requestBody: description: Filters for the Skill inventory report. required: true content: application/json: schema: type: object required: - entity_type - entity_columns - entity_properties properties: entity_type: type: string minLength: 1 enum: - Employee description: >- Name of the entity type for which the report will be generated. example: employee entity_columns: type: array items: description: A column that is added to the DIM table. type: object required: - column_name - property_name properties: column_name: type: string example: dim_column_name description: > 'The name of the column that is returned in the csv. Assigned column names should be different from the default output columns. Default output columns are: `external_id`, `assigned_position` and `low_data_availability`' property_name: type: string example: dim_property_name description: The name of the Custom Property. description: >- The Custom Property columns that will be included in the `dim_{entity}.csv` file. This can be an empty list. entity_properties: type: array items: description: A property to be added to the fact table. type: object required: - property_name properties: property_name: type: string example: fact_property_name description: The name of the Custom Property. description: >- The Custom Properties that will be included in the `fact_{entity}_properties.csv` file. This can be an empty list. responses: '200': description: OK. content: application/zip: schema: type: string format: binary '202': description: s content: application/json: schema: type: object properties: entity_details: type: object properties: done: type: number description: >- The number of entities that have already been processed. example: 100 total: type: number description: >- The total number of entities that have to be processed. example: 1000 entity_skill_cluster_links: type: object properties: done: type: number description: >- The number of entities that have already been processed. example: 100 total: type: number description: >- The total number of entities that have to be processed. example: 1000 skill_cluster_descriptions: type: object properties: done: type: number description: >- The number of entities that have already been processed. example: 100 total: type: number description: >- The total number of entities that have to be processed. example: 1000 skill_cluster_info: type: object properties: done: type: number description: >- The number of entities that have already been processed. example: 100 total: type: number description: >- The total number of entities that have to be processed. example: 1000 '400': description: Bad request content: application/json: schema: type: object properties: title: type: string description: Name of the error. description: description: Description of the error. anyOf: - type: string - type: object - type: array items: type: string description: Description of the error. example: - title: 400 Bad Request description: The request body was not structured correctly. '401': description: Unauthorized content: application/json: schema: type: object properties: title: type: string description: Name of the error. description: type: string description: Description of the error. example: - title: 401 Unauthorized description: OAuth access token is missing, invalid or expired. '403': description: Forbidden content: application/json: schema: type: object properties: title: type: string description: Name of the error. description: type: string description: Description of the error. example: - title: 403 Forbidden description: You don't have access to this resource. '405': description: Method Not Allowed content: application/json: schema: type: object properties: title: type: string description: Name of the error. description: type: string description: Description of the error. example: - title: 405 Method Not Allowed description: This method is not allowed for the requested URL. '429': description: Too Many Requests content: text/plain: schema: type: string example: 'max connections reached: ' '503': description: Service Unavailable content: application/json: schema: type: object properties: title: type: string description: Name of the error. description: type: string description: Description of the error. example: - title: 503 Service Unavailable description: >- The Skill Engine API is currently not available. Please contact TechWolf or try again later. security: - application: - read components: securitySchemes: application: type: oauth2 flows: clientCredentials: tokenUrl: https://techwolf.eu.auth0.com/oauth/token scopes: write: allows modifying resources read: allows reading resources read_reports: allows reading reports ````