Skip to main content
The list below provides an overview of breaking changes to the SkillEngine API. Breaking changes are modifications that may cause your existing integrations to stop working. These changes are only applied to your tenant when you request a version update.

​
March 2026

  • The proficiency_level, proficiency_float, and critical response fields have been replaced with governed_proficiency_level, inferred_proficiency_level, governed_proficiency_float, inferred_proficiency_float, governed_critical, and inferred_critical on the following endpoints:
    • GET /job_architecture/jobs/{job_external_id}/skill_profile
    • GET /job_architecture/job_families/{job_family_external_id}/skill_profile
    • POST /job_architecture/export/jobs/skill_profiles
    • POST /job_architecture/export/job_families/skill_profiles
  • The validation_state field is now always returned on each Skill in the Skill Profile response for the above endpoints. The include=skill_validation_state query/body parameter has been removed.
  • Suggested Skills (with validation_state: "suggested") are now included alongside governed Skills in the Skill Profile response for the above endpoints.

​
December 2025

  • Changed the GET /reports/data_maturity_scan/employee_quality_matrix endpoint to POST and added optional filters request body to filter by Employee external IDs.
  • Changed the GET /reports/data_maturity_scan/job_quality_matrix endpoint to POST and added optional filters request body to filter by Job external IDs.

​
September 2025

  • Removed translation_found field from the GET /employees/suggestions/skills endpoint.
  • Removed skill names from unsupported languages from the output of the GET /employees/suggestions/skills endpoint.

​
August 2025

  • Deprecated the domains response format from the GET /courses/{course_external_id}/skill_profile and the GET /vacancies/{vacancy_external_id}/skill_profile endpoints.

​
March 2025

  • Removed the skill_vocab and external_id fields from the GET /taxonomy/skills endpoint
  • Removed the skill_vocab and external_id fields from the GET /taxonomy/skills/{skill_id} endpoint
  • Removed the skill_vocab and external_id fields from the GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills endpoint
  • Removed the skill_vocab and external_id fields from the GET /taxonomy/export endpoint

​
February 2025

  • Removed the POST /integrations/file_load_task endpoint.
  • Removed the GET /integrations/file_load_task/{task_id} endpoint.
  • Removed the /job_architecture/jobs/{job_external_id}/market_skill_profile endpoint.

​
January 2025

  • Removed the response_format=trending query paramter option for all GET /<entity>/skill_profile endpoints.

​
December 2024

  • Removed the GET /employees/{external_id}/metrics/position_alignment endpoint.

​
November 2024

  • Removed the POST /vacancies/{external_id}/metrics/fillability endpoint.
  • Renamed the value of query parameter include=description to include=skill_description in the GET /taxonomy/skills endpoint.

​
October 2024

  • Changed the format for duplicate data examples from the GET /reports/data_maturity_scan/data_improvement_actions endpoint.
  • Removed the POST /reports/skills_alignment endpoint.
  • Removed the POST /reports/workforce_alignment endpoint.
  • Removed the POST /reports/strategy_map endpoint.
  • Removed the POST /reports/skill_frequencies endpoint.
  • Removed the POST /reports/organization_names endpoint.
  • Removed the POST /reports/employee_skill_distribution endpoint.
  • Removed the POST /reports/vacancy_skill_distribution endpoint.

​
September 2024

  • Renamed the field name to skill_name in the GET /employees/{external_id}/skill_profile endpoint when the response_format query parameter is set to skill_clusters or domains.

