Skill Engine API (2024-10-09)

Download OpenAPI specification:Download

API Support: support@techwolf.ai URL: https://www.techwolf.ai/

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.

Authentication

The Skill Engine API uses OAuth2 for authentication. You'll receive a client_id, client_secret, audience and tenant from TechWolf to request an Authorization token at https://techwolf.eu.auth0.com/oauth/token with grant_type client_credentials.
Authorization tokens are limited and requesting a new token requires an HTTP request to the token endpoint, slowing down requests. So if you're not using a standard OAuth2 client, make sure to cache this token and reuse it until it expires. The expiry is returned by Auth0 (and also encoded in the token). More information about OAuth2 can be found here.

An example request to the token endpoint is as follows:

curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \
-H 'Accept: application/json'  \
-H 'Content-Type: application/json' \
-d '{"client_id": "abcd12317icwFq2x3f4v4BZlQ2sB5q2i2E",
    "client_secret": "abcd1234JViv17icwFq2x3f4v4BZlQ2sB5q2i2E",
    "audience": "eu3.techwolf.ai",
    "grant_type": "client_credentials",
    "tenant": "company_xyz"}'

The response contains the following attributes:

  • access_token: the token that is to be used in the Authorization header of subsequent API calls
  • expires_in: lifetime of the token
  • scope: access permissions of the token
  • token_type: default Bearer

An example response can be found below:

{
    "access_token": "eyJhbGciOiJSUzI0I0seiEw",
    "expires_in": 10800,
    "scope": "read write"
    "token_type": "Bearer"
}

Scopes

A list of the supported scopes can be found below:

  • read: Grants read access
  • write: Grants write access
  • read_reports: Grants read access to reports (only aggregated info)

You can determine which scopes should be included in your access token by specifying them in the token request. If you don't specificy the scopes, you will receive a token with all possible scopes for your tenant.

curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \
-H 'Accept: application/json'  \
-H 'Content-Type: application/json' \
-d '{"client_id": "abcd12317icwFq2x3f4v4BZlQ2sB5q2i2E",
    "client_secret": "abcd1234JViv17icwFq2x3f4v4BZlQ2sB5q2i2E",
    "audience": "eu3.techwolf.ai",
    "grant_type": "client_credentials",
    "tenant": "company_xyz",
    "scopes": ["read", "read_reports"]}'

Using the token

The token needs to be added in the Authorization header of the subsequent API calls, in the following format Authorization: Bearer {access_token}. To verify if your token works, you can retrieve the version of your tenant via the /version endpoint:

curl -X GET '[server-url]/version' \
    -H 'Accept: application/json'  \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI0I0seiEw'

Want to Know More? More information about the authentication process with OAuth2 can be found on the Auth0 website.

Versioning Overview

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 below).

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

Deprecations will be announced in the documentation and will be supported for a certain period of time. After this period. After this period, the deprecation will become a breaking change. Deprecations can be tracked in the documentation below.

Non-breaking changes, on the other hand, will be supported by your API, ** regardless of your version**. An overview can also be found below.

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 .

Finally, when an endpoint is marked with an Beta tag, this means that it is "in beta" Please note that these endpoints can undergo breaking changes without any notice or promises on backwards compatibility. You should not use them in production.

Breaking Changes

View all breaking changes.

2024-10-07

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

2024-09-20

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

2024-08-29

  • Removed the GET /reports/succession_risk endpoint.

2024-08-27

  • Removed the GET /reports/employees/skills endpoint.

2024-08-21

  • Removed the GET /reports/employees/position_alignment endpoint.

2024-08-20

  • Removed the POST /reports/replacement_risk endpoint.

2024-08-19

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

2024-07-25

  • 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.
  • Removed support for the employee_filters field and renamed the field vacancy_filters to filters for the POST /employees/{external_id}/metrics/employability endpoint.
  • Removed support for the vacancy_filters field and renamed the field employee_filters to filters for the POST /vacancies/{external_id}/metrics/fillability endpoint.

2024-06-20

  • Removed support for the language filter in the POST /companies/{external_id}/matching_employees endpoint.

2024-06-17

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

2024-06-12

  • Removed the POST /employees/{external_id}/similar endpoint.
  • Removed the POST /vacancies/{external_id}/similar endpoint.
  • Removed the POST /courses/{external_id}/similar endpoint.

2024-06-03

  • Removed Occupation entity and its functionalities, along with the Reskilling & Deployment report

2024-05-15

  • Removed the include=skill_match_scores query parameter of POST /employees/{external_id}/matching_job_families

2024-05-13

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

2024-02-05

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

2024-01-24

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

2023-12-18

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

2023-11-09

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

2023-10-10

  • 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}.

2023-06-13

  • Removed the deprecated PUT {entity}/{external_id}/skill_profile endpoint.

2023-04-21

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

2023-02-21

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

2023-01-27

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

2022-10-24

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

2022-10-05

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

2022-07-19

  • The score field in GET /{entity}/{external_id}/skill_profile in list format is now optional.

2022-07-18

  • Deprecated GET /employees/{external_id}/recommended_courses and added POST instead.

2022-06-03

  • Removed POST /competencies/{external_id}/similar and POST /competencies/{external_id}/profile/related endpoints.

2022-05-23

  • Removed PUT /competencies/{external_id}/skill_profile feedback endpoint.

2021-11-09

  • Removed Document Entity and all its functionalities.

2021-07-28

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

2021-06-04

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

2021-04-30

  • The language query parameter has become required for the creation and update of an entity.

2021-03-19

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

2021-02-25

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

2021-02-03

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

2021-01-19

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

Deprecations

View all Deprecations

2023-12-10

  • 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

Compatible Changes

The list below gives a sorted overview of non-breaking changes to the SkillEngine API. These changes are immediately available to you, will be supported by your API, regardless of your version.

View all compatible changes.

October 2024

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

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 POST /organisational_units/metrics endpoint that allows fetching Taxonomy adoption metrics for multiple Organisational Units.
  • 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/<employee_id>/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/<employee_id>/skill_events/<event_id> 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/<skill_custer_id>/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.

Domains

Domains in the Skill Engine API allow enterprise customers to adapt Domains in their Taxonomy.

Custom Properties are supported for this entity.

List Domains

Get a list of all Domains available in the system.

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of entities returned, ordered by the last_updated field and external_id.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for returned entities, results starting from offset up to offset + limit.

Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
503Service Unavailable
get/taxonomy/domains
Response samples
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Domain

Create a new Domain in the system.

Request
Security:
application (write)
Request Body schema: application/json
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

domain_name
required
string [ 1 .. 255 ] characters

Name of the Domain.

Responses
204No Content
400Bad Request
401Unauthorized
403Forbidden
405Method Not Allowed
409Conflict
503Service Unavailable
post/taxonomy/domains
Request samples
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "domain_name": "IT & Engineering"
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Get Domain

Get Domain information stored in the system.

Request
Security:
application (read)
path Parameters
domain_external_id
required
any

The unique Domain ID in your system, consisting of alphanumeric characters, hyphens and underscores.

query Parameters
include
Array of strings

Additional Domain attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.

Items Value: "custom_properties"
Example: include=custom_properties
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/taxonomy/domains/{domain_external_id}
Response samples
    1 more
    503
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "domain_name": "IT & Engineering",
  • "last_updated": "2021-01-21T17:32:28.000Z"
}

Update Domain

Submit the most up-to-date Domain information. Any field that is present will overwrite existing values within the system, while absent fields will be left as is.

Request
Security:
application (write)
path Parameters
domain_external_id
required
any

The unique Domain ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Request Body schema: application/json
domain_name
string [ 1 .. 255 ] characters

Name of the Domain.