​
August 2024

  • Removed the GET /reports/succession_risk endpoint.
  • Removed the GET /reports/employees/skills endpoint.
  • Removed the GET /reports/employees/position_alignment endpoint.
  • Removed the POST /reports/replacement_risk endpoint.
  • Removed count response body field from the POST /employees/search endpoint.
  • Removed count response body field from the POST /vacancies/search endpoint.
  • Removed count response body field from the POST /companies/search endpoint.
  • Removed count response body field from the POST /employees/{external_id}/recommended_courses endpoint.
  • Removed count response body field from the POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses endpoint.
  • Removed count response body field from the POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses endpoint.
  • Removed count response body field from the POST /employees/{external_id}/matching_vacancies endpoint.
  • Removed count response body field from the POST /employees/{external_id}/matching_companies endpoint.
  • Removed count response body field from the POST /employees/{external_id}/matching_jobs endpoint.
  • Removed count response body field from the POST /employees/{external_id}/matching_job_families endpoint.
  • Removed count response body field from the POST /vacancies/{external_id}/matching_employees endpoint.
  • Removed count response body field from the POST /companies/{external_id}/matching_employees endpoint.
  • Removed count response body field from the POST /job_architecture/jobs/{external_id}/matching_employees endpoint.
  • Removed count response body field from the POST /job_architecture/job_families/{external_id}/matching_employees endpoint.

​
July 2024

  • Removed the GET /reports/employees/employability endpoint.
  • Removed the GET /employees/{external_id}/metrics/employability endpoint.
  • Removed the GET /vacancies/{external_id}/metrics/fillability endpoint.

​
June 2024

  • Removed support for the language filter in the POST /companies/{external_id}/matching_employees endpoint.
  • Removed feedback_format=skill_clusters support for the PATCH /vacancies/{external_id}/skill_profile endpoint.
  • Removed feedback_format=skill_clusters support for the PATCH /courses/{external_id}/skill_profile endpoint.
  • Removed response_format=skill_clusters support for the GET /vacancies/{external_id}/skill_profile endpoint.
  • Removed response_format=skill_clusters support for the GET /courses/{external_id}/skill_profile endpoint.
  • Removed the POST /reports/clustered_trending_skills endpoint.
  • Removed the POST /reports/emerging_skills endpoint.
  • Removed the POST /employees/{external_id}/similar endpoint.
  • Removed the POST /vacancies/{external_id}/similar endpoint.
  • Removed the POST /courses/{external_id}/similar endpoint.
  • Removed Occupation entity and its functionalities, along with the Reskilling & Deployment report

​
May 2024

  • Removed the include=skill_match_scores query parameter of POST /employees/{external_id}/matching_job_families
  • Replaced the skill_type field with skill_types for the skills response body field of the GET /job_architecture/job/{job_id}/skill_profile and GET /job_architecture/job_families/{job_family_id}/skill_profile endpoints.
  • Replaced the skill_type field with skill_types for the skills field of the records response body field of the POST /job_architecture/export/jobs/skill_profiles, and POST /job_architecture/export/job_families/skill_profiles endpoints.
  • Replaced the skill_type field with skill_types for the skills field of skill_clusters field of the records response body field of the POST /job_architecture/export/jobs/skill_clusters.

​
February 2024

  • Removed the include=skill_clusters query parameter of POST /vacancies/{external_id}/matching_employees and GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match.
  • Moved the relevant_experience response body field of the response_format=explained query parameter to the newly added include=relevant_experience query parameter of the GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match endpoint.
  • Renamed the skill response body field to skill_name of the GET employees/{external_id}/vacancies/{external_id}/gap endpoint.

​
January 2024

  • The GET /job_architecture/job/{job_id}/skill_profile endpoint has a new Skill type called Family-Specific.
  • The GET /job_architecture/job_families/{job_family_id}/skill_profile endpoint has a new Skill type called Family-Specific.

​
December 2023

  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /employees/{external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /job_architecture/jobs/{job_external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /vacancies/{external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /courses/{external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /occupations/{external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /vacancies/{external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /courses/{external_id}/skill_profile now requires either a skill or a skill_id, not both.
  • The skills request body field of the SkillProfileUpdateMessage of the endpoint PATCH /occupations/{external_id}/skill_profile now requires either a skill or a skill_id, not both.

​
November 2023

  • Removed the deprecated GET /employees/{external_id}/profile/related endpoint.
  • Removed the deprecated POST /employees/{external_id}/profile/related endpoint.
  • Removed the deprecated GET /vacancies/{external_id}/profile/related endpoint.
  • Removed the deprecated POST /vacancies/{external_id}/profile/related endpoint.
  • Removed the deprecated GET /courses/{external_id}/profile/related endpoint.
  • Removed the deprecated POST /courses/{external_id}/profile/related endpoint.
  • Removed the deprecated GET /occupations/{external_id}/profile/related endpoint.
  • Removed the deprecated POST /occupations/{external_id}/profile/related endpoint.
  • Removed the deprecated GET /skills/{skill_name}/related endpoint.

​
October 2023

  • Remove POST /skill_clusters in favor of POST /taxonomy/skill_clusters.
  • Remove DELETE /skill_clusters/{skill_cluster_id} in favor of DELETE /taxonomy/skill_clusters/{skill_cluster_id}.
  • Remove PATCH /skill_clusters/{skill_cluster_id} in favor of PATCH /taxonomy/skill_clusters/{skill_cluster_id}.

​
June 2023

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

​
April 2023

  • A skill_event with project_content now assumes a textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). The previous functionality of general project descriptions is removed.

​
February 2023

  • The desired_functions and non_desired_functions fields of the Employee have been changed from lists of titles to list of Function objects. A Function object consists of a Function title and a relative importance.

​
January 2023

  • All instances of competency, competencies or capitalized alternatives have been renamed to skill_cluster and skill_clusters, and their capitalized versions.
  • All instances of category, categories or capitalized alternatives have been renamed to domain and domains, and their capitalized versions.

​
October 2022

  • The competency and score fields in PUT, PATCH /{entity}/{external_id}/skill_profile in competencies format are now renamed to competency_name and proficiency_level respectively.
  • The score fields in PUT, PATCH /{entity}/{external_id}/skill_profile in skills format is replaced by has_skill which is a boolean instead of number.
  • The competency and score fields in GET /{entity}/{external_id}/skill_profile in competencies format are now renamed to competency_name and proficiency_level respectively.

​
July 2022

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

​
June 2022

  • Deprecated GET /employees/{external_id}/recommended_courses and added POST instead.
  • Removed POST /competencies/{external_id}/similar and POST /competencies/{external_id}/profile/related endpoints.

​
May 2022

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

​
November 2021

  • Removed Document Entity and all its functionalities.

​
July 2021

  • Similar Entity endpoints are now POST instead of GET.
  • The response format of Similar Entity endpoints has changed from a list to an object containing two fields: the list of results and the total number of results available.

​
June 2021

  • Search endpoints now require weights in the body, in the same manner as matching endpoints.
  • Search endpoints now support a score_min_threshold query parameter, and defaults to 0.5 for this value instead of the previously internal 0.0.

​
April 2021

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

​
March 2021

  • The response format of matching results (GET/POST /employees/{external_id}/matching_vacancies , GET/POST /vacancies/{external_id}/matching_employees , GET /employees/{external_id}/matching_companies and GET /companies/{external_id}/matching_employees) has changed from a list to an object containing two fields: the list of results and the total number of results available.
  • The response format of search results (POST /employees/search , POST /vacancies/search and POST /companies/search) has changed from a list to an object containing two fields: the list of search results and the total number of results available from the free text search.
  • The response format of list results (GET /employees/, GET /vacancies/ , GET /companies/, GET /courses/, GET /competencies/, GET /documents/ and GET /occupations/) has changed from a list to an object containing two fields: the list of results and the total number of results available.

​
February 2021

  • Employee creation (POST /employees) and updates (PATCH /employees/{external_id}) no longer support uploading individual resumes (as employee_resume) in favour of accepting a list of multiple resumes (as employee_documents) with the same format.
  • The list entity endpoints (GET /employees, GET /vacancies, GET /courses , GET /occupations, GET /competencies and GET /documents) no longer support the response_format query parameter. The response now corresponds to the former objects response format for all endpoints.

​
January 2021

  • The version endpoint now returns a body with a single field version, indicating the current version of your tenant. The version is returned as a date (ISO-8601, ex. 2021-01-19) and no longer as a number.