Responses
204No Content
400Bad request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
patch/taxonomy/domains/{domain_external_id}
Request samples
application/json
{
  • "domain_name": "IT - HR"
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Delete Domain

Delete Domain information stored inside the system. By deleting a Domain, all Skill Clusters linked to this Domain are also deleted.

Request
Security:
application (write)
path Parameters
domain_external_id
required
any

The unique Domain ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Responses
204No Content
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
delete/taxonomy/domains/{domain_external_id}
Response samples
application/json
[
  • {
    }
]

Subdomains

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.

List Subdomains

Get a list of all Subdomains available in the system.

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of entities returned, ordered by the last_updated field and external_id.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for returned entities, results starting from offset up to offset + limit.

Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
503Service Unavailable
get/taxonomy/subdomains
Response samples
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Subdomain

Create a new Subdomain in the system that is linked to a Domain.

Request
Security:
application (write)
Request Body schema: application/json
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

domain_id
required
string <uuid> [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID of a Domain to which this Subdomain is linked, consisting of alphanumeric characters, hyphens and underscores.

subdomain_name
required
string [ 1 .. 255 ] characters

Name of the Subdomain.

Responses
204No Content
400Bad Request
401Unauthorized
403Forbidden
405Method Not Allowed
409Conflict
503Service Unavailable
post/taxonomy/subdomains
Request samples
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "subdomain_name": "Research"
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Get Subdomain

Get the Subdomain information stored in the system.

Request
Security:
application (read)
path Parameters
subdomain_external_id
required
any

The unique Subdomain ID in your system, consisting of alphanumeric characters, hyphens and underscores.

query Parameters
include
Array of strings

Additional Subdomain attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.

Items Value: "custom_properties"
Example: include=custom_properties
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/taxonomy/subdomains/{subdomain_external_id}
Response samples
    1 more
    503
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "subdomain_name": "Database Management",
  • "last_updated": "2021-01-21T17:32:28.000Z"
}

Update Subdomain

Submit the most up-to-date Subdomain information. Any field that is present will overwrite existing values within the system, while absent fields will be left as is.

Request
Security:
application (write)
path Parameters
subdomain_external_id
required
any

The unique Subdomain ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Request Body schema: application/json
domain_id
string <uuid> [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID of a Domain to which this Subdomain is linked, consisting of alphanumeric characters, hyphens and underscores.

subdomain_name
string [ 1 .. 255 ] characters

Name of the Subdomain.

Responses
204No Content
400Bad request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
patch/taxonomy/subdomains/{subdomain_external_id}
Request samples
application/json
{
  • "domain_id": "b9734761-eb84-42dc-a79f-5e7b1fe897b7",
  • "subdomain_name": "Research"
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Delete Subdomain

Delete Subdomain information stored inside the system.

Request
Security:
application (write)
path Parameters
subdomain_external_id
required
any

The unique Subdomain ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Responses
204No Content
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
delete/taxonomy/subdomains/{subdomain_external_id}
Response samples
application/json
[
  • {
    }
]

Skill Clusters

Skill Clusters in the Skill Engine API allow enterprise customers to adapt Skill Clusters in their Taxonomy.

Custom Properties are supported for this entity.

List Skill Clusters

Get a list of all Skill Clusters available in the system.

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of entities returned, ordered by the last_updated field and external_id.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for returned entities, results starting from offset up to offset + limit.

Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
503Service Unavailable
get/taxonomy/skill_clusters
Response samples
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Skill Cluster

Create a new Skill Cluster in the system that is linked to a Domain or Subdomain. A Skill Cluster must be linked to a Domain in a 3-level Taxonomy, and it can only be linked to a Subdomain in a 4-level Taxonomy.

Request
Security:
application (write)
Request Body schema: application/json
One of:
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

domain_id
required
string <uuid> [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID of a Domain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.

skill_cluster_name
required
string [ 1 .. 255 ] characters

Name of the Skill Cluster.

skill_cluster_description
required
string

Description of the Skill Cluster.

Responses
204No Content
400Bad Request
401Unauthorized
403Forbidden
405Method Not Allowed
409Conflict
503Service Unavailable
post/taxonomy/skill_clusters
Request samples
application/json
3-level Taxonomy
3-level Taxonomy
4-level Taxonomy
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "domain_id": "a84574fd5-eb84-42dc-a79f-595965eacb564",
  • "skill_cluster_name": "Database Management",
  • "skill_cluster_description": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle."
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Get Skill Cluster

Get the Skill Cluster information stored in the system.

Request
Security:
application (read)
path Parameters
skill_cluster_external_id
required
any

The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.

query Parameters
include
Array of strings

Additional Skill Cluster attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.

Items Value: "custom_properties"
Example: include=custom_properties
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/taxonomy/skill_clusters/{skill_cluster_external_id}
Response samples
    1 more
    503
application/json
3-level Taxonomy
3-level Taxonomy
4-level Taxonomy
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "domain_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
  • "skill_cluster_name": "Database Management",
  • "skill_cluster_description": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.",
  • "last_updated": "2021-01-21T17:32:28.000Z"
}

Update Skill Cluster

Submit the most up-to-date Skill Cluster information. Any field that is present will overwrite existing values within the system, while absent fields will be left as is.

Request
Security:
application (write)
path Parameters
skill_cluster_external_id
required
any

The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Request Body schema: application/json
One of:
domain_id
string <uuid> [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID of a Domain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.

skill_cluster_name
string [ 1 .. 255 ] characters

Name of the Skill Cluster.

skill_cluster_description
string

Description of the Skill Cluster.

Responses
204No Content
400Bad request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
patch/taxonomy/skill_clusters/{skill_cluster_external_id}
Request samples
application/json
3-level Taxonomy
3-level Taxonomy
4-level Taxonomy
{
  • "domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "skill_cluster_name": "Database Management",
  • "skill_cluster_description": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle."
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Delete Skill Cluster

Delete Skill Cluster information stored inside the system.

Request
Security:
application (write)
path Parameters
skill_cluster_external_id
required
any

The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Responses
204No Content
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
delete/taxonomy/skill_clusters/{skill_cluster_external_id}
Response samples
application/json
[
  • {
    }
]

List Skills

Get a list of all Skills linked to a Skill Cluster.

Request
Security:
application (read)
path Parameters
skill_cluster_external_id
required
any

The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.

query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of entities returned, ordered by the skill_id field.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for returned entities, results starting from offset up to offset + limit.

vocab_language
string
Default: "en_uk"

The display language used for Skill names. Altering the vocabulary language does not change the Skill Profile; it solely changes the way it is displayed. If not specified, the default language (en_uk) will be used. The en language is an alias for en_uk.

Enum: "en" "en_uk" "en_us" "de" "fr" "nl"
Example: vocab_language=en_uk
Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
503Service Unavailable
get/taxonomy/skill_clusters/{skill_cluster_external_id}/skills
Response samples
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Add Skill

Add a Skill to a Skill Cluster.

Request
Security:
application (write)
path Parameters
skill_cluster_external_id
required
string

The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.

skill_id
required
string <uuid> (SkillId) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The universal unique ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The Skill name connected to this id can be identified by either using the Skill Search endpoint or in any response body that contains that Skill.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
Responses
204No Content
400Bad request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
put/taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

Remove Skill

Remove a Skill from a Skill Cluster.

Request
Security:
application (write)
path Parameters
skill_cluster_external_id
required
any

The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.

skill_id
required
string <uuid> (SkillId) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The universal unique ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The Skill name connected to this id can be identified by either using the Skill Search endpoint or in any response body that contains that Skill.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
Responses
204No Content
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
delete/taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}
Response samples
application/json
[
  • {
    }
]

Skills

Skills in the Skill Engine API allow enterprise customers to get Skills in their Taxonomy.

Custom Properties are supported for this entity.

List Skills

Get the Skill information stored inside the system for multiple Skills.

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of entities returned, ordered by the skill_id field.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for returned entities, results starting from offset up to offset + limit.

vocab_language
string
Default: "en_uk"

The display language used for Skill names. Altering the vocabulary language does not change the Skill Profile; it solely changes the way it is displayed. If not specified, the default language (en_uk) will be used. The en language is an alias for en_uk.

Enum: "en" "en_uk" "en_us" "de" "fr" "nl"
Example: vocab_language=en_uk
include
Array of strings

Additional Skill info attributes that will be included in the response body.

Items Value: "description"
Example: include=description
domain_namespace
string
Default: "techwolf"

The Domain namespace determines the Domains the Skills will be mapped to. Skills are mapped to the Skill Domains of TechWolf by default. Choosing the taxonomy Domain namespace maps the Skills to the Skill Cluster Domains in your Taxonomy.

Enum: "techwolf" "taxonomy"
Example: domain_namespace=taxonomy
Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
422Unprocessable entity
503Service Unavailable
get/taxonomy/skills
Response samples
    1 more
    503
application/json
{
  • "results": [
    ],
  • "count": 2
}

Get Skill

Get the Skill information stored inside the Vocabulary. Meta information such as the adoption of the Skill can also be requested.

Request
Security:
application (read)
path Parameters
skill_id
required
string <uuid> (SkillId) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The universal unique ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The Skill name connected to this id can be identified by either using the Skill Search endpoint or in any response body that contains that Skill.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
include
Array of strings

Additional Skill attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.

Items Enum: "custom_properties" "adoption"
Example: include=custom_properties
vocab_language
string
Default: "en_uk"

The display language used for Skill names. Altering the vocabulary language does not change the Skill Profile; it solely changes the way it is displayed. If not specified, the default language (en_uk) will be used. The en language is an alias for en_uk.

Enum: "en" "en_uk" "en_us" "de" "fr" "nl"
Example: vocab_language=en_uk
domain_namespace
string
Default: "techwolf"

The Domain namespace determines the Domains the Skills will be mapped to. Skills are mapped to the Skill Domains of TechWolf by default. Choosing the taxonomy Domain namespace maps the Skills to the Skill Cluster Domains in your Taxonomy.

Enum: "techwolf" "taxonomy"
Example: domain_namespace=taxonomy
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
422Unprocessable entity
503Service Unavailable
get/taxonomy/skills/{skill_id}
Response samples
    2 more
    422
    503
application/json
{
  • "external_id": null,
  • "skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
  • "skill_name": "SQL",
  • "skill_vocab": "TechWolf",
  • "skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
  • "domain_name": "Information Technology"
}

Taxonomy operations

Taxonomy operations can be used to view or edit large parts of the Taxonomy.

Get Taxonomy changes

Get a list of changes to the Taxonomy within a certain timeframe.

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of Taxonomy changes returned, ordered by their timestamp.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for the returned Taxonomy changes, results starting from offset up to offset + limit.

required
string or string

The earliest timestamp (in IS08601 format) for which you want to retrieve Taxonomy changes.

Example: timestamp_from=2021-01-21T00:00:00.000Z
required
string or string

The latest timestamp (in IS08601 format) for which you want to retrieve Taxonomy changes.

Example: timestamp_to=2022-02-22T00:00:00.000Z
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/taxonomy/changes
Response samples
    1 more
    503
application/json
3-level Taxonomy
3-level Taxonomy
4-level Taxonomy
{
  • "count": 1,
  • "changes": [
    ]
}

Apply Taxonomy changes

Apply a set of changes to the Taxonomy in the system. The changes are applied in the order they are given in the request body.

Request
Security:
application (write)
Request Body schema: application/json
One of:
required
Array of objects (ApplyChange3level)
Responses
204No Content
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
422Unprocessable entity
503Service Unavailable
post/taxonomy/apply
Request samples
application/json
3-level Taxonomy
3-level Taxonomy
4-level Taxonomy
{
  • "changes": [
    ]
}
Response samples
    1 more
    503
application/json
[
  • {
    }
]

CRUD

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.

Custom Properties are supported for this entity.

List Employees

Get a list of all Employees available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100

The maximal number of entities returned, ordered by the last_updated field and external_id.

Example: limit=50
offset
integer >= 0
Default: 0

The applied offset for returned entities, results starting from offset up to offset + limit.

is_active
boolean
Default: "None"

This parameter can be used to only include entities with the active attribute set to true or false. If the parameter is not set, all entities will be included.

Example: is_active=true
organisational_unit
string

This parameter can be used to only include Employees linked to the specified organisational_unit. If organisational_unit="null", only Employees without a linked Organisatioanl Unit are included. If the parameter is not set, all entities will be included.

Example: organisational_unit=c3903505-eb84-42dc-a79f-5d8b1fe897b7
skill_id
string <uuid> [ 1 .. 100 ] characters

The unique ID of a Skill, consisting of alphanumeric characters and hyphens. Setting this query parameter will only include Employees that have this Skill in their Skill Profile.

Example: skill_id=a3903505-eb84-42dc-a79f-5e7b1fe897b7
Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
503Service Unavailable
get/employees
Response samples
application/json
{
  • "count": 3,
  • "results": [
    ]
}

Create Employee

Submit new Employee information to initialise their Skill Profile inside the Skill Engine API.

Request
Security:
application (write)
query Parameters
language
required
string

The language of the input data, which has an impact on the Skill extraction. auto will automatically detect the language used in the provided data.

Enum: "auto" "nl" "fr" "en" "de"
Example: language=en
strict
boolean
Default: true

If strict is enabled, entity creation will fail when a Skill Profile cannot be constructed. If strict is set to false, failed Skill Profile creation will still result in entity creation, but the Skill Profile will be empty.

Request Body schema: application/json
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

assigned_position
string or null (AssignedPositionCRUD) [ 1 .. 255 ] characters

Job title of the Employee's assigned position. Only one of assigned_position or assigned_position_id should be provided upon creation or update.

assigned_position_id
string <uuid> (AssignedPositionIdCRUD) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

external_id of the Job the Employee is assigned to. Only one of assigned_position or assigned_position_id should be provided upon creation or update. The assigned_position is automatically filled in with the job_name of the Job. Upon update or delete of the Job, the assigned_position is also updated accordingly.

active
boolean or null (EmployeeActive)
Default: true

The Employee will not be used in matching if active is false. This is useful when an Employee is being phased out.

organisational_unit
string or null [ 1 .. 255 ] characters [a-zA-Z0-9_-]+

The external ID of the Organisational Unit the Employee is assigned to.

Array of objects or null (WorkExperience)

The working history of an Employee. It is recommended to add these through the Skill Event endpoints as to not overwrite any existing Working History events.

Array of objects or null (Education)

The education history of an Employee. It is recommended to add these through the Skill Event endpoints as to not overwrite any existing Education History events.

Array of objects or null (Language)

List of ISO 639-1 codes for languages spoken by the Employee, combined with the proficiency level. The proficiency levels go from 1 (elementary proficiency) to 5 (native proficiency). If the level is omitted, the default proficiency level of 2 is used.

Array of objects or null (Function)

List of desired functions of the Employee. Elements consist of a title and a relative importance. The title can be either a single-line string or free text. The desired function is only processed and stored when the desired function is recognized by TechWolf AI.

Array of objects or null (Function)

List of non-desired functions of the Employee. Elements consist of a title and a relative importance. The title can be either a single-line string or free text. The non-desired function is only processed and stored when the non-desired function is recognized by TechWolf AI.

Location (object) or LocationAddress (object)

Either a Location object, containing a latitude and longitude, or either a LocationAddress object, containing a country, city and postal code (A state and street address are optional).

Array of objects or null (EmployeeResume)

List of base64 encoded documents (e.g. CVs) related to the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format. It is recommended to add these through the Skill Event endpoints as to not overwrite any existing Resume Document events.

Responses
204No Content
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
409Conflict
413Payload Too Large
415Unsupported Media Type
422Unprocessable entity
503Service Unavailable
post/employees
Request samples
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "assigned_position": "Python Developer",
  • "assigned_position_id": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "active": true,
  • "organisational_unit": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
  • "working_history": [
    ],
  • "education_history": [
    ],
  • "languages": [
    ],
  • "desired_functions": [
    ],
  • "non_desired_functions": [
    ],
  • "location": {
    },
  • "employee_documents": [
    ]
}
Response samples
    5 more
    409
    413
    415
    422
    503
application/json
BadRequestSchema
BadRequestSchema
MaxEntitiesSchema
[
  • {
    }
]

Get Employee

Get the Employee information stored inside the system. As resumes are not stored inside our system, they are not returned in this call.

Request
Security:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
include
Array of strings

Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.

Items Value: "custom_properties"
Example: include=custom_properties
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/employees/{external_id}
Response samples
    1 more
    503
application/json
default
default
custom_properties
{
  • "last_updated": "2021-01-21T17:32:28.000Z",
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "assigned_position": "Python Developer",
  • "assigned_position_id": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "active": true,
  • "low_data_availability": false,
  • "organisational_unit": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
  • "working_history": [
    ],
  • "education_history": [
    ],
  • "languages": [
    ],
  • "desired_functions": [
    ],
  • "non_desired_functions": [
    ],
  • "location": {
    }
}

Update Employee

Submit the most up-to-date Employee information to update their profile inside the system. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is.

Since the Employee resume is deleted after creating a Skill Profile, it is a required field for recalculating the Skill Profile based on the resume. If no resume is provided, the Skill Profile will be recalculated based on the other available properties.

Passing the null value removes non-required attributes. Object attributes will be removed when passing null, arrays with [] and strings with the empty string ''.

Request
Security:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
language
required
string

The language of the input data, which has an impact on the Skill extraction. auto will automatically detect the language used in the provided data.

Enum: "auto" "nl" "fr" "en" "de"
Example: language=en
strict
boolean
Default: true

If strict is enabled, entity creation will fail when a Skill Profile cannot be constructed. If strict is set to false, failed Skill Profile creation will still result in entity creation, but the Skill Profile will be empty.

Request Body schema: application/json
assigned_position
string or null (AssignedPositionCRUD) [ 1 .. 255 ] characters

Job title of the Employee's assigned position. Only one of assigned_position or assigned_position_id should be provided upon creation or update.

assigned_position_id
string <uuid> (AssignedPositionIdCRUD) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

external_id of the Job the Employee is assigned to. Only one of assigned_position or assigned_position_id should be provided upon creation or update. The assigned_position is automatically filled in with the job_name of the Job. Upon update or delete of the Job, the assigned_position is also updated accordingly.

active
boolean or null
Default: true

The Employee will not be used in matching if active is false. This is useful when an Employee is being phased out.

organisational_unit
string or null [ 1 .. 255 ] characters [a-zA-Z0-9_-]+

The external ID of the Organisational Unit the Employee is assigned to.

Array of objects or null (WorkExperience)

The working history of an Employee. It is recommended to add these through the Skill Event endpoints as to not overwrite any existing Working History events.

Array of objects or null (Education)

The education history of an Employee. It is recommended to add these through the Skill Event endpoints as to not overwrite any existing Education History events.

Array of objects or null (Language)

List of ISO 639-1 codes for languages spoken by the Employee, combined with the proficiency level. The proficiency levels go from 1 (elementary proficiency) to 5 (native proficiency). If the level is omitted, the default proficiency level of 2 is used.

Array of objects or null (Function)

List of desired functions of the Employee. Elements consist of a title and a relative importance. The title can be either a single-line string or free text. The desired function is only processed and stored when the desired function is recognized by TechWolf AI.

Array of objects or null (Function)

List of non-desired functions of the Employee. Elements consist of a title and a relative importance. The title can be either a single-line string or free text. The non-desired function is only processed and stored when the non-desired function is recognized by TechWolf AI.

Location (object) or LocationAddress (object)
Array of objects (EmployeeResume)

List of base64 encoded documents (e.g. CVs) related to the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.

Responses
204No Content
400Bad request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
413Payload Too Large
415Unsupported Media Type
422Unprocessable entity
503Service Unavailable
patch/employees/{external_id}
Request samples
application/json
{
  • "assigned_position": "Python Developer",
  • "assigned_position_id": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "active": true,
  • "organisational_unit": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
  • "working_history": [
    ],
  • "education_history": [
    ],
  • "languages": [
    ],
  • "desired_functions": [
    ],
  • "non_desired_functions": [
    ],
  • "location": {
    },
  • "employee_documents": [
    ]
}
Response samples
    4 more
    413
    415
    422
    503
application/json
[
  • {
    }
]

Delete Employee

Remove an Employee from the system. This step deletes all information linked exclusively to this Employee. If these need to be removed as well, make sure to do this separately. By deleting an Employee, you delete their Skill Profile history, which cannot be recreated or recovered afterwards.

Request
Security:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
Responses
204No Content
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
delete/employees/{external_id}
Response samples
application/json
[
  • {
    }
]

Skill Profile

Get the Skill Profile for an Employee

Get an export of the Employee Skill Profile to leverage it for user interaction. Check our tutorials for a clear overview of how to get the most out of each format!

Request
Security:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
response_format
string
Default: "list"

The format of the response profile. More info about adding your Skill Clusters can be found in the tutorials.

Enum: "list" "trending" "skill_clusters" "domains"
Example: response_format=list
vocab_language
string
Default: "en_uk"

The display language used for Skill names. Altering the vocabulary language does not change the Skill Profile; it solely changes the way it is displayed. If not specified, the default language (en_uk) will be used. The en language is an alias for en_uk.

Enum: "en" "en_uk" "en_us" "de" "fr" "nl"
Example: vocab_language=en_uk
include
Array of strings

Additional entity attributes that will be included in the response body. This parameter

Items Enum: "sources" "low_data_availability_flag"
Example: include=sources
external_vendor
string (SupportedExternalVendors)

The external vendor language you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.

Value: "workday"
Example: external_vendor=workday
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/employees/{external_id}/skill_profile
Response samples
    1 more
    503
application/json
EmployeeListSkillProfile
EmployeeListSkillProfile
EmployeeTrendingSkillProfile
EmployeeListSkillClusterProfile
EmployeeDomainsSkillProfile
EmployeeListExternalVendorProfile
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "num_skill_events": 5,
  • "low_data_availability": false,
  • "skills": [
    ]
}

Partially update an Employee Skill Profile with feedback

Provide feedback about an existing Employee Skill Profile to update it inside the system. When the feedback_format query parameter is skills, the body of the feedback message overwrites, adds or updates Skills in the original profile. When the feedback_format query parameter is skill_clusters, this endpoint will change the Skill Cluster Skills in the Skill Profile to fit the given Skill Cluster proficiency level.

Request
Security:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
feedback_format
string
Default: "skills"

The format in which feedback for the Skill Profile is given.

Enum: "skills" "skill_clusters" "external_vendor_skills"
Example: feedback_format=Skills
Request Body schema: application/json
One of:
source
string

The source of the Skill Profile update.

Array of objects (SkillWithRequiredHasSkillArray)

The Skills contained in this profile. Either the skill or the skill_id must be provided, but not both.

Responses
204No Content
400Bad request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
415Unsupported Media Type
503Service Unavailable
patch/employees/{external_id}/skill_profile
Request samples
application/json
SkillProfileUpdateMessage
SkillProfileUpdateMessage
EmployeeSkillClusterProfileUpdateMessage
ExternalVendorSkillProfileUpdateMessage
{
  • "source": "oracle",
  • "skills": [
    ]
}
Response samples
    2 more
    415
    503
application/json
[
  • {
    }
]

Metrics

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 .

Get Employee count

Get the total number of Employee objects stored inside the system.

Request
Security:
application (read)
Responses
200OK
401Unauthorized
403Forbidden
405Method Not Allowed
503Service Unavailable
get/employees/metrics/count
Response samples
application/json
{
  • "entity_type": "Employee",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "count",
  • "metric_value": 1000,
  • "last_update": "2020-09-01T11:45:49Z"
}

Get the employability metric using filters and weights

Retrieve the employability for this Employee. Employability is determined by how well the Employee's top 50 Vacancy opportunities match with the Employee's skill profile. It is reported as a number between 0 and 1, with the upper end indicating that an Employee has many opportunities that match well. The final employability score is calculated by computing a special weighted average of the top 50 Vacancy match scores.

Request
Security:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
response_format
string
Default: "simple"

If set to explained, the response will include an explanation of the match.

Enum: "simple" "explained"
Example: response_format=explained
Request Body schema: application/json
required
Array of max_geo_distance (object) or multi_max_geo_distances (object) or language (object) or last_updated (object) or custom_property_equal (object) or custom_property (object) or custom_property_is_in (object) or custom_property_is_in_list (object) or custom_property_contains (object) or custom_property_contains_element (object) or custom_property_list_overlap (object) or external_id_is_in_list (object) or exclude_match_feedback (object)
required
Array of skills_match (object) or desired_functions (object) or non_desired_functions (object) or geo_distance (object) or language (object) or custom_property (object) or custom_property_is_in (object) or custom_property_is_in_list (object) or custom_property_contains (object) or custom_property_contains_element (object) or custom_property_list_overlap (object)
used_event_types
Array of strings

If not empty, only Skill Events of the types listed here will be taken into account to perform the matching. Learn more about the Skill Event Types at How it works.

Items Enum: "working_history" "education_history" "resume_document" "learning" "goal" "project" "ticket" "certificate" "skill_notes"
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
post/employees/{external_id}/metrics/employability
Request samples
application/json
{
  • "filters": [
    ],
  • "weights": [
    ],
  • "used_event_types": [
    ]
}
Response samples
    1 more
    503
application/json
EmployeeEmployability
EmployeeEmployability
EmployeeEmployabilityExplained
{
  • "entity_type": "Employee",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "configurable_employability",
  • "metric_value": 0.8,
  • "last_update": "2020-09-01T11:45:49Z"
}

Get the position alignment metric

Retrieve the position alignment for this Employee. Position alignment is an indication of the extent to which an Employee fits their assigned position within your company. It is reported as a number between 0 and 1, with the upper end indicating that an Employee is a good fit for their assigned position, while a lower score indicates that the Employee may have some missing Skills.

Request
Security:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) [ 1 .. 100 ] characters [a-zA-Z0-9_-]+

Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.

Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7
query Parameters
response_format
string
Default: "simple"

The format in which the position alignment metric needs to be returned. The simple response format only returns the position alignment score. While the explained response format also returns relevant experience and Skills.

Enum: "simple" "explained"
Example: response_format=simple
Responses
200OK
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
503Service Unavailable
get/employees/{external_id}/metrics/position_alignment
Response samples
    1 more
    503
application/json
EmployeePositionAlignment
EmployeePositionAlignment
ExplainedEmployeePositionAlignment
{
  • "entity_type": "Employee",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "position_alignment",
  • "metric_value": 0.8,
  • "last_update": "2020-09-01T11:45:49Z"
}

Search

Search for Employees based on free text

Search for Employees

Request
Security:
application (read)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The maximal number of results returned.

Example: limit=10
offset
integer >= 0
Default: 0

The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit.

score_min_threshold
number <float> [ 0 .. 1 ]
Default: 0.5

The minimum score of the results. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum.

Example: score_min_threshold=0.7
language
string
Default: "auto"

The language of the input text. auto will automatically detect the language used.

Enum: "auto" "nl" "fr" "en" "de"
Example: language=en
Request Body schema: application/json
text
required
string

Input text.

Location (object) or LocationAddress (object)
required
Array of max_geo_distance (object) or custom_property (object) or custom_property_is_in_list (object) or custom_property_contains_element (object) or external_id_is_in_list (object) or exclude_match_feedback (object)
required
Array of geo_distance (object) or custom_property (object) or desired_functions (object) or non_desired_functions (object) or skills_match (object)
Responses
200OK
400Bad request
401Unauthorized
403Forbidden
405Method Not Allowed
413Payload Too Large