{
"openapi": "3.1.1",
"info": {
"version": "latest",
"contact": {
"name": "API Support",
"url": "https://www.techwolf.ai/",
"email": "support@techwolf.ai"
},
"title": "Skill Engine API",
"description": "The Skill Engine API is your single stop for continuous Skill tracking, matching, learning management and strategic insights. This API specification describes how to augment your existing data sources with Skills to build your workforce of tomorrow.\n"
},
"servers": [
{
"description": "Skill Engine API",
"url": "https://{tenant_name}.{region}.techwolf.ai",
"variables": {
"tenant_name": {
"default": "tenant_name"
},
"region": {
"default": "eu3",
"enum": [
"eu3",
"us3"
]
}
}
}
],
"security": [
{
"application": [
"read",
"write"
]
}
],
"tags": [
{
"name": "TaxonomyDomains",
"x-displayName": "Domains",
"description": "Domains in the Skill Engine API allow enterprise customers to adapt Domains in\ntheir Taxonomy.\n\n[Custom Properties]() are supported for this entity.\n"
},
{
"name": "TaxonomySubdomains",
"x-displayName": "Subdomains",
"description": "Subdomains in the Skill Engine API allow enterprise customers to adapt\nSubdomains in their Taxonomy.\n\n\nBy default, **Subdomains are disabled**. The 3-level Taxonomy only consists of\nDomains, Skill Clusters and Skills. Enabling Subdomains allows a 4-level\nTaxonomy consisting of Domains, Subdomains, Skill Clusters and Skills. To enable\nSubdomains on your tenants, contact support@techwolf.ai!\n\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "TaxonomySkillClusters",
"x-displayName": "Skill Clusters",
"description": "Skill Clusters in the Skill Engine API allow enterprise customers to adapt Skill\nClusters in their Taxonomy.\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "TaxonomySkills",
"x-displayName": "Skills",
"description": "Skills in the Skill Engine API allow enterprise customers to get Skills in their\nTaxonomy.\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "Taxonomy",
"x-displayName": "Taxonomy operations",
"description": "Taxonomy operations can be used to view or edit large parts of the Taxonomy.\n"
},
{
"name": "TaxonomyExport",
"x-displayName": "Taxonomy",
"description": ""
},
{
"name": "EmployeeCRUD",
"x-displayName": "CRUD",
"description": "Employees in the Skill Engine API represent either a person within your\norganisation or a candidate within the Job market.\n\nMore info about entities can be found on the\n[How it Works page](/technology/entities/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "EmployeeProfile",
"x-displayName": "Skill Profile"
},
{
"name": "EmployeeMetrics",
"x-displayName": "Metrics",
"description": "A metric is a single number representing some amount of information about an\nentity or a collection of entities of the same type.\n\nMore info about Metrics can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "EmployeeSearch",
"x-displayName": "Search"
},
{
"name": "EmployeeInteractions",
"x-displayName": "Interactions",
"description": "Interactions can be used to handle Employees interacting with Vacancies or titles in ways that express their desired functions."
},
{
"name": "EmployeeSuggestions",
"x-displayName": "Suggestions"
},
{
"name": "SkillEvents",
"x-displayName": "Skill Events",
"description": "A Skill Event influences the Skillset of an Employee. When an Employee finishes\na Course, receives feedback, starts a new function, or when another event occurs\nthat gives additional info to an Employee's Skill Profile, a Skill Event can be\ngenerated.\n\nSkill Events allow you to monitor the evolution of an Employee's Skill Profile\nand allow you to pinpoint exactly what Skills your Employees had at a certain\ntime. Skill Events also enable an easy method of adding new information to a\nprofile.\n\nCheck the how it works article to find out everything you need to know about\nSkill Events. [How it Works](/technology/skill_events/)\n"
},
{
"name": "VacancyCRUD",
"x-displayName": "CRUD",
"description": "Vacancies in the Skill Engine API correspond to Job postings or open positions.\n\nMore info about entities can be found on the\n[How it Works page](/technology/entities/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "VacancyProfile",
"x-displayName": "Skill Profile"
},
{
"name": "VacancyMetrics",
"x-displayName": "Metrics",
"description": "A metric is a single number representing some amount of information about an\nentity or a collection of entities of the same type.\n\nMore info about Metrics can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "VacancySearch",
"x-displayName": "Search"
},
{
"name": "CourseCRUD",
"x-displayName": "CRUD",
"description": "Courses in the Skill Engine API correspond to internal/external training or\neducation.\n\nMore info about entities can be found on the\n[How it Works page](/technology/entities/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "OrganisationalUnits",
"x-displayName": "Organisational Units",
"description": "Organisational Units in the Skill Engine API represent groupings of Employees\narranged in a hierarchical structure.\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "OrganisationalUnitMetrics",
"x-displayName": "Metrics",
"description": "A metric is a single number representing some amount of information about an\nentity or a collection of entities of the same type.\n\nMore info about Metrics can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "CourseProfile",
"x-displayName": "Skill Profile"
},
{
"name": "CourseMetrics",
"x-displayName": "Metrics",
"description": "A metric is a single number representing some amount of information about an\nentity or a collection of entities of the same type.\n\nMore info about Metrics can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "SkillClusterCRUD",
"x-displayName": "CRUD",
"description": "Skill Clusters in the Skill Engine API allow enterprise customers to use their\nown Skill Cluster framework.\n\nMore info about Skill Clusters can be found at the\n[How it Works page](/technology/skill-clusters/) and the\n[Skill Cluster Tutorial](/tutorials/skill-clusters/overview/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "SkillClusterProfile",
"x-displayName": "Skill Profile"
},
{
"name": "SkillClusterMetrics",
"x-displayName": "Metrics",
"description": "A metric is a single number representing some amount of information about an\nentity or a collection of entities of the same type.\n\nMore info about Metrics can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "CompanyCRUD",
"x-displayName": "CRUD",
"description": "An External Company in the Skill Engine API represents **any external company**.\nThey can be used to match against, using the Vacancies that are linked to them.\n\nEmployment and staffing customers can match candidates with external companies,\neven when they do not have an explicitly advertised position.\n\nEnterprise customers can use External Companies too to profile and compare\nthemselves to other External Companies.\n\nMore info about External Companies can be found on the\n[How it Works page](/technology/companies/) and the\n[External Company tutorial](/tutorials/companies/overview/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "CompanySearch",
"x-displayName": "Search"
},
{
"name": "Skill Search"
},
{
"name": "Skill Lookup"
},
{
"name": "Skill Gaps"
},
{
"name": "Vacancy Matching",
"description": "The Skill Engine API allows you to fetch matching entities and External\nCompanies with a wide range of different configurations. The system leverages a\nset of _filters_ (constraints that are applied before matching, making a binary\ndecision for each entity whether they should be considered) and _weights_\n(reweighting of the match scores) to let you tailor results to your wishes. You\ncan find more information about how filters work [here]().\n\nMatch results can be queried in a paginated manner, allowing you to iteratively\nfetch all relevant results for a match query using the common `limit` and\n`offset` setup. Under the hood, the Skill Engine API uses a two-step process to\nenable paginated results: first, _approximate matching_ is applied to create an\ninitial ordering of results, followed by _refinement_ of these results into the\nfinal scores. The ordering of the results, and therefore also the contents of\nany given page, are determined entirely by the approximate matching. This allows\nus to provide high volumes of matches without the delay caused by refining all\npossible matches for every single query. As approximate and refined scores can\nin some cases deviate from each other slightly, it is expected that in some\ncases the last result of a given page can have a lower score than the first\nresult of the next -- if this is problematic for your use case (i.e. you want\nthe exact top 10), then we recommend using a higher limit and trimming down\nresults, as this suffices to capture any reordering caused by refinement.\n\nBy default, a geographic distance filter is applied by default such that only\nentities within a 50 km range are considered. This range can be adapted by\nconfiguring the `max_geo_distance` filter. To retain fast response times, any\nmatching request that has more than 10.000 entities fulfilling all filter\ncriteria will be cut off at the 10.000 entities that are geographically closest\nto the search point.\n"
},
{
"name": "Job Matching"
},
{
"name": "Job Family Matching"
},
{
"name": "Task Matching"
},
{
"name": "Match Feedback"
},
{
"name": "External Company Matching"
},
{
"name": "Course Recommendations"
},
{
"name": "Export Matching"
},
{
"name": "ExportEmployeesSkillClusters",
"x-displayName": "Employees",
"description": "Export data from the API through pagination. Request the first page of an export\nby not specifying the `starting_after` field. Next pages can be requested by\nsetting the `starting_after` field to the last `external_id` from the previous\npage. When there is no more data after the requested page, `has_next` will be\n`false`.\n"
},
{
"name": "ExportEmployeeAssignedPosition",
"x-displayName": "Employees Assigned Position"
},
{
"name": "CoursesExportSkillProfiles",
"x-displayName": "Courses",
"description": ""
},
{
"name": "VacanciesExportSkillProfiles",
"x-displayName": "Vacancies",
"description": ""
},
{
"name": "JobArchitectureExport",
"x-displayName": "Job Architecture",
"description": ""
},
{
"name": "OrganisationalStructureExport",
"x-displayName": "Organisational Structure"
},
{
"name": "JobFamilyCRUD",
"x-displayName": "CRUD",
"description": "Job Families in the Skill Engine API represent a group of Jobs that are related\nwithin your organisation.\n\nMore info about Job Families can be found at the\n[Job Architecture Tutorial](/tutorials/job_architecture/overview/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "JobCRUD",
"x-displayName": "CRUD",
"description": "Jobs in the Skill Engine API represent a specific role within your organisation.\nThey are linked to Job Families.\n\nMore info about Jobs can be found at the\n[Job Architecture Tutorial](/tutorials/job_architecture/overview/).\n\n[Custom Properties]() are supported for this\nentity.\n"
},
{
"name": "Job Family Profile Data",
"description": "Job Family Profile Data influences the Skillset of a Job Family. Profile Data\nenables an easy method of adding new information to a Job Family.\n"
},
{
"name": "Job Profile Data",
"description": "Job Profile Data influences the skillset of a Job. Profile Data enables an easy\nmethod of adding new information to a Job.\n"
},
{
"name": "JobIssues",
"x-displayName": "Issues",
"description": "A Job Issue represents a data issue identified for a particular job,\ne.g. a missing or short Job description."
},
{
"name": "JobChanges",
"x-displayName": "Changes",
"description": "Job changes represent data changes that were suggested and/or applied to Jobs in the Job Architecture."
},
{
"name": "JobSuggestions",
"x-displayName": "Suggestions",
"description": "Job architecture suggestions represent AI-generated recommendations for changes to job skill profiles, such as adding or removing skills, or updating proficiency levels and criticality flags."
},
{
"name": "JobFamilyProfile",
"x-displayName": "Skill Profile"
},
{
"name": "JobProfile",
"x-displayName": "Skill Profile"
},
{
"name": "JobMetrics",
"x-displayName": "Metrics",
"description": "A metric is a single number representing some amount of information about an\nentity or a collection of entities of the same type.\n\nMore info about Metrics can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "PeerGroups",
"x-displayName": "Peer Groups",
"description": "A peer group consists of a list of companies used to create external market Skill Profiles for Jobs.\n\nMore information about external market Skill Profiles can be found in the documentation of the relevant\n[endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-skill-profiles)."
},
{
"name": "General Reports",
"description": "Reports aggregate and group Metrics into a broader overview.\n\nMore info about Reports can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "Employee Reports",
"description": "Reports aggregate and group Metrics into a broader overview.\n\nMore info about Reports can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "Vacancy Reports",
"description": "Reports aggregate and group Metrics into a broader overview.\n\nMore info about Reports can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "Job Reports",
"description": "Reports aggregate and group Metrics into a broader overview.\n\nMore info about Reports can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "Data Maturity Scan",
"description": "Reports aggregate and group Metrics into a broader overview.\n\nMore info about Reports can be found on the\n[How it Works page](/technology/metrics-reports/) .\n"
},
{
"name": "Versioning Overview",
"description": "import { ExperimentalBadge } from '/snippets/ExperimentalBadge.mdx'\n\nThe SkillEngine API is a date-based versioned API system, such that each\nintegrator interacts with a certain version of our product. To know your own\nversion, you can call the `/version` endpoint (description can be\nfound [here](/reference/latest/Version/Version/get-version)).\n\nYour version is set by us at the time your tenant is created. This version\ncontrols how your API will behave (in terms of supported parameters, response\nformats, etc.).\n\nAs it is possible that we introduce breaking changes in future updates that may\nbreak your code, we will not update your version **unless you specifically\nrequest this**. Breaking changes will always be released under a new date and\ncan be tracked in the documentation [here]().\n\nDeprecations will be announced in the documentation and will be supported for a \ncertain period of time. After this period, the deprecation will\nbecome a breaking change. Deprecations can be tracked in the documentation [here]().\n\nNon-breaking changes, on the other hand, will be supported by your API, **regardless of \nyour version**. An overview can also be found [here]().\n\nIn case you want to test a specific version of the API, e.g. when switching\nversions, you can add the header `X-API-Version` to your requests. The value of\nthis header is the version of the API you want to use, for example `2021-03-19`.\n\nWhen you see an endpoint marked with it is considered experimental or in beta. These endpoints can undergo breaking changes without any\nnotice or promises on backwards compatibility. You should not use them in\nproduction.\n"
},
{
"name": "Breaking Changes",
"description": "The list below provides an overview of breaking changes to the SkillEngine API.\nBreaking changes are modifications that may cause your existing integrations to\nstop working. These changes are only applied to your tenant when you request a\nversion update.\n\n### October 2026\n\n- Removed the `GET /employees/{employee_external_id}/task_profile` endpoint from the public API.\n- Removed the `PATCH /employees/{employee_external_id}/task_profile` endpoint.\n\n### September 2026\n\n- Removed the `POST /reports/skill_inventory` endpoint.\n- `ticket`, `merge_request` and business record Skill Events (`it_incident`, `support_ticket`, … — see `GET /skill_event_types`) are no longer accepted on the `POST /employees/{employee_external_id}/skill_events` endpoint on tenants with a model configuration older than `MC_2025_Q1_V1`.\n Such requests are rejected with a `422 Unprocessable Entity` response stating that the model configuration of the tenant is outdated.\n To keep using these Skill Event types, contact TechWolf to upgrade your tenant to the latest model configuration.\n\n### August 2026\n\n- Removed the `include=relevant_experience` query/body parameter and the `relevant_experience` response field from the `POST /employees/{external_id}/matching_vacancies`, `POST /vacancies/{external_id}/matching_employees`, and `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` endpoints.\n\n### July 2026\n\n- Removed the deprecated `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` endpoint; use the `POST` variant on the same path instead.\n- Removed the `POST /reports/job_architecture_benchmark` endpoint.\n\n### March 2026\n\n- The `proficiency_level`, `proficiency_float`, and `critical` response fields have been replaced\n with `governed_proficiency_level`, `inferred_proficiency_level`, `governed_proficiency_float`,\n `inferred_proficiency_float`, `governed_critical`, and `inferred_critical` on the following endpoints:\n - `GET /job_architecture/jobs/{job_external_id}/skill_profile`\n - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n - `POST /job_architecture/export/jobs/skill_profiles`\n - `POST /job_architecture/export/job_families/skill_profiles`\n- The `validation_state` field is now always returned on each Skill in the Skill Profile response\n for the above endpoints. The `include=skill_validation_state` query/body parameter has been removed.\n- Suggested Skills (with `validation_state: \"suggested\"`) are now included alongside governed Skills\n in the Skill Profile response for the above endpoints.\n\n### December 2025\n\n- Changed the `GET /reports/data_maturity_scan/employee_quality_matrix` endpoint\n to `POST` and added optional `filters` request body to filter by Employee external IDs.\n- Changed the `GET /reports/data_maturity_scan/job_quality_matrix` endpoint\n to `POST` and added optional `filters` request body to filter by Job external IDs.\n\n### September 2025\n\n- Removed `translation_found` field from the `GET /employees/suggestions/skills` endpoint.\n- Removed skill names from unsupported languages from the output of the `GET /employees/suggestions/skills` endpoint.\n\n### August 2025\n\n- Deprecated the `domains` response format from the\n `GET /courses/{course_external_id}/skill_profile` and the\n `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints.\n\n### March 2025\n\n- Removed the `skill_vocab` and `external_id` fields from the\n `GET /taxonomy/skills` endpoint\n- Removed the `skill_vocab` and `external_id` fields from the\n `GET /taxonomy/skills/{skill_id}` endpoint\n- Removed the `skill_vocab` and `external_id` fields from the\n `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint\n- Removed the `skill_vocab` and `external_id` fields from the\n `GET /taxonomy/export` endpoint\n\n### February 2025\n\n- Removed the `POST /integrations/file_load_task` endpoint.\n- Removed the `GET /integrations/file_load_task/{task_id}` endpoint.\n- Removed the `/job_architecture/jobs/{job_external_id}/market_skill_profile`\n endpoint.\n\n### January 2025\n\n- Removed the `response_format=trending` query paramter option for all\n `GET //skill_profile` endpoints.\n\n### December 2024\n\n- Removed the `GET /employees/{external_id}/metrics/position_alignment`\n endpoint.\n\n### November 2024\n\n- Removed the `POST /vacancies/{external_id}/metrics/fillability` endpoint.\n- Renamed the value of query parameter `include=description` to\n `include=skill_description` in the `GET /taxonomy/skills` endpoint.\n\n### October 2024\n\n- Changed the format for duplicate data examples from the\n `GET /reports/data_maturity_scan/data_improvement_actions` endpoint.\n- Removed the `POST /reports/skills_alignment` endpoint.\n- Removed the `POST /reports/workforce_alignment` endpoint.\n- Removed the `POST /reports/strategy_map` endpoint.\n- Removed the `POST /reports/skill_frequencies` endpoint.\n- Removed the `POST /reports/organization_names` endpoint.\n- Removed the `POST /reports/employee_skill_distribution` endpoint.\n- Removed the `POST /reports/vacancy_skill_distribution` endpoint.\n\n### September 2024\n\n- Renamed the field `name` to `skill_name` in the\n `GET /employees/{external_id}/skill_profile` endpoint when the\n `response_format` query parameter is set to `skill_clusters` or `domains`.\n\n### August 2024\n\n- Removed the `GET /reports/succession_risk` endpoint.\n- Removed the `GET /reports/employees/skills` endpoint.\n- Removed the `GET /reports/employees/position_alignment` endpoint.\n- Removed the `POST /reports/replacement_risk` endpoint.\n- Removed `count` response body field from the `POST /employees/search`\n endpoint.\n- Removed `count` response body field from the `POST /vacancies/search`\n endpoint.\n- Removed `count` response body field from the `POST /companies/search`\n endpoint.\n- Removed `count` response body field from the\n `POST /employees/{external_id}/recommended_courses` endpoint.\n- Removed `count` response body field from the\n `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses`\n endpoint.\n- Removed `count` response body field from the\n `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses`\n endpoint.\n- Removed `count` response body field from the\n `POST /employees/{external_id}/matching_vacancies` endpoint.\n- Removed `count` response body field from the\n `POST /employees/{external_id}/matching_companies` endpoint.\n- Removed `count` response body field from the\n `POST /employees/{external_id}/matching_jobs` endpoint.\n- Removed `count` response body field from the\n `POST /employees/{external_id}/matching_job_families` endpoint.\n- Removed `count` response body field from the\n `POST /vacancies/{external_id}/matching_employees` endpoint.\n- Removed `count` response body field from the\n `POST /companies/{external_id}/matching_employees` endpoint.\n- Removed `count` response body field from the\n `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint.\n- Removed `count` response body field from the\n `POST /job_architecture/job_families/{external_id}/matching_employees`\n endpoint.\n\n### July 2024\n\n- Removed the `GET /reports/employees/employability` endpoint.\n- Removed the `GET /employees/{external_id}/metrics/employability` endpoint.\n- Removed the `GET /vacancies/{external_id}/metrics/fillability` endpoint.\n\n### June 2024\n\n- Removed support for the `language` filter in the\n `POST /companies/{external_id}/matching_employees` endpoint.\n- Removed `feedback_format=skill_clusters` support for the\n `PATCH /vacancies/{external_id}/skill_profile` endpoint.\n- Removed `feedback_format=skill_clusters` support for the\n `PATCH /courses/{external_id}/skill_profile` endpoint.\n- Removed `response_format=skill_clusters` support for the\n `GET /vacancies/{external_id}/skill_profile` endpoint.\n- Removed `response_format=skill_clusters` support for the\n `GET /courses/{external_id}/skill_profile` endpoint.\n- Removed the `POST /reports/clustered_trending_skills` endpoint.\n- Removed the `POST /reports/emerging_skills` endpoint.\n- Removed the `POST /employees/{external_id}/similar` endpoint.\n- Removed the `POST /vacancies/{external_id}/similar` endpoint.\n- Removed the `POST /courses/{external_id}/similar` endpoint.\n- Removed Occupation entity and its functionalities, along with the Reskilling\n & Deployment report\n\n### May 2024\n\n- Removed the `include=skill_match_scores` query parameter of\n `POST /employees/{external_id}/matching_job_families`\n- Replaced the `skill_type` field with `skill_types` for the `skills` response\n body field of the `GET /job_architecture/job/{job_id}/skill_profile` and\n `GET /job_architecture/job_families/{job_family_id}/skill_profile`\n endpoints.\n- Replaced the `skill_type` field with `skill_types` for the `skills` field of\n the `records` response body field of the\n `POST /job_architecture/export/jobs/skill_profiles`, and\n `POST /job_architecture/export/job_families/skill_profiles` endpoints.\n- Replaced the `skill_type` field with `skill_types` for the `skills` field of\n `skill_clusters` field of the `records` response body field of the\n `POST /job_architecture/export/jobs/skill_clusters`.\n\n### February 2024\n\n- Removed the `include=skill_clusters` query parameter of\n `POST /vacancies/{external_id}/matching_employees` and\n `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`.\n- Moved the `relevant_experience` response body field of the\n `response_format=explained` query parameter to the newly added\n `include=relevant_experience` query parameter of the\n `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`\n endpoint.\n- Renamed the `skill` response body field to `skill_name` of the\n `GET employees/{external_id}/vacancies/{external_id}/gap` endpoint.\n\n### January 2024\n\n- The `GET /job_architecture/job/{job_id}/skill_profile` endpoint has a new\n Skill type called `Family-Specific`.\n- The `GET /job_architecture/job_families/{job_family_id}/skill_profile`\n endpoint has a new Skill type called `Family-Specific`.\n\n### December 2023\n\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /employees/{external_id}/skill_profile` now requires either\n a `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` now\n requires either a `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint\n `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile`\n now requires either a `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either\n a `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a\n `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /occupations/{external_id}/skill_profile` now requires\n either a `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either\n a `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a\n `skill` or a `skill_id`, not both.\n- The `skills` request body field of the `SkillProfileUpdateMessage` of the\n endpoint `PATCH /occupations/{external_id}/skill_profile` now requires\n either a `skill` or a `skill_id`, not both.\n\n### November 2023\n\n- Removed the deprecated `GET /employees/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `POST /employees/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `GET /vacancies/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `POST /vacancies/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `GET /courses/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `POST /courses/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `GET /occupations/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `POST /occupations/{external_id}/profile/related`\n endpoint.\n- Removed the deprecated `GET /skills/{skill_name}/related` endpoint.\n\n### October 2023\n\n- Remove `POST /skill_clusters` in favor of `POST /taxonomy/skill_clusters`.\n- Remove `DELETE /skill_clusters/{skill_cluster_id}` in favor of\n `DELETE /taxonomy/skill_clusters/{skill_cluster_id}`.\n- Remove `PATCH /skill_clusters/{skill_cluster_id}` in favor of\n `PATCH /taxonomy/skill_clusters/{skill_cluster_id}`.\n\n### June 2023\n\n- Removed the deprecated `PUT {entity}/{external_id}/skill_profile` endpoint.\n\n### April 2023\n\n- A `skill_event` with `project_content` now assumes a textual description of\n a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.).\n The previous functionality of general project descriptions is removed.\n\n### February 2023\n\n- The `desired_functions` and `non_desired_functions` fields of the Employee\n have been changed from lists of titles to list of Function objects. A\n Function object consists of a Function title and a relative importance.\n\n### January 2023\n\n- All instances of `competency`, `competencies` or capitalized alternatives\n have been renamed to `skill_cluster` and `skill_clusters`, and their\n capitalized versions.\n- All instances of `category`, `categories` or capitalized alternatives have\n been renamed to `domain` and `domains`, and their capitalized versions.\n\n### October 2022\n\n- The `competency` and `score` fields in\n `PUT, PATCH /{entity}/{external_id}/skill_profile` in `competencies` format\n are now renamed to `competency_name` and `proficiency_level` respectively.\n\n- The `score` fields in `PUT, PATCH /{entity}/{external_id}/skill_profile` in\n `skills` format is replaced by `has_skill` which is a boolean instead of\n number.\n- The `competency` and `score` fields in\n `GET /{entity}/{external_id}/skill_profile` in `competencies` format are now\n renamed to `competency_name` and `proficiency_level` respectively.\n\n### July 2022\n\n- The `score` field in `GET /{entity}/{external_id}/skill_profile` in `list`\n format is now optional.\n\n### June 2022\n\n- Deprecated `GET /employees/{external_id}/recommended_courses` and added POST\n instead.\n- Removed `POST /competencies/{external_id}/similar` and\n `POST /competencies/{external_id}/profile/related` endpoints.\n\n### May 2022\n\n- Removed `PUT /competencies/{external_id}/skill_profile` feedback endpoint.\n\n### November 2021\n\n- Removed Document Entity and all its functionalities.\n\n### July 2021\n\n- Similar Entity endpoints are now `POST` instead of `GET`.\n- The response format of Similar Entity endpoints has changed from a list to\n an object containing two fields: the list of results and the total number of\n results available.\n\n### June 2021\n\n- Search endpoints now require weights in the body, in the same manner as\n matching endpoints.\n- Search endpoints now support a `score_min_threshold` query parameter, and\n defaults to 0.5 for this value instead of the previously internal 0.0.\n\n### April 2021\n\n- The language query parameter has become required for the creation and update\n of an entity.\n\n### March 2021\n\n- The response format of matching results\n (`GET/POST /employees/{external_id}/matching_vacancies` ,\n `GET/POST /vacancies/{external_id}/matching_employees` ,\n `GET /employees/{external_id}/matching_companies` and\n `GET /companies/{external_id}/matching_employees`) has changed from a list\n to an object containing two fields: the list of results and the total number\n of results available.\n- The response format of search results (`POST /employees/search` ,\n `POST /vacancies/search` and `POST /companies/search`) has changed from a\n list to an object containing two fields: the list of search results and the\n total number of results available from the free text search.\n- The response format of list results (`GET /employees/`, `GET /vacancies/` ,\n `GET /companies/`, `GET /courses/`, `GET /competencies/`, `GET /documents/`\n and `GET /occupations/`) has changed from a list to an object containing two\n fields: the list of results and the total number of results available.\n\n### February 2021\n\n- Employee creation (`POST /employees`) and updates\n (`PATCH /employees/{external_id}`) no longer support uploading individual\n resumes (as `employee_resume`) in favour of accepting a list of multiple\n resumes (as `employee_documents`) with the same format.\n- The list entity endpoints (`GET /employees`, `GET /vacancies`,\n `GET /courses` , `GET /occupations`, `GET /competencies` and\n `GET /documents`) no longer support the `response_format` query parameter.\n The response now corresponds to the former `objects` response format for all\n endpoints.\n\n### January 2021\n\n- The version endpoint now returns a body with a single field `version`,\n indicating the current version of your tenant. The version is returned as a\n date (ISO-8601, ex. 2021-01-19) and no longer as a number.\n"
},
{
"name": "Deprecations",
"description": "This section lists all currently deprecated features in the SkillEngine API. Deprecated features will be supported for a certain period of time before being removed. We recommend updating your integration to use the newer alternatives as soon as possible.\n\n### March 2026\n\n- Deprecated the Suggested Skill Profile endpoints. Use the corresponding Skill Profile endpoints instead.\n\n The following endpoints are affected:\n\n - `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile`\n - `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile`\n - `POST /job_architecture/export/jobs/suggested_skill_profiles`\n - `POST /job_architecture/export/job_families/suggested_skill_profiles`\n\n### January 2026\n\n- Deprecated the `GET /taxonomy/changes` endpoint. This endpoint will be replaced\n by the newly introduced `POST /taxonomy/changes` endpoint.\n\n### December 2023\n\n- Introduced a `skill_id` field alongside Skill names in our API endpoints to\n avoid ambiguities and conflicts. Using Skill names in a request body to\n denote or update a Skill is deprecated, please use `skill_id` instead.\n Existing functionality is backward-compatible.\n\n The following endpoints are affected:\n\n - `PATCH /employees/{external_id}/skill_profile`\n - `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile`\n - `PATCH /job_architecture/jobs/{job_external_id}/skill_profile`\n - `PATCH /vacancies/{external_id}/skill_profile`\n - `PATCH /courses/{external_id}/skill_profile`\n - `PATCH /occupations/{external_id}/skill_profile`\n"
},
{
"name": "Compatible Changes",
"description": "The list below gives a sorted overview of non-breaking changes to the\nSkillEngine API. These changes are immediately available to you and will be\nsupported by your API, regardless of your version.\n\n### October 2026\n\n- Added the `GET /skill_event_types` endpoint that lists the Skill Event types\n your tenant can send and the content fields each one takes.\n- Added 25 Skill Event types for business records (`it_incident`,\n `support_ticket`, `technical_spec`, …) to\n `POST /employees/{employee_external_id}/skill_events`, enabled per tenant on\n request.\n\n### August 2026\n\n- Added `custom_properties` as an `include` value on\n `POST /export/employees/skill_profiles` and `POST /export/skills` that\n returns, per Skill, the custom properties set on it as a mapping of property\n name to value.\n- Raised the maximum length of `ticket_description` on `ticket` Skill Events\n from 10 000 to 50 000 characters.\n- Raised the maximum length of `description` on `merge_request` Skill Events\n from 5 000 to 250 000 characters, and of `commits[].message` from 500 to\n 100 000 characters.\n- Added the `skill_description` field to the `vocab_update_add_skill` operation\n of `GET /taxonomy/changes` and `POST /taxonomy/changes`.\n- Added the `vocab_update_description` operation type to `GET /taxonomy/changes`\n and `POST /taxonomy/changes`, emitted when a Skill's description changes\n between vocabulary versions.\n\n### July 2026\n\n- Added `output_language` as an `include` value on `POST /export/skills` that\n returns, per Skill, the language its information was resolved from, so\n fallback resolutions can be told apart from genuine translations.\n- Added `linked_jobs` as an `include` value on `POST /export/tasks` that\n expands each Task with the Jobs it is assigned to.\n- Added the `external_vendor` query parameter to `POST /export/tasks` for the\n `linked_jobs` include.\n- Added the `canonical_task_id_is_in_list` filter to `POST /export/tasks`.\n\n### June 2026\n\n- Added a top-level `unrecognized_skill_ids` array field to the\n `400 Bad Request` response of `PATCH /employees/{external_id}/skill_profile`\n when `feedback_format` is `external_vendor_skills` and one or more submitted\n Skill IDs are not recognised. All unrecognized IDs are returned in a single\n response so they can be removed and the request retried in one round trip.\n The field is purely additive; the `skills` feedback format response is\n unchanged.\n- Added the `domain_id`, `subdomain_id`, `cluster_id`, and `canonical_task_id`\n fields to the task `hierarchy` block, giving each task-hierarchy level a\n stable id alongside its name. The ids are returned (nullable) wherever the\n hierarchy appears: `GET /tasks/{task_id}`, `GET /tasks/search`, the Employee\n and Job Task Profile endpoints (both `list` and `hierarchy` response\n formats), and the task exports (`POST /export/tasks`,\n `POST /export/employees/task_profiles`, and\n `POST /job_architecture/export/jobs/task_profiles`).\n- Added the `response_format` query parameter to the Job Family task-based\n matching endpoints\n (`POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks`\n and\n `GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match`).\n- Added the `match_type` field to each entry in the `similar_tasks` array of the\n `POST /tasks/validate` response, indicating how the similar Task was found.\n- Added `skill_source` as an `include` value on\n `GET /job_architecture/jobs/{job_external_id}/skill_profile`,\n `GET /employees/{external_id}/skill_profile`,\n `POST /job_architecture/export/jobs/skill_profiles`, and\n `POST /export/employees/skill_profiles`. When requested, each Skill in the\n response gains a `skill_source` field indicating whether the Skill is a\n custom Skill or originates from the TechWolf vocabulary.\n- Added the `GET /tasks/{task_id}` endpoint that fetches a single Task by id.\n- Added the `DELETE /tasks/{task_id}` endpoint that deletes a custom Task.\n- Added the `POST /tasks` endpoint that creates a custom Task.\n- Added the optional `source` body parameter to `POST /tasks` that records\n free-text attribution for a custom Task.\n- Added the `POST /tasks/validate` endpoint that screens candidate Task names\n for quality and uniqueness.\n- Added `task_source` and `enrichment_status` as `include[]` values on\n `GET /tasks/search` and `POST /export/tasks`, plus `ai_impact` and `hierarchy`\n on `GET /tasks/search`.\n- Added the `response_format` query parameter to the task-based matching\n endpoints (`POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks`,\n `GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match`,\n and `POST /tasks/matching`).\n\n### May 2026\n\n- Added a new `POST /tasks/matching` endpoint that returns the symmetric\n task-based match score between two caller-supplied task sets.\n- Added a new `POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks`\n endpoint that returns the Jobs whose task profiles best match the given Job,\n ranked by task-match score.\n- Added a new `GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match`\n endpoint that returns the symmetric task-based match score between two Jobs.\n- Added a new `POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks`\n endpoint that returns the Job Families whose task profiles best match the\n given Job Family, ranked by task-match score.\n- Added a new `GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match`\n endpoint that returns the symmetric task-based match score between two Job\n Families.\n- Added the `normalized` query parameter to `POST /skills/lookup`. When set to\n `true`, the endpoint matches Skill names case-insensitively and\n diacritic-insensitively (Latin diacritics only), so inputs like `Café`,\n `café`, and `cafe` all resolve to the same Skill. Defaults to `false`\n (exact match).\n- Added the `query` field to every entry in the response of\n `POST /skills/lookup`. It echoes the Skill name as provided in the request\n body. When `normalized=false`, `query` always equals `skill_name`. When\n `normalized=true` and the Skill is matched, `query` may differ from\n `skill_name` in casing or Latin diacritics. On a miss, `skill_name` falls\n back to the input value, so the field is always non-null.\n\n### April 2026\n\n- Added a new `GET /taxonomy/skills/languages` endpoint that returns the list of language codes\n available for Skills in the tenant's vocabulary. An optional `external_vendor` query parameter\n can be provided to retrieve languages for a specific vendor vocabulary.\n\n- Extended the `vocab_language` query parameter to support 12 additional language codes\n **when scoped to the `workday` vendor** (via `external_vendor=workday`):\n `es` (Spanish), `fr_ca` (French Canadian), `it` (Italian), `ja` (Japanese), `ko` (Korean),\n `pt_br` (Brazilian Portuguese), `zh_cn` (Simplified Chinese), `zh_tw` (Traditional Chinese),\n `sv` (Swedish), `fi` (Finnish), `da` (Danish), and `no` (Norwegian).\n The default TechWolf vocabulary continues to support only `en`, `en_uk`, `en_us`, `de`,\n `fr`, and `nl`. Use the new `GET /taxonomy/skills/languages` endpoint to discover the\n exact set of languages available for a given vendor in your tenant.\n Additionally, IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`, `nb-NO`) are now accepted\n and mapped to their internal equivalents. This applies to all endpoints that accept the\n `vocab_language` parameter.\n\n### March 2026\n\n- Added the `low_data_availability` filter to matching endpoints. When\n `exclude_low_data_availability` is set to `true`, entities with insufficient\n data for qualitative Skill inference are excluded from matching results. This\n filter is available on the following endpoints:\n - `POST /employees/{external_id}/matching_vacancies`\n - `POST /employees/{external_id}/matching_jobs`\n - `POST /vacancies/{external_id}/matching_employees`\n - `POST /job_architecture/jobs/{job_external_id}/matching_employees`\n - `POST /job_architecture/jobs/{job_external_id}/matching_source_jobs`\n - `POST /job_architecture/jobs/{job_external_id}/matching_target_jobs`\n - `POST /job_architecture/job_families/{job_family_external_id}/matching_employees`\n - `POST /companies/{external_id}/matching_employees`\n - `POST /employees/{external_id}/metrics/employability`\n - `POST /export/employees/matching_vacancies`\n - `POST /export/employees/matching_jobs`\n - `POST /export/vacancies/matching_employees`\n - `POST /job_architecture/export/jobs/matching_employees`\n- Added the `active_only` query parameter to\n `GET /reports/data_maturity_scan/data_improvement_actions`. When set to `true`,\n only active Employees and Jobs are included in the Data Improvement Actions.\n- Added the `category` query parameter to `POST /job_architecture/export/suggestions`\n and `POST /job_architecture/suggestions/interactions`. Set `category=tasks` to\n export or interact with task suggestions instead of the default skill suggestions.\n- Added the `429 Too Many Requests` response to all API endpoints. The API now\n returns this status code when rate limits are exceeded.\n- Added a new **Working History Dates** action generator to the Data Improvement Actions report\n (`GET /reports/data_maturity_scan/data_improvement_actions`). It identifies Working History\n Skill Events where a duration cannot be calculated due to missing `start_date`, missing\n `end_date`, or identical start and end dates. Examples are grouped by Employee.\n- The `include=proficiency_level` parameter on Job and Job Family Skill Profile endpoints now\n returns `governed_proficiency_level` and `inferred_proficiency_level` fields (instead of\n `proficiency_level`). Similarly, `include=proficiency_float` returns `governed_proficiency_float`\n and `inferred_proficiency_float`, and `include=critical` returns `governed_critical` and\n `inferred_critical`. This applies to the following endpoints:\n - `GET /job_architecture/jobs/{job_external_id}/skill_profile`\n - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n - `POST /job_architecture/export/jobs/skill_profiles`\n - `POST /job_architecture/export/job_families/skill_profiles`\n- The `validation_state` field is now always included on each Skill in the response of the\n above endpoints. The `include=skill_validation_state` parameter is no longer needed.\n- Suggested Skills (with `validation_state: \"suggested\"`) are now returned alongside governed\n Skills in the Skill Profile response for the above endpoints.\n- Added the `strict` query parameter to\n `POST /employees/{employee_external_id}/skill_events`. When `strict` is enabled,\n Skill Event creation will fail if the referenced Job has an empty Skill Profile.\n- Added the `end_active_jobs` query parameter to\n `POST /employees/{employee_external_id}/skill_events`. When enabled, any currently\n active working history Skill Event (without an `end_date`) for the Employee will be\n ended automatically when the new Skill Event is created.\n\n### February 2026\n\n- Added the `include=business_relevant` query parameter to the `POST /export/skills`\n endpoint to include whether a Skill is marked as business relevant.\n- Added the `output_skills_sorting` query parameter to `GET /employees/{external_id}/skill_profile` to sort Skills alphabetically or by decreasing confidence.\n- The `output_skills_sorting` body parameter on `POST /export/employees/skill_profiles` now also works when an external vendor is specified.\n- Added the `vocab_language` query parameter to the following matching endpoints\n to specify the display language for Skill names in the response:\n - `POST /employees/{external_id}/matching_vacancies`\n - `POST /employees/{external_id}/matching_jobs`\n - `POST /employees/{external_id}/matching_job_families`\n - `GET /employees/{employee_external_id}/match_assigned_position`\n - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`\n - `GET /employees/{employee_external_id}/jobs/{job_external_id}/match`\n - `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match`\n - `POST /vacancies/{external_id}/matching_employees`\n - `POST /job_architecture/jobs/{job_external_id}/matching_employees`\n - `GET /job_architecture/jobs/{job_external_id}/market_alignment`\n - `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles`\n - `POST /job_architecture/jobs/{job_external_id}/matching_source_jobs`\n - `POST /job_architecture/jobs/{job_external_id}/matching_target_jobs`\n - `POST /job_architecture/job_families/{job_family_external_id}/matching_employees`\n - `POST /export/employees/match_assigned_position`\n - `POST /export/vacancies/matching_employees`\n - `POST /export/employees/matching_vacancies`\n - `POST /export/employees/matching_jobs`\n - `POST /job_architecture/export/jobs/matching_employees`\n - `POST /job_architecture/export/jobs/market_alignment`\n - `POST /job_architecture/export/job_families/suggested_skill_profiles`\n - `POST /job_architecture/export/suggestions`\n - `POST /employees/{employee_external_id}/recommended_courses`\n - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses`\n - `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses`\n - `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses`\n - `POST /skills/lookup`\n - `POST /export/employees/skill_profiles`\n - `POST /job_architecture/export/jobs/suggested_skill_profiles`\n - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/gap`\n- Added the **Work Intelligence Task Profile** endpoints (experimental):\n - `GET /tasks/search` - Search for Tasks using a fuzzy text query with AI\n impact information\n - `GET /employees/{employee_external_id}/task_profile` - Retrieve an\n Employee's Task Profile with optional AI impact and source event\n information\n - `GET /job_architecture/jobs/{job_external_id}/task_profile` - Retrieve a\n Job's Task Profile with optional AI impact and source data information\n - `POST /export/employees/task_profiles` - Export Task Profiles for all\n Employees with pagination and filters\n - `POST /job_architecture/export/jobs/task_profiles` - Export Task Profiles\n for all Jobs with pagination and filters\n - `PATCH /employees/{employee_external_id}/task_profile` - Provide feedback\n on tasks in an Employee's Task Profile, setting each task's\n `validation_state` to `validated` or `rejected`\n - `PATCH /job_architecture/jobs/{job_external_id}/task_profile` - Provide\n feedback on tasks in a Job's Task Profile, setting each task's\n `validation_state` to `validated` or `rejected`\n - `POST /export/tasks` - Bulk export of Tasks.\n- Added the `inferred_proficiency_level` field to the return of the\n `POST /employees/suggestions/skills` endpoint when `include=proficiency` is\n set as a query parameter\n- Added the `include=inference_enabled` query parameter to indicate whether the \n Skill can be inferred, applicable to the following endpoints:\n - `GET /taxonomy/skills`\n - `GET /taxonomy/skills/{skill_id}`\n - `GET /taxonomy/export`\n - `POST /export/skills`\n\n### January 2026\n\n- Added the `vocab_language` query parameter to the following endpoints to\n specify the display language for Skill names in the response:\n - `POST /job_architecture/jobs/metrics/adoption_metrics`\n - `POST /job_architecture/export/job_families/skill_profiles`\n - `POST /job_architecture/export/jobs/skill_profiles`\n - `POST /job_architecture/export/jobs/market_skill_profiles`\n - `POST /employees/metrics/adoption_metrics`\n- Added the `merge_request` Skill Event type for Employees. When creating or\n updating Skill Events via\n `POST /employees/{employee_external_id}/skill_events` or\n `PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id}`,\n the `event_type` can now be `merge_request` with content containing `title`,\n `description`, and `commits` (list of objects with `message`). Merge request\n events are processed asynchronously to infer skills from the title,\n description, and commit messages.\n- Changed the `POST /taxonomy/skills` endpoint to require write_skills scope\n access.\n- Added the `DELETE /taxonomy/skills/{skill_id}` endpoint which allows for\n deleting custom Skills from the system. This endpoint requires write_skills\n scope access.\n- Added the `vocab_language` query parameter to the\n `PATCH /taxonomy/skills/{skill_id}` endpoint to support updating descriptions\n and names of Skills in different languages.\n- Added the `skill_source` to the output of the following endpoints:\n - `GET /taxonomy/skills/{skill_id}`\n - `GET /taxonomy/skills`\n - `GET /taxonomy/export`\n - `POST /export/skills`\n- Added the `default_skill_name` and `default_skill_description` to the output\n of the following endpoints:\n - `GET /taxonomy/skills/{skill_id}`\n - `GET /taxonomy/skills`\n - `GET /taxonomy/export`\n- Added the `include=default_skill_name` and `include=default_skill_description`\n to the `POST /export/skills` endpoint to add the `default_skill_name` and\n `default_skill_description` to the output.\n- Added the `filters` body parameter with the `skill_id_is_in_list` and\n `skill_source` filters to the `POST /export/skills` endpoint.\n- Added pagination to the `POST /export/skills` endpoint using the `limit` and\n `starting_after` body parameters.\n- Added the `external_vendor` query parameter to the `GET /taxonomy/changes`\n endpoint to support retrieving Taxonomy Changes in an external vendor's Skill\n vocabulary.\n- Added the `create_skill` and `delete_skill` operation types to the\n `GET /taxonomy/changes` and `POST /taxonomy/apply` endpoints.\n- Added the `POST /taxonomy/changes` endpoint.\n- Added the `vocab_update_add_skill` operation type to the\n `GET /taxonomy/changes` and `POST /taxonomy/changes` endpoint.\n\n### December 2025\n\n- Added the `include_overqualified` and `min_critical_skills_match_ratio`\n parameters to the employee-job matching endpoints to filter matches based on\n their overqualification status and on the matching ratio of critical skills.\n- Enhanced the employee-job matching and match endpoints\n (`POST /employees/{external_id}/matching_jobs`,\n `POST /job_architecture/jobs/{job_external_id}/matching_employees`,\n `POST /matching/export/employees/matching_jobs`,\n `POST /job_architecture/export/jobs/matching_employees`,\n `GET /employees/{employee_external_id}/match_assigned_position`,\n `GET /employees/{employee_external_id}/jobs/{job_external_id}/match`, and\n `POST /export/employees/match_assigned_position`) to automatically include\n additional fields when proficiency matching or criticality matching is enabled\n on the tenant. When proficiency matching is enabled, responses include\n `overqualified` status (for matching endpoints only), `skill_proficiency`, and\n `adjacent_skill_proficiency` fields. When criticality matching is enabled,\n responses include `critical` and `gap_impact` fields.\n- Added the `include` query parameter to the\n `GET /reports/data_maturity_scan/job_maturity_overview` and\n `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints to\n include additional metrics in the response.\n - For Jobs: `job_data_count` and `data_distribution`.\n - For Employees: `valid_assigned_position`, `has_business_data`, and\n `sufficient_working_history`.\n- Removed `MIN_SOURCE_CONFIRMATION` from the list of possible reasons in the\n Data Maturity Scan maturity overview endpoints.\n- Added the `is_active` query parameter to the\n `GET /reports/data_maturity_scan/job_maturity_overview` and\n `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints to\n filter entities by their active status.\n- Removed the `force_recalculate` parameter from the\n `GET /reports/data_maturity_scan/job_maturity_overview` and\n `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints as the\n underlying data is now updated continuously.\n\n### November 2025\n\n- Added the `low_data_availability` query paremeter to the `GET /employees`\n endpoint.\n- Added the `low_data_availability` and `job_family` query parameters to the\n `GET /job_architecture/jobs` endpoint.\n- Added the `job_count` to the output of the `GET /job_architecture/export`\n endpoint.\n\n### October 2025\n\n- Added the `external_vendor` query parameter to the\n `PUT /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}`\n and\n `DELETE /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}`\n endpoints to support applying Taxonomy Changes in an external vendor's Skill\n vocabulary.\n- Added the `external_vendor` query parameter to the\n `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills`,\n `GET /taxonomy/export` and `GET /taxonomy/skills` endpoints to display Skills\n in an external vendor's Skill vocabulary.\n- Added the `include=properties` query parameter to the following endpoints to\n show properties of each Skill:\n - `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` (List\n skills in a skill cluster)\n - `GET /taxonomy/skills` (List all skills)\n - `POST /export/skills` (Export all skills)\n - `GET /taxonomy/export` (Taxonomy export)\n - `GET /taxonomy/skills/{skill_id}` (Get Skill endpoint)\n - `GET /employees/{external_id}/skill_profile` (Get Employee Skill profile)\n - `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n (Get Skill Profile Job Family)\n - `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile`\n (Get suggested skill profile Job Family)\n - `GET /job_architecture/jobs/{job_external_id}/skill_profile` (Get Skill\n Profile Job)\n - `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile`\n (Get suggested skill profile Job)\n - `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` (Get\n external market profiles for Job)\n - `POST /export/employees/skill_profiles` (Export Employee Skill Profile)\n - `POST /job_architecture/export/jobs/skill_profiles` (Export Job Skill\n Profile)\n - `POST /job_architecture/export/jobs/suggested_skill_profiles` (Export\n Suggested Job Skill Profile)\n - `POST /job_architecture/export/jobs/market_skill_profiles` (Export Market\n Job Skill Profile)\n - `POST /job_architecture/export/job_families/skill_profiles` (Export Job\n Family Skill Profile)\n - `POST /job_architecture/export/job_families/suggested_skill_profiles`\n (Export Job Family Skill Suggested Profile)\n- Added the `properties` query parameter to the following endpoints to filter\n skills by their properties:\n - `POST /employees/suggestions/skills` (Get suggestions, validated and\n rejected Skills for selected Employees)\n - `GET /skills/search` (Search for Skills similar to the text provided) The\n parameter uses the format `properties[property_name]=value` to filter\n skills that have a specific property with a specific value. For example,\n `properties[sap_status]=active` will only return skills that have the\n `sap_status` property set to `active`.\n- Added the `external_vendor` query parameter to the\n `PATCH /taxonomy/skills/{skill_id}` endpoint to support updating descriptions\n and properties of Skills in an external vendor's Skill vocabulary.\n- Added the `POST /taxonomy/skills` endpoint which allows for creating new\n Skills in the system, either in TechWolf Skill vocabulary or an external\n vendor's Skill vocabulary. This endpoint requires admin scope access.\n- Added the `restore` query parameter to the `POST /employees` endpoint to\n enable support for restoration of soft deleted Employees during the grace\n period.\n- Added the `include=proficiency` and `include=job_critical` to the query\n parameters of the `GET /employees/{employee_external_id}/suggestions/skills`\n endpoint to allow the `self_rated_proficiency_level` and\n `is_job_critical_skill` attributes to be included in the response.\n- Added the `external_vendor` query parameter to all matching endpoints and some\n additional endpoints:\n - `POST /employees/{external_id}/matching_vacancies`\n - `POST /vacancies/{external_id}/matching_employees`\n - `POST /employees/{external_id}/matching_jobs`\n - `POST /job_architecture/jobs/{external_id}/matching_employees`\n - `POST /job_architecture/jobs/{external_id}/matching_source_jobs`\n - `POST /job_architecture/jobs/{external_id}/matching_target_jobs`\n - `POST /employees/{external_id}/matching_job_families`\n - `POST /job_architecture/job_families/{external_id}/matching_employees`\n - `POST /employees/{external_id}/matching_companies`\n - `POST /companies/{external_id}/matching_employees`\n - `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`\n - `GET /employees/{employee_external_id}/jobs/{job_external_id}/match`\n - `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match`\n - `GET /employees/{employee_external_id}/match_assigned_position`\n - `POST /employees/{employee_external_id}/recommended_courses`\n - `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses`\n - `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses`\n - `POST /export/employees/match_assigned_position`\n - `POST /export/employees/matching_jobs`\n - `POST /export/employees/matching_vacancies`\n - `POST /export/vacancies/matching_employees`\n - `POST /job_architecture/export/jobs/matching_employees`\n - `POST /employees/search`\n - `POST /companies/search`\n - `POST /vacancies/search`\n - `POST /skills/lookup`\n\n### September 2025\n\n- Added the `GET /export/vacancies/skill_profiles` endpoint to paginate through\n all Skill Profiles of Vacancies in the API in bulk.\n- Added support to display Skill Profiles in external vendor Skills with the\n `response_format=list` response format in the\n `POST /export/courses/skill_profiles` and\n `POST /export/vacancies/skill_profiles`\n- Added support to display hierarchical Skill profiles with the\n `response_format=hierarchy` response format, for the\n `POST /export/courses/skill_profiles` and the\n `POST /export/vacancies/skill_profiles` endpoints, both for TechWolf Skills\n and external vendor Skills.\n- Added an experimental `POST /export/skills` endpoint that exports the\n information for all Skills in the system.\n- Added the `POST /export/employees/matching_jobs` endpoint to export the top\n matching Jobs for Employees.\n- Added the `POST /job_architecture/export/jobs/matching_employees` endpoint to\n export the top matching Employees for Jobs.\n- Added the `POST /export/employees/matching_vacancies` endpoint to export the\n top matching Vacancies for Employees.\n- Added the `POST /export/vacancies/matching_employees` endpoint to export the\n top matching Employees for Vacancies.\n- Added the `external_vendor` query parameter to the `POST /taxonomy/apply`\n endpoint to support applying Taxonomy Changes in an external vendor's Skill\n vocabulary.\n\n### August 2025\n\n- Added instructions on how to set up OAuth authentication to the Workday Skill\n Sync Integration documentation.\n- Added support to display descriptions and domains for external vendor Skills\n in the `GET /taxonomy/skills/{skill_id}` endpoint.\n- Added support to display Skill Profiles in external vendor Skills with the\n `response_format=hierarchy` response format in the\n `GET /employees/skill_profiles` and `POST /export/employees/skill_profiles`\n endpoints.\n- Added support to display hierarchical Skill profiles with the\n `response_format=hierarchy` response format, for the\n `GET /courses/{course_external_id}/skill_profile` and the\n `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints, both for\n TechWolf Skills and external vendor Skills.\n\n### July 2025\n\n- Add support to display adoption metrics in external vendor Skills in the\n `POST /job_architecture/jobs/metrics/adoption_metrics` and\n `POST employees/metrics/adoption_metrics` endpoints.\n- Add support to display Skill Profiles in external vendor Skills with the\n `response_format=hierarchy` response format in the\n `GET /job_architecture/jobs/skill_profiles` and\n `GET /job_architecture/job_families/skill_profiles` endpoints.\n- Add support to display Skill Profiles in external vendor Skills in the\n `POST /job_architecture/export/jobs/skill_profiles` and\n `POST /job_architecture/export/job_families/skill_profiles` endpoints.\n- Add support to display the market Skill Profiles in external vendor Skills in\n the `GET /job_architecture/jobs/market_skill_profiles` and\n `POST /job_architecture/export/jobs/market_skill_profiles` endpoints.\n\n### June 2025\n\n- Update the `include` parameter in the \n `GET /employees/{employee_external_id}/skill_profile` endpoint to allow\n `inferred_proficiency_level` and `inferred_proficiency_float` to be included\n with `response_format=list`.\n- Update the `include` body parameter in the \n `POST export/employees/skill_profiles` endpoint to allow the\n `self_rated_proficiency_level`, `self_rated_proficiency_float`\n ,`inferred_proficiency_level` and `inferred_proficiency_float` fields to be\n included.\n- Add the `GET /job_architecture/issues` endpoint to fetch Job issues.\n- Add the `GET /job_architecture/issues/summary` endpoint to get a summary of\n the number of Job issues per type.\n- Add the `include=issues` parameter to the `GET /job_architecture/export`\n endpoint.\n- Add the `GET /job_architecture/changes` endpoint to fetch Job architecture\n changes.\n- Add the `POST /job_architecture/changes` endpoint to start the batch\n generation of Job changes.\n- Add the `PATCH /job_architecture/changes` endpoint to bulk update multiple job\n architecture changes at once.\n- Add the `GET /job_architecture/changes/summary` endpoint to get a summary of\n the number of Job changes per type.\n- Add the `POST /job_architecture/changes/preview` endpoint to generate a\n preview Job change.\n- Add the `GET /job_architecture/changes/{change_id}` endpoint to get detailed\n information about a specific Job architecture change.\n- Add the `PATCH /job_architecture/changes/{change_id}` endpoint to update a\n specific Job architecture change with new data.\n\n### May 2025\n\n- Add the `self_rated_proficiency_level` and `self_rated_proficiency_float`\n attributes to the request body of the\n `PATCH /employees/{employee_external_id}/skill_profile` endpoint for the\n `skills` and `external_vendor_skills` feedback formats.\n- Update the `include` parameter in the\n `GET /employees/{employee_external_id}/skill_profile` endpoint to allow\n `self_rated_proficiency_level` and `self_rated_proficiency_float` to be\n included with `response_format=list`.\n\n### April 2025\n\n- Add the `GET /job_architecture/jobs/market_alignment` and\n `POST job_architecture/export/jobs/market_alignment` endpoints.\n\n### March 2025\n\n- Add `ticket_system` field to the `ticket` event type to be able to specify the\n ticketing system where the ticket originated from. This field is important for\n skill inference as different models may be used for different ticketing\n systems.\n\n### February 2025\n\n- Allow patching of Organisational Units with `parent_id=null` to become a root\n Organisational Unit in the `PATCH /organisational_units/{external_id}`\n endpoint.\n- Add `GET /job_architecture/peer_groups` endpoint.\n\n### January 2025\n\n- Add the optional `proficiency_float` field to the request body of the\n `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` and\n `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoints.\n- Add the `include=proficiency_float` option to the include query parameter of\n the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and\n `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoints.\n- Add the `include=proficiency_float` option to the include body parameter of\n the `POST /job_architecture/export/jobs/skill_profiles` and\n `POST /job_architecture/export/job_families/skill_profiles` endpoints.\n- Add the `external_vendor` query parameter to the\n `POST /employees/suggestions/skills` endpoint\n- Remove the `strict` query parameter from the\n `POST /employees/suggestions/skills` endpoint\n- Add the `include=critical` option to the include query parameters to the\n `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile`\n endpoint.\n- Update the `include` parameter in the\n `GET /job_architecture/jobs/{job_external_id}/skill_profile` and\n `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoints to allow `proficiency_level` and `critical` to be included with\n `response_format=hierarchy`\n- Make the `skill_cluster_description` optional and set it to an empty string by\n default. Additionally, save any placeholder value or a description that\n exactly matches the Skill Cluster name as an empty string.\n\n### December 2024\n\n- Add the `include=proficiency_level` and `include=critical` options to the\n include body parameter of the\n `POST /job_architecture/export/jobs/skill_profiles` endpoint.\n- Add the `include=proficiency_level` and `include=critical` options to the\n include body parameter of the\n `POST /job_architecture/export/job_families/skill_profiles` endpoint.\n- Add the `external_vendor` query parameter to the `GET /skills/search`\n endpoint.\n- Return the default proficiency level when no proficiency level is set in the\n `GET /job_architecture/jobs/{job_external_id}/skill_profile`,\n `POST /job_architecture/export/jobs/skill_profiles`,\n `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`,\n and `POST /job_architecture/export/job_families/skill_profiles` endpoints.\n- Add the `force_recalculate` query parameter to all report endpoints.\n\n### November 2024\n\n- Add `limit`, `offset`, and `update_low_data_availability` query parameters to\n the `GET /reports/data_maturity_scan/employee_maturity_overview` and\n `GET /reports/data_maturity_scan/job_maturity_overview` endpoints.\n- Add `include=skill_cluster_description` parameter to the\n `GET /taxonomy/skill_clusters` endpoint.\n- Add `skill_cluster_description` response body field and query parameter\n `include=skill_cluster_description` to the `GET taxonomy/export` endpoint.\n- Add the `PATCH /taxonomy/skills/{skill_id}` endpoint.\n- Return the custom Skill description in the `GET /taxonomy/skills`,\n `GET /taxonomy/skills/{skill_id}`, and `GET /taxonomy/export` endpoints if one\n is set.\n- Add the `update_skill` operation type to the `GET /taxonomy/changes` and\n `POST /taxonomy/apply` endpoints.\n- Add `include=skill_description` parameter to the\n `/taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint.\n- Add `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` and\n `POST /job_architecture/export/jobs/market_skill_profiles` endpoints.\n- Add the `proficiency_level` and `critical` attributes to the request body of\n the `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` endpoint.\n- Add the `proficiency_level` and `critical` attributes to the request body of\n the\n `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoint.\n- Add the `include=proficiency_level` and `include=critical` query parameters to\n the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and\n `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoints.\n\n### October 2024\n\n- Add `POST /job_architecture/jobs/metrics/adoption_metrics` endpoint.\n- Add `POST /employees/metrics/adoption_metrics` endpoint.\n- Add `source_data` to `skills` returned in\n `GET/job_architecture/jobs/{job_external_id}/skill_profile` and\n `GET/job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoints.\n- Add CRUD operations for Custom Properties and Custom Property Definitions for\n Organisational Units.\n- Add `active` attribute to the Organisational Unit entity.\n- Add `hierarchy` as a possible response format for the\n `GET /employees/{employee_external_id}/skill_profile` endpoint.\n- Add `include=custom_properties` parameter to\n `GET/job_architecture/job_families`, `GET/job_architecture/jobs`,\n `GET/courses`, `GET/vacancies`, `GET/employees`, `GET/companies`,\n `GET/taxonomy/domains`, `GET/taxonomy/subdomains`,\n `GET/taxonomy/skill_clusters` and `GET/taxonomy/skills` endpoints.\n- Add `output_skills_sorting` parameter to\n `GET /job_architecture/export/job_families/suggested_skill_profiles`,\n `GET /job_architecture/export/job_families/skill_profiles`,\n `GET /job_architecture/export/jobs/suggested_skill_profiles` and\n `GET /job_architecture/export/jobs/skill_profiles` endpoints.\n- Deprecate the\n `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint.\n- Add the `vocab_update_rename_skill`, `vocab_update_merge_skill`, and\n `vocab_update_remove_skill` operation types to the `GET /taxonomy/changes`\n endpoint.\n\n### September 2024\n\n- Add `GET /job_architecture/jobs/{job_external_id}/matching_source_jobs`\n endpoint.\n- Add `GET /job_architecture/jobs/{job_external_id}/matching_target_jobs`\n endpoint.\n- Add error code 400 as possible response code for\n `DELETE /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}`\n for\n `DELETE /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}`\n when trying to delete Skill Profile Feedback instances and respective examples\n for this\n- Add\n `GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}`\n endpoint.\n- Add `skill_profile_feedback` as a `data_type` to the Job Family Profile Data\n of a Job Family. This new `data_type` may be included the responses of\n `GET /job_architecture/job_families/{job_family_external_id}/profile_data` and\n `GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}`.\n- Add\n `GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}`\n endpoint.\n- Add `skill_profile_feedback` as a `data_type` to the Job Profile Data of a\n Job. This new `data_type` may be included the responses of\n `GET /job_architecture/jobs/{job_external_id}/profile_data` and\n `GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}`.\n- Add `skill_id` query parameter to the `GET /employees` and\n `GET /organisational_units/export` endpoints that allows for filtering the\n returned entities on whether their Skill Profile contains a certain Skill.\n- Add an experimental `POST /employees/suggestions/skill` endpoint that allows\n to find suggested, validated, and rejected Skill suggestions for Employees.\n- Add `en_us`, `de`, and `fr` to the list of supported values for the\n `vocab_language` query parameters in the\n `GET /{entity}/{external_id}/skill_profile`,\n `GET /taxonomy/skill_clusters/{external_id}/skills`, `GET /taxonomy/skill/`,\n and `GET /taxonomy/export/` endpoints.\n- Add the `low_data_availability_flag` to the possible values of the `include`\n query parameter of the `GET /organisational_units/export` and\n `GET /job_architecture/export` endpoints.\n- Add `skill_id` query parameter to the `GET /job_architecture/export` endpoint\n that allows for filtering the entities on whether their Skill Profile contains\n a certain Skill.\n- Add `source_coverage` metric to the response of the\n `GET /reports/data_maturity_scan/job_quality_matrix` and\n `GET /reports/data_maturity_scan/employee_quality_matrix` endpoints.\n- Add `skill_name`, `skill_cluster_name`, `subdomain_name`, and `domain_name` to\n the output of `GET /taxonomy/changes`.\n- Add `subdomain_name` to output of the\n `POST /job_architecture/export/jobs/skill_clusters`,\n `POST /export/employees/skill_clusters` and\n `GET /employees//skill_profile?response_format=skill_clusters`\n endpoints for 4-level Taxonomies.\n- Add `source_data` to the output of\n `GET /jobs/{job_external_id}/suggested_skill_profile`,\n `GET /job_families/{job_family_external_id}/suggested_skill_profile`,\n `POST /job_architecture/export/jobs/suggested_skill_profiles`, and\n `POST /job_architecture/export/job_families/suggested_skill_profiles`.\n- Add endpoints `POST /integrations/file_load_task` to upload a CSV-file from S3\n into the system and `GET /integrations/file_load_task/{task_id}` to get the\n status of the File Load Task.\n\n### August 2024\n\n- Add `skill_validation_state` to the possible values of the `include` query\n parameter of the `GET /job_architecture/export/jobs/skill_profiles`,\n `GET /job_architecture/export/jobs/suggested_skill_profiles`,\n `GET /job_architecture/export/job_families/skill_profiles`, and\n `GET /job_architecture/export/job_families/suggested_skill_profiles`\n endpoints.\n- Add `skill_validation_state` to the possible values of the `include` query\n parameter of the\n `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n and\n `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile`\n endpoints.\n- Add `skill_validation_state` to the possible values of the `include` query\n parameter of the `GET /job_architecture/jobs/{job_external_id}/skill_profile`\n and `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile`\n endpoints.\n- Add Employee and Job key metric reports. `GET /reports/employees/key_metrics`\n `GET /reports/jobs/key_metrics`\n `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile`\n\n### July 2024\n\n- Add CRUD operations for Organisational Units.\n- Add export endpoint `GET /organisational_units/export` to get the full\n hierarchy of the Organisational Units including the `total_nr_of_employees`\n field.\n- Added `organisational_unit` field to Employees that is returned in\n `GET /employees` and `GET /employees/{external_id}`.\n- Added query parameter `organisational_unit` to `GET /employees` to filter\n Employees on their linked Organisational Unit.\n- Added the `low_data_availability_flag` to the possible values of the `include`\n query parameter of the `GET /employees/{external_id}/skill_profile` and\n `GET /job_architecture/jobs/{job_external_id}/skill_profile` endpoints.\n- Added the `low_data_availability_flag` to the possible values of the `include`\n body parameter of the `POST /export/employees/skill_profiles` and\n `POST /job_architecture/export/jobs/skill_profiles` endpoints that allows\n including the low data availability flag in the output.\n- Added the option to upload files of data type `job_description` as Job Profile\n Data. Available in the\n `POST /job_architecture/jobs/{job_external_id}/profile_data` and\n `PATCH /job_architecture/jobs/{job_external_id}/profile_data` endpoint.\n- Added the option to upload files of data type `job_family_description` as Job\n Family Profile Data. Available in the\n `POST /job_architecture/job_families/{job_family_external_id}/profile_data`\n and\n `PATCH /job_architecture/job_families/{job_family_external_id}/profile_data`\n endpoint.\n\n### June 2024\n\n- Add `low_data_availability` attribute to the Employee entity.\n- Add `low_data_availability` attribute to the Job entity.\n- Added Data Maturity Scan reporting endpoints:\n - `GET /reports/data_maturity_scan/employee_quality_matrix`\n - `GET /reports/data_maturity_scan/job_quality_matrix`\n - `GET /reports/data_maturity_scan/employee_maturity_overview`\n - `GET /reports/data_maturity_scan/job_maturity_overview`\n - `GET /reports/data_maturity_scan/data_improvement_actions`\n- Added `rejected_skills` to the possible values of the `include` body parameter\n of the `POST /export/employees/skill_profiles` endpoint that allows including\n rejected Skills in the output.\n\n### May 2024\n\n- Add `GET /employees/{employee_external_id}/jobs/{job_external_id}/match`\n endpoint that allows to match an Employee with a Job.\n- Add `POST /employees/{employee_external_id}/matching_jobs` endpoint that\n allows to find the top matching Jobs for an Employee.\n- Add `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint\n that allows to find the top matching Employees for a Job.\n- Add `POST /job_architecture/job_families/{external_id}/matching_employees`\n endpoint that allows to find the top matching Employees for a Job Family.\n- Add\n `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses`\n endpoint that recommends Courses to address the Skill Gap between the Employee\n and the Job.\n- Add\n `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match`\n endpoint that allows to match an Employee with a Job Family.\n- Add `GET /employees/{employee_external_id}/match_assigned_position` endpoint\n that allows to match an Employee with their assigned position.\n- Add `POST /export/employees/match_assigned_position` endpoint that allows to\n match Employees with their assigned position in bulk.\n- Add `output_skills_sorting` body parameter to the\n `POST /export/employees/skill_profiles` endpoint, allowing `alphabetical` to\n sort the Skills in the resulting profiles alphabetically, or `confidence` to\n sort them by decreasing confidence.\n- Add `is_active` filter to the\n `POST /job_architecture/export/jobs/skill_profiles`,\n `POST /job_architecture/export/jobs/suggested_skill_profiles`,\n `POST /job_architecture/export/jobs/skill_clusters`,\n `POST /job_architecture/export/job_families/skill_profiles`,\n `POST /job_architecture/export/job_families/suggested_skill_profiles`,\n `POST /export/employees/skill_profiles`,\n `POST /export/employees/skill_clusters`, `POST /export/courses/skill_profiles`\n export endpoints to only include active or inactive entities in the result\n based on the filter value.\n- Add `is_active` query parameter to the `GET /job_architecture/export` export\n endpoint to only include active or inactive jobs and job families in the\n result.\n- Add `is_active` query parameter to the `GET /employees`, `GET /vacancies`,\n `GET /courses`, `GET /job_architecture/jobs`,\n `GET /job_architecture/job_families` list endpoints to only include active or\n inactive entities in the result.\n- Add `include=entity` and `include=custom_properties` query parameter to\n `POST /employees/{external_id}/matching_job_families`.\n- Removed `Core` as a possible value of the `skill_type` field of a Skill in the\n Job Family Skill Profile.\n- Add `response_format=explained` query parameter to\n `POST /employees/{external_id}/matching_vacancies`,\n `POST /vacancies/{external_id}/matching_employees` and\n `POST /employees/{external_id}/matching_job_families`, that includes\n `missing_skills` and `present_skills` response body fields as additional\n information about the matches.\n- Add `include=adoption` query parameter to the `taxonomy/skills/{skill_id}`\n endpoint to include the adoption of the Skill in Jobs and Employees in the\n response.\n- Add `assigned_position_id` attribute to the Employee entity.\n- Allow `PATCH /employees//skill_events/` on the\n `resume_document`, `feedback`, `goal`, `project`, `certificate`, `learning`\n and `ticket` event types.\n\n### April 2024\n\n- Add `active` attribute to Course, Employee, Job and Job Family entity.\n- Add support to display Skill Profiles in external vendor Skills on GET, using\n the query parameter `external_vendor`, for Course, Employee, Job and Job\n Family entities. Usage:\n- `GET /employee/{employee_id}/skill_profile?external_vendor={external_vendor}`\n- `GET /job_architecture/jobs/{job_external_id}/skill_profile?external_vendor={external_vendor}`\n- `GET /job_architecture/job_families/{job_family_external_id}/skill_profile?external_vendor={external_vendor}`\n- `GET /courses/{external_id}/skill_profile?external_vendor={external_vendor}`\n- Add support to provide feedback to Skill Profiles in external vendor Skills,\n using the query parameter `feedback_format=external_vendor_skills`, for\n Course, Employee, Job and Job Family entities. Usage:\n - `PATCH /employee/{employee_id}/feedback_format=external_vendor_skills`\n - `PATCH /job_architecture/jobs/{job_external_id}/skill_profile?feedback_format=external_vendor_skills`\n - `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile?feedback_format=external_vendor_skills`\n - `PATCH /courses/{external_id}/skill_profile?feedback_format=external_vendor_skills`\n- Deprecate\n `GET /employee{employee_external_id}/vacancy/{vacancy_external_id}/recommend_courses`\n- Add\n `POST /employee{employee_external_id}/vacancy/{vacancy_external_id}/recommend_courses`\n endpoint which makes use of an updated and improved methodology to recommend\n Courses.\n- Update `POST /employee{employee_external_id}/recommend_courses` endpoint in\n line with the updated and improved methodology to recommend Courses.\n\n### March 2024\n\n- Add `POST /job_architecture/export/jobs/suggested_skill_profiles` endpoint to\n paginate through all suggested Skill Profiles of Jobs in the API in bulk.\n- Add `POST /job_architecture/export/job_families/suggested_skill_profiles`\n endpoint to paginate through all suggested Skill Profiles of Job Families in\n the API in bulk.\n- The `domain_namespace` query parameter is available on the\n `job_architecture/export/jobs/skill_profiles` and\n `job_architecture/export/job_families/skill_profiles` endpoints.\n- When requesting an Employee Skill Profile through either\n `GET /employee/{employee_id}/skill_profile` or\n `POST /export/employees/skill_profiles`, the response will now include the\n `source_events` field on all Skills, when requesting sources. `source_events`\n provides more insights into which Skill Event contributes to which skill.\n\n### February 2024\n\n- Add `GET /employees/{employee_id}/skill_events/{skill_event_id}` endpoint to\n be able to get a single Skill Event of an Employee.\n- Add `POST /job_architecture/export/jobs/skill_profiles` endpoint to paginate\n through all Skill Profiles of Jobs in the API in bulk.\n- Add `POST /job_architecture/export/job_families/skill_profiles` endpoint to\n paginate through all Skill Profiles of Job Families in the API in bulk.\n- Add support for `ticket` Skill Events.\n- Add support for `skill_notes` Job Profile Data.\n- Deprecated the `POST /job_architecture/export/job/skill_clusters` endpoint and\n added the `POST /job_architecture/export/jobs/skill_clusters`.\n\n### January 2024\n\n- A `source` attribute can now be added to each Skill Profile feedback endpoint\n to indicate the source of the feedback. See all\n `PATCH /{entity}/{entity_id}/skill_profile` endpoints.\n- An `include` query parameter can now be added to the\n `GET /employees/{external_id}/skill_profile` endpoint to include the source\n Skill Events where the reported Skills are inferred from.\n- Add `POST /export/employees/skill_profiles` endpoint to get the Skill profiles\n of all Employees in the API through pagination.\n- Add the `POST /skills/lookup` endpoint to get corresponding UUIDs for a list\n of Skill names.\n- Add `GET /job_architecture/job/{job_id}/suggested_skill_profile` to get\n suggested skills for a Job.\n- Add\n `GET /job_architecture/job_families/{job_family_id}/suggested_skill_profile`\n to get suggested skills for a Job Family.\n\n### December 2023\n\n- Add the `include=custom_properties` query parameter to the\n `GET /taxonomy/skills/{skill_id}` endpoint to include the Custom Properties of\n a Skill in the response.\n- Add the `include=custom_properties` query parameter to the\n `GET /taxonomy/skill_clusters/{skill_cluster_id}` endpoint to include the\n Custom Properties of Skill Clusters in the response.\n- Add the `include=custom_properties` query parameter to the\n `GET /taxonomy/subdomains/{subdomain_id}` endpoint to include the Custom\n Properties of Subdomains in the response.\n- Add the `include=custom_properties` query parameter to the\n `GET /taxonomy/domains/{domain_id}` endpoint to include the Custom Properties\n of Domains in the response.\n- Introduced a `skill_id` field alongside Skill names in our API endpoints to\n avoid ambiguities and conflicts. All endpoints that return Skill names will\n now also return a `skill_id` field. Using Skill names in a request body to\n denote an update of a Skill is deprecated, please use `skill_id` instead.\n- Mark all `/occupations` endpoints as deprecated.\n- Add the `vocab_language` query parameter to the\n `GET /{entity}/{external_id}/skill_profile` endpoints to specify the language\n of the Skill names in the Skill Profile response.\n- Add the `vocab_language` query parameter to the\n `GET /taxonomy/skill_clusters/{external_id}/skills` endpoint to specify the\n language of the Skill names in the Skill Profile response.\n- Add the `vocab_language` query parameter to the `GET /taxonomy/skill/`\n endpoints to specify the language of the Skill names in the Skill Profile\n response.\n- Add the `vocab_language` query parameter to the `GET /taxonomy/export/`\n endpoints to specify the language of the Skill names in the Skill Profile\n response.\n\n### November 2023\n\n- Add the `domain_namespace` query parameter to\n `GET /job_architecture/jobs/{job_external_id}/skill_profile` endpoint to\n express the Skill Domains in either TechWolf or Taxonomy Domains.\n- Add the `domain_namespace` query parameter to\n `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint\n to express the Skill Domains in either TechWolf or Taxonomy Domains.\n- Add the `domain_namespace` query parameter to\n `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoint to express the Skill domains in either TechWolf or Taxonomy Domains.\n- Add `domain_name` response body field and `domain_namespace` query parameter\n to `GET /taxonomy/skills/{skill_id}` endpoint to express the Skill Domains in\n either TechWolf or Taxonomy Domains.\n- Add `domain_name` response body field and `domain_namespace` query parameter\n to `GET /taxonomy/skills` endpoint to express the Skill Domains in either\n TechWolf or Taxonomy Domains.\n- Add the `domain_namespace` query parameter to `GET /skills/search` endpoint to\n express the Skill Domains in either TechWolf or Taxonomy Domains.\n- Add `POST /export/courses/skill_profiles` endpoint to paginate through all\n Skill Profiles of Courses in the API in bulk.\n- Add `last_updated_with_taxonomy_changes` filter to the POST\n `/export/employees/skill_clusters` and POST\n `/job_architecture/export/job/skill_clusters` endpoints.\n- Add `next_starting_after` field to response of\n `POST /export/employees/skill_clusters` endpoint.\n\n### October 2023\n\n- Add `GET /job_architecture/jobs/{job_external_id}/market_skill_profile`\n endpoint to get the market Skill Profile of a Job.\n- Update request sample for `POST /reports/job_architecture_benchmark` endpoint.\n- Mark all `/skill_clusters` endpoints as deprecated.\n\n### September 2023\n\n- Add `skill_description` response body field and query parameter\n `include=skill_description` to `GET taxonomy/export`.\n- Add a `vacancy` data type for Job Profile Data. Available in the POST\n `/job_architecture/jobs/{job_external_id}/profile_data` endpoint.\n- Add the `taxonomy/changes` endpoint to view all changes to the Taxonomy within\n a certain timeframe.\n- Add `skill_id` and `skill_sources` to Skills of response body field in\n `GET export/employees/skill_clusters`.\n- Add a `POST /job_architecture/export/job/skill_clusters` endpoint to fetch Job\n Skill clusters and Skills in bulk.\n- Add the `Subdomain` entity to enable a 4-level Taxonomy hierarchy.\n- Add CRUD operations for Custom Properties and Custom Property Definitions for\n the following Taxonomy entities: `taxonomy/domains`, `taxonomy/subdomains`,\n `taxonomy/skill_clusters`, and `taxonomy/skills`.\n- Add `external_id` and `skill_vocab` fields to the `taxonomy/export` and\n `taxonomy/skill_cluster//skills` endpoints.\n\n### August 2023\n\n- Add `skill_id` response body field and query parameter `search_method` to\n `POST skills/search`.\n- Add `GET` and `POST /taxonomy/domains` to see all Domains and create a new\n Domain respectively. Add `GET`, `PATCH` and\n `DELETE /taxonomy/domains/{external_id}` to see a single Domain, update a\n Domain and delete a Domain respectively.\n- Add `GET` and `POST /taxonomy/skill_clusters` to see all Skill Clusters and\n create a new Skill Cluster respectively. Add `GET`, `PATCH` and\n `DELETE /taxonomy/skill_clusters/{external_id}` to see a single Skill Cluster,\n update a Skill Cluster and delete a Skill Cluster respectively.\n- Add `GET /taxonomy/skill_clusters/{external_id}/skills` to see all Skills in a\n Skill Cluster. Add `PUT` and\n `DELETE /taxonomy/skill_clusters/{external_id}/skills/{skill_external_id}` to\n add a Skill to a Skill Cluster and remove a Skill from a Skill Cluster\n respectively.\n- Add `GET /taxonomy/skills/{concept_uuid}` and `GET /taxonomy/skills` to get\n meta information of a single Skill or multiple Skills.\n- Add `GET /taxonomy/export` to export the full structure of the Taxonomy.\n- Add `POST /taxonomy/apply` to apply a set of changes to the Taxonomy.\n- Add `skill_id` to the response body of\n `GET job_architecture/jobs/{job_external_id}/skill_profile` and\n `GET job_architecture/job_families/{job_family_external_id}/skill_profile`.\n- Add functionality for Jobs to not be linked to a Job Family.\n- Skill Profile feedback in Skill Cluster format\n (`PATCH /employees/{external_id}/skill_profile?feedback_format=skill_clusters`)\n can now be given with a `skill_cluster_id`.\n- Add `GET /job_architecture/export`.\n\n### July 2023\n\n- Add `POST /reports/job_architecture_benchmark`.\n- Add the `include=skill_match_scores` query parameter to the\n `POST /employees/{external_id}/matching_job_families`, which includes match\n scores between the Employee and individual Skills in the response.\n\n### June 2023\n\n- Add `POST /reports/internal_talent_mobility`.\n- Update `POST /reports/skill_inventory`.\n- Add `GET /employees/{employee_external_id}/interactions` and\n `GET /employees/{employee_external_id}/interactions/{interaction_external_id}`\n endpoints, which allow for listing all interactions of an Employee and getting\n a single Interaction respectively.\n- Deprecated the `PUT /employees/{external_id}/skill_profile`,\n `PUT /vacancies/{external_id}/skill_profile`,\n `PUT /courses/{external_id}/skill_profile` and\n `PUT /occupations/{external_id}/skill_profile` endpoints.\n- Add `POST /employees/{employee_external_id}/matching_job_families` endpoint,\n which calculates and returns matching Job Families for an Employee. Weights\n are not customizable, but filtering on Custom Properties, external IDs and the\n `last_updated` field is allowed.\n- Add the `used_event_types` body parameter to the\n `POST /employees/{employee_id}/matching_vacancies` endpoint, allowing to use\n only events of certain types to be taken into account when calculating\n matching Vacancies for an Employee.\n\n### May 2023\n\n- Vacancy searching now works based on literal text matching by default. Skills\n based searching is still possible, as well as a combination of both.\n- Allow `PATCH` on SkillEvents with type `skill_notes`.\n- Add progress to the `POST /reports/skill_inventory` endpoint.\n- Add `skill_cluster_id` to the output of Employee, Vacancy, Course, Occupation\n `GET /{entity}/{external_id}/skill_profile?response_format=skill_clusters`\n endpoints, the `POST /export/employees/skill_clusters` endpoint, and the\n `POST /vacancies/{external_id}/matching_employees?include=skill_clusters`\n endpoint.\n- Add `POST /employees/{employee_external_id}/interactions` and\n `DELETE /employees/{employee_external_id}/interactions/{interaction_external_id}`\n endpoints, which allow the creation and deletion of Interactions between the\n Employee and a title or Vacancy.\n- Add\n `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile`\n and `PATCH /job_architecture/job/{job_external_id}/skill_profile` which allow\n feedback on the Skill Profile of Job Families and Jobs respectively.\n- Add a breakdown of the matching Vacancies for a company in the results of the\n `/companies/search` endpoint.\n\n### April 2023\n\n- Courses can now have a `source` field. When creating Skill Events from a\n Course with a source, the source of the Course will be used if no source is\n provided in the Skill Event.\n- Add `POST /reports/skill_inventory` endpoint to get the Skill Inventory\n report.\n\n### March 2023\n\n- Add Update\n `/employees/{employee_external_id}/skill_events/{skill_event_external_id}`\n endpoint to support updating an Employee's Skill Event.\n- Add Job and Job Family entities to `job_architecture/jobs` and\n `job_architecture/job_families` endpoints respectively.\n- Add Job Profile Data and Job Family Profile Data to the\n `job_architecture/job_families/{job_family_external_id}/profile_data` and\n `job_architecture/jobs/{job_external_id}/profile_data` endpoints respectively.\n- Add `custom_property_is_in_list` filter to\n `POST employees/{employee_external_id}/recommended_courses`.\n- Add the `property_value` and `assigned_position` fields of an Employee to the\n Skill Cluster Adoption report (`reports/employees/skill_cluster_adoption`).\n- Add `GET job_architecture/jobs/{job_external_id}/skill_profile` and\n `GET job_architecture/job_families/{job_family_external_id}/skill_profile`\n endpoints\n- Add `match_feedback` option for the `include` parameter of the\n `/employees/{employee_external_id}/matching_vacancies` and\n `/vacancies/{vacancy_external_id}/matching_employees` endpoints, which\n includes feedback given to a match in the result if applicable.\n- Custom Properties have been added to the Job and Job Family entities. They can\n be requested by using the `custom_properties` include option when sending to\n the `GET job_architecture/jobs/{job_external_id}` and\n `GET job_architecture/job_families/{job_family_external_id}` endpoints.\n- Add Update\n `/job_architecture/jobs/{job_external_id}/profile_data/{profile_data_external_id}`\n and Update\n `/job_architecture/job_families/{job_family_external_id}/profile_data/{profile_data_external_id}`\n endpoints to support updating Job Profile Data and Job Family Profile Data.\n- Create or update working history Skill Events using a `job_id` at\n `POST /employees/{employee_external_id}/skill_events` and\n `PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id}`\n respectively\n\n### February 2023\n\n- Add the multi_max_geo_distances filter in matching for endpoints\n `/employees/{external_id}/matching_vacancies` and\n `/vacancies/{external_id}/matching_employees`.\n- Add the Succession Risk Report available under the `/reports/succession_risk`\n endpoint.\n- Add the `rejected_skills` include option to the\n `POST /export/employees/skill_clusters` endpoint.\n- Add the option to create learning Skill Events from a `course_id`\n\n### January 2023\n\n- Add `competency_type` in `GET /competencies` and\n `GET /competencies/{external_id}`.\n- Add support for specifying the location in LocationAddress format in the\n MaxGeoDistanceFilter.\n- Add the Replacement Risk Report available under the\n `/reports/replacement_risk` endpoint.\n\n### December 2022\n\n- The Get Skill Profile endpoints `/entity_type/{external_id}/skill_profile`\n with `response_format=competencies` now return Skill information.\n- Add `custom_property_list_overlap` filter for Employee and Vacancy matching.\n- Add `GET vacancies/{vacancy_external_id}/metrics/fillability` endpoint, which\n calculates the fillability metric of a Vacancy. The fillability is influenced\n by the number of matching Employees and the number of Vacancies that can be\n filled by those Vacancies. More matching Employees will result in a higher\n fillability, and more matching Vacancies will result in a lower fillability.\n- Add `POST vacancies/{vacancy_external_id}/metrics/fillability` endpoint which\n allows for filtering the used entities on maximal allowed distance and Custom\n Properties, and assigning weights to the different factors used in the\n fillability calculation.\n- Add `exclude_match_feedback` filter to\n `POST employees/{employee_external_id}/recommended_courses` and\n `POST employees/{employee_external_id}/matching_vacancies`\n- Add `DELETE` endpoints to\n `employees/{employee_external_id}/vacancies/{vacancy_external_id}/match_feedback`\n and\n `employees/{employee_external_id}/courses/{course_external_id}/match_feedback`\n- Add `include=competencies` query parameter to\n `vacancies/{vacancy_external_id}/matching_employees`.\n- Add `include` query parameter for the\n `employees/{employee_external_id}/similar` endpoint. Possible values are:\n `entity`, `competencies` and `custom_properties`.\n- Add `validation_state` to Skills returned from\n `GET employees/{employee_external_id}/skill_profile` endpoint in `list` and\n `competency` format.\n- Add `validation_state` to Skills returned from\n `POST export/employees/competencies` endpoint.\n- Add `exclude_match_feedback` filter to the `employees/search` and\n `vacancies/search` endpoints.\n- Add `related_skills` to `include` in `POST export/employees/competencies`\n endpoint.\n- Adding a `proficiency_level` to a competency in the body is no longer required\n when sending feedback via `PUT` or `PATCH` to\n `/employees/{employee_external_id}/skill_profile?feedback_format=competencies`\n- Add `score_breakdown` option for the `include` parameter of the\n `/employees/{employee_external_id}/matching_vacancies` and\n `/vacancies/{vacancy_external_id}/matching_employees` endpoints, which\n includes a breakdown of the contribution of all input weights to the total\n match score in the response body.\n\n### November 2022\n\n- Add the `skill_notes` event type.\n- Add the Competency Adoption Report available under the\n `/reports/employees/competency_adoption` endpoint.\n- Add `POST employees/{employee_external_id}/metrics/employability` endpoint\n which allows for filtering the used entities on maximal allowed distance and\n Custom Properties, and assigning weights to the different factors used in the\n calculation.\n- Add `PATCH` endpoint to `vacancies/{external_id}/skill_profile`,\n `occupations/{external_id}/skill_profile` and\n `courses/{external_id}/skill_profile`.\n- Add `include=relevant_experience` query parameter to\n `employees/{employee_external_id}/matching_vacancies` and\n `vacancies/{vacancy_external_id}/matching_employees`.\n- For `LocationAddress` inputs, `city` can be used instead of `postal_code` now,\n making one of them required instead of having `postal_code` required.\n- The Get Skill Profile endpoints `/entity_type/{ID}/skill_profile` with\n `response_format=competencies` now return Skill category information.\n\n### October 2022\n\n- Add a not equals option (`neq`) to the `custom_property` filter.\n- Add `sources` in the `/export/employees/competencies` endpoint, to be able to\n track from which Skill Events the given competencies originate from.\n- Add support for addresses as an alternative for location coordinates.\n\n### August 2022\n\n- Add `include` query parameter to\n `vacancies/{vacancy_external_id}/matching_employees` to allow retrieving\n Employee information without extra calls.\n- Add `include=location` query parameter option to\n `employees/{employee_external_id}/matching_vacancies`\n- Add a `validation_state` field to the `/export/employees/competencies`\n response. Indicating whether the competencies linked to Employees are already\n validated by a manager or Employee or still suggested.\n\n### July 2022\n\n- Add a category field to the `POST /competencies` and\n `PATCH /competencies/{external_id}` endpoints to change the category of a\n competency.\n\n### June 2022\n\n- Add a PATCH endpoint for Skill Profile feedback on Employees such that Skill\n profiles can be partially updated.\n- Add `last_updated` filter for Employee and Vacancy matching.\n- Add an experimental `POST /export/employees/competencies` endpoint for\n extracting Employee competencies and Skills from the API.\n\n### May 2022\n\n- Change how the `GET /competencies/{external_id}/skill_profile` endpoint\n returns Skill Profiles for clients who use a Taxonomy managed by TechWolf.\n\n### April 2022\n\n- Add support for `project` and `certificate` Skill Events.\n- Add support for explicit `working_history`, `education_history`, and\n `resume_document` Skill Events.\n\n### March 2022\n\n- Add support for `feedback` and `goal` Skill Events.\n\n### February 2022\n\n- Add `include` query parameter to\n `employees/{employee_external_id}/recommended_courses` to allow retrieving\n Course information without extra calls.\n\n### January 2022\n\n- Add Delete\n `/employees/{employee_external_id}/skill_events/{skill_event_external_id}`\n endpoint to support removing an Employee's Skill Event from the API.\n- Add GET `/employees/{employee_external_id}/skill_events` endpoint to support\n fetching an Employee's Skill Events of a specified type in the API. The only\n allowed event type is a `learning_event`.\n- Add POST `/employees/{employee_external_id}/skill_events` endpoint to support\n the creation of Skill Events in the API. The only allowed event type is a\n `learning_event`.\n\n### December 2021\n\n- Add `/employees/{employee_external_id}/recommended_courses` endpoint,\n returning the recommended Courses to improve an Employee's Skill Profile.\n- Removed Certificates from Employees and all its functionalities.\n- The Custom Property weights for the matching endpoints now support the\n `custom_property_contains`, `custom_property_contains_element` ,\n `custom_property_is_in` and `custom_property_is_in_list` configurations. Match\n scores are increased when the applied condition on the matching entities'\n specified Custom Property checks out.\n- The matching endpoints now support the `language` weight configurations. Match\n scores are increased when the matching entities' language levels fall between\n a range of the source entity language levels.\n\n### October 2021\n\n- All endpoints supporting the `explained` response format now return additional\n category information when the explained response format is requested.\n- The Get Skill Profile endpoints `/entity_type/{ID}/skill_profile` now support\n `response_format=categories` and thereby return Skill category information.\n- The Skill Search endpoint `/skills/search` now returns Skill category\n information.\n- The Search endpoints now support German (`de`) language.\n- You can now create and update entities in German with the `language=de` query\n parameter.\n- The Reskilling & Deployment report now provides information for key missing\n Skills on an Employee-level.\n\n### September 2021\n\n- The `/employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`\n endpoint with `response_format=explained` query parameter now returns the body\n with missing Skills included under the `missing_skills` key.\n- Add external Company hiring activity profiling with NACE-codes under the\n `/companies/{external_id}/nace` endpoint.\n- Add the Reskilling & Deployment Report available under the\n `/reports/reskilling_and_deployment` endpoint.\n- Reskilling & Deployment report now supports a Qlik-friendly CSV output format.\n- Reskilling & Deployment report now supports `score_min_threshold`.\n- The `external_id_is_in_list` filter is now supported for the Job Matching and\n external Company Matching endpoints. Additionally, this filter is also\n supported for the Search and Similar endpoints of Employee, Vacancy, and\n external Company.\n\n### August 2021\n\n- The Employability metric now takes into account the supply of Employees that\n could fill in the demand as well.\n- The Search endpoints now support an optional `language` query parameter, to\n indicate the language of the input text.\n\n### July 2021\n\n- `companies/:external_id/desired_functions` now supports the `PUT` method.\n Calling this method replaces all existing desired function Vacancies with the\n new set.\n- Similar Entity endpoints now support `score_min_threshold`.\n- Similar Entity endpoints now support Custom Property filters.\n- Similar Entity endpoints for Employees and Vacancies now support location and\n language based filters.\n- Similar Entity endpoints now support Custom Property weights.\n- Similar Entity endpoints for Employees and Vacancies now support location\n weight.\n\n### June 2021\n\n- Add the option to override the location used for geo-distance calculation in\n matching request filters.\n- `max_geo_distance` field on Employee entities was deprecated.\n- remove `max_geo_distance` field on Employee entities.\n\n### May 2021\n\n- You can now use a Vacancy-prefix when looking for matching external Companies\n such that filtering and weighting is based on the Custom Properties of the\n Vacancies associated with the external company, rather than the external\n company itself.\n\n### April 2021\n\n- Add strict parameter to entity creation and update operations (Employees,\n Competencies, Courses, Documents, Occupations, Vacancies).\n- Change the outward facing side of (non-)desired functions during Employee\n creation. Output and input now better reflect internal results.\n- Add languages field to external Companies.\n- You can now add a geo distance weight to the matching endpoints. Match scores\n are increased when two entities are in proximity to each other.\n- You can now add Custom Property weights to the matching endpoints. Match\n scores are increased when the applied condition on the matching entities'\n specified Custom Property checks out.\n- Extraction language can now be specified for the POST\n `companies/{external_id}/desired_functions` endpoint.\n\n### March 2021\n\n- You can now specify the non-desired functions when creating or updating an\n Employee to take their negative preference into account when matching to new\n positions.\n- You can now modify the non-desired functions boost used during matching by\n setting the appropriate weight on the match endpoints\n `employees/{external_id}/matching_vacancies` and\n `vacancies/{external_id}/matching_employees`.\n- You can now submit multiple desired functions linked to a given External\n Company through a single multiline string using the new\n `request_format=free_text` query parameter on the\n `/companies/{external_id}/desired_functions` endpoint.\n- You can now submit free text, multiline strings desired functions &\n non-desired functions for an Employee through the `desired_functions` &\n `non_desired_functions` attributes.\n- You can now search for Vacancies and external Companies based on free text,\n through the endpoints `/vacancies/search` and `/companies/search`.\n- You can now add datetime-typed Custom Properties.\n- You can now provide a list of filters when searching for entities using free\n text through the endpoints `/employees/search`, `/vacancies/search` and\n `/companies/search`.\n- You can now provide multiple values (as a list) when using the\n `custom_property_contains_element` filter. Entities will not be filtered out\n if they contain at least one of the provided values in the list Custom\n Property.\n- You can now specify the comparison operator when using the `custom_property`\n filter. If no operator is specified, the filter defaults to the `equals`\n operator.\n- You can now specify an offset on matching endpoints for `employees`\n ,`vacancies` and `companies`.\n- You can now specify an offset on search endpoints for `employees`,`vacancies`\n and `companies`.\n- You can now pass the `null` value for optional fields during creation and\n updating of all entities. Passing the `null` value during an update will unset\n the entity's attribute. Objects will be unset as `null`, arrays as the empty\n array `[]` and strings as the empty string `''`.\n- External Companies now support Custom Properties.\n- (Non-)desired function score boosting is now calculated relative to the\n relevancy of the function title, instead of a binary boost on occurrence of a\n title.\n- You can now provide a list of filters at the match endpoints\n `employees/{external_id}/matching_companies` and\n `companies/{external_id}/matching_employees`. This will be used to filter out\n entities that do not need to be considered during matching.\n- You can now provide a list of weights at the match endpoints\n `employees/{external_id}/matching_companies` and\n `companies/{external_id}/matching_employees`. The weights can override some\n default weights during matching (e.g. desired functions boost).\n- Custom Property definitions are no longer allowed to contain double\n underscores in their name.\n- You can now set the weight of the skills-related match component contributing\n to the final match score (this was previously hard-coded to 1.0).\n- You can now filter on the Custom Properties of External Companies linked to a\n Vacancy, when matching Employees to Vacancies and vice versa.\n\n### February 2021\n\n- You can now search for Employees based on free text, through the endpoint\n `/employees/search`.\n- You can add an (optional) External Company link to a Vacancy, through the\n endpoint `/vacancies` and attribute `company`.\n- You can now list, create, retrieve, update and delete External Companies\n through the endpoints `/companies/*`.\n- You can now optionally mark Vacancies as inactive using the field `active`.\n When this is field has the value `false`, the Vacancy will not be used for\n matching.\n- Deleting External Companies now deletes all linked inactive Vacancies in\n cascade.\n- You can now find the best Employees for a given External Company with an\n overview of its matching Vacancies, through the endpoint\n `/companies/{external_id}/matching_employees`.\n- You can now find the best External Companies for a given Employee with an\n overview of the matching Vacancies per External Company, through the endpoint\n `/employees/{external_id}/matching_companies`.\n- You can now upload desired functions as inactive Vacancies linked to a given\n External Company, through the endpoint\n `/companies/{external_id}/desired_functions`.\n- You can now see when an entity was last updated by checking the attribute\n `last_updated` upon entity retrieval.\n- You can now provide a list of filters at the match endpoints\n `employees/{external_id}/matching_vacancies` and\n `vacancies/{external_id}/matching_employees`. This will be used to filter out\n entities that do not need to be considered during matching.\n- You can now provide a list of languages with proficiency levels during Vacancy\n creation.\n- You can now provide a list of weights at the match endpoints\n `employees/{external_id}/matching_vacancies` and\n `vacancies/{external_id}/matching_employees`. The weights can override some\n default weights during matching (e.g. desired functions boost).\n- The POST-type methods on `matching_vacancies` and `matching_employees` are now\n the preferred way to request the matches.\n- You can now add a list of strings as a Custom Property.\n- You can now explicitly provide the language used in Skill Profile extraction\n during entity creation/update using the `language` query parameter. Supported\n languages are `auto`, `nl`, `fr` and `en`.\n- You can now optionally add a Job description to the entries in the\n working_history of an Employee. These descriptions will also be used for Skill\n extraction.\n\n### January 2021\n\n- You can add a (optional) `max_geo_distance` attribute when creating an\n Employee through the endpoint `/employees`. This is used for matching if there\n is no `max_geo_distance`. provided as query parameter. The default distance in\n our system when nothing is provided, is 50 km.\n"
},
{
"name": "Authentication",
"description": ""
},
{
"name": "Introduction",
"description": ""
},
{
"name": "Version"
},
{
"name": "Filters",
"description": "A crucial aspect of the configurability of matchmaking inside Skill Engine API\nis the use of _filters_. You can see filters as hard constraints that are\napplied prior to the calculation of any Skills based match. The filters\navailable for a matching endpoint are described in the specification of this\nendpoint, but for further clarification, this section provides a more complete\noverview.\n\nFilters can apply to one side of the matching equation, or can use both. In the\nlatter case, we distinguish between the **source entity** (the one you are\nsearching matches for) and the **target entities** (the ones you are searching\nfor matches within). For example, if you request matches on\n`/vacancies/{vid}/matching_employees`, then the source entity is the Vacancy\nwith external_id `vid`, while the target entities consist of all Employees\ntogether.\n\n## Single Entity Filters\n\nSingle entity filters are always applied to the target entities, irrespective of\nthe properties of the source entity.\n\n### Custom Property Comparison\n\nThe `custom_property` filter is one of the base building blocks for filtering in\nSkill Engine API. It filters the target entities using a value you provide\ninside the filter itself, and supports equality as well as a range of greater\nthan / less than varieties. To know if you've applied the filter in the right\ndirection, it's good to phrase it as: \"I want to receive all entities that have\na `property_name` that is `operator` to/than `property_value`\". For example, the\nfilter below results in all entities that have a `wage` Custom Property above\n`3000`.\n\n```json\n{\n \"filter\": \"custom_property\",\n \"property_name\": \"wage\",\n \"property_value\": \"3000\",\n \"operator\": \"gt\"\n}\n```\n\nWhen looking for matching vacancies, you can use the prefix `company__` before\nthe actual property name to apply the filter on the Custom Properties of the\nexternal company linked to the Vacancy, rather than on the Custom Properties of\nthe Vacancies itself. For example if you only want the Vacancies linked to\nexternal Companies that allow telework, the filter would like this:\n\n```json\n{\n \"filter\": \"custom_property\",\n \"property_name\": \"company__telework_policy\",\n \"property_value\": \"allowed\"\n}\n```\n\nWhen looking for matching external companies, the prefix `vacancy__` can be used\nbefore the actual value of `property_name` to apply the filtering to the Custom\nProperties associated to the Vacancies linked to the external Companies instead\nthe external Companies itself.\n\n### Custom Property Contains Element\n\nThe `custom_property_contains_element` can be applied to `list[text]` type\nCustom Properties, and selects those entities for which the Custom Property\nvalue contains the supplied `property_value`. For example, the filter below\ncould be used in a situation where Employees indicate the industries they want\nto work in -- in that case, the filter selects only the Employees that want to\nwork in `electronics`.\n\n```json\n{\n \"filter\": \"custom_property_contains_element\",\n \"property_name\": \"industries\",\n \"property_value\": \"electronics\"\n}\n```\n\nIf you want to require the Custom Property value to contain multiple different\nelements, you can simply append more filters, which will create the desired\neffect. If you want to filter for entities containing one or more of multiple\nelements, you can supply a list of options instead of just one value. To update\nour example from above, the filter below selects Employees that want to work in\n`electronics`, `chemicals` or both.\n\n```json\n{\n \"filter\": \"custom_property_contains_element\",\n \"property_name\": \"industries\",\n \"property_value\": [\"electronics\", \"chemicals\"]\n}\n```\n\nWhen looking for matching vacancies, you can use the prefix `company__` before\nthe actual property name to apply the filter on the Custom Properties of the\nexternal company linked to the Vacancy, rather than on the Custom Properties of\nthe Vacancies itself. For the example above this would become\n`company__industries` .\n\nWhen looking for matching external companies, the prefix `vacancy__` can be used\nbefore the actual value of `property_name` to apply the filtering to the Custom\nProperties associated to the Vacancies linked to the external Companies instead\nthe external Companies itself.\n\n### Custom Property Is In List\n\nIn similar fashion to the contains element filter, the\n`custom_property_is_in_list` filter selects entities for which (non-list) Custom\nProperty `property_name` is contained in the passed list of `possible_values`.\nFor example, if you're looking for an Employee that wants to work either full\ntime or part time, you might submit a filter similar to the one below:\n\n```json\n{\n \"filter\": \"custom_property_is_in_list\",\n \"property_name\": \"possible_work_regimes\",\n \"possible_values\": [\"fulltime\", \"parttime\"]\n}\n```\n\nWhen looking for matching vacancies, you can use the prefix `company__` before\nthe actual property name to apply the filter on the Custom Properties of the\nexternal company linked to the Vacancy, rather than on the Custom Properties of\nthe Vacancies itself. For the example above this would become\n`company__possible_work_regimes`.\n\nWhen looking for matching external companies, the prefix `vacancy__` can be used\nbefore the actual value of `property_name` to apply the filtering to the Custom\nProperties associated to the Vacancies linked to the external Companies instead\nthe external Companies itself.\n\n### External ID is in List\n\nThis filter allows explicit filtering on external IDs of the target entities.\nAny entity not mentioned in the list is excluded.\n\n```json\n{\n \"filter\": \"external_id_is_in_list\",\n \"external_ids\": [\"external_id_1\", \"external_id_2\", \"external_id_3\"]\n}\n```\n\n## Entity Relation Filters\n\nEntity relation filters filter the target entities using some relation they may\nor may not have with the source entity.\n\n### Geo Distance\n\nThis rather simple filter allows you to filter the target entities based on\ntheir distance from the source entity. The distance is expressed in kilometers,\nand calculated in a straight line between the two points. If the source entity\nhas no `location` set, this filter will not have any effect. If the source\nentity does have a location, then target entities without a location will not be\nconsidered. If no geo distance filter is provided, Employee/Vacancy matching\ndefaults to a range of 50km.\n\n```json\n{\n \"filter\": \"max_geo_distance\",\n \"max_geo_distance\": 50\n}\n```\n\n### Language\n\nThe `language` filter allows you to determine how language requirements are\nhandled when matching between Employees and Vacancies. As each language\nindicated on either of these entity types also has a level, you can tune the\nstrictness of this filter by modifying `max_underqualification` and\n`max_overqualification`. These respective values indicate how many levels below\nor above the languages in the source entity those in the target entities are\nallowed to be. Checking is only done for languages present in the source entity,\nso in case of an empty `languages` attribute on the source side, this filter\nwill not have any effect. If `max_underqualification` is equal or greater than\nthe level of one or more languages for the source entity, target entities that\ndo not mention this language will also be considered valid combinations with it.\n\n```json\n{\n \"filter\": \"language\",\n \"max_overqualification\": 2,\n \"max_underqualification\": 1\n}\n```\n\n### Custom Property Equal\n\nThe `custom_property_equal` filter simply checks for equality between properties\non the source and target entities. By providing the name of the property to be\nused on the source side as `from_entity_property` and the one on the target side\nas `to_entity_property`, you can flexibly choose which Custom Properties to use.\n\n```json\n{\n \"filter\": \"custom_property_equal\",\n \"from_entity_property\": \"employment_type\",\n \"to_entity_property\": \"employment_type\"\n}\n```\n\nWhen the filtering is applied to vacancies, either as `from_entity` or as\n`to_entity`, you can use the prefix `company__` before the actual value of\n`from_entity_property` or `to_entity_property` to apply the filtering on the\nCustom Properties of the external company linked to the Vacancy rather than the\nVacancy itself.\n\nWhen the filtering is applied to external Companies as `to_entity`, the prefix\n`vacancy__` can be used before the actual value of `to_entity_property` to apply\nthe filtering to the Custom Properties associated to the Vacancies linked to the\nexternal Companies instead the external Companies itself.\n\n### Custom Property Contains\n\nThe `custom_property_contains` filter is very similar to the\n`custom_property_equal` filter, but instead works with a `list[text]` and `text`\nproperty, checking whether one contains the other. Specifically, this filter\nselects the target entities for which the value of `to_entity_property` is a\npart of the `from_entity_property` (which must be a list type) of the source\nentity. The example below reflects the scenario where an Employee might indicate\nin which countries they want to work, so that only Vacancies in one of these\ncountries can be returned. If the Custom Property is not set for the source\nentity, the filter has no effect. If the target entities lack the\n`to_entity_property`, they are ignored.\n\n```json\n{\n \"filter\": \"custom_property_contains\",\n \"from_entity_property\": \"allowed_countries\",\n \"to_entity_property\": \"country\"\n}\n```\n\nWhen the filtering is applied to vacancies, either as `from_entity` or as\n`to_entity`, you can use the prefix `company__` before the actual value of\n`from_entity_property` or `to_entity_property` to apply the filtering on the\nCustom Properties of the external company linked to the Vacancy rather than the\nVacancy itself.\n\nWhen the filtering is applied to external Companies as `to_entity`, the prefix\n`vacancy__` can be used before the actual value of `to_entity_property` to apply\nthe filtering to the Custom Properties associated to the Vacancies linked to the\nexternal Companies instead the external Companies itself.\n\n### Custom Property Is In\n\nThe `custom_property_is_in` filter is the mirror image of the\n`custom_property_contains` filter. If you apply one type in fetching Vacancies\nfor a given Employee, then you can transform it into the other to have the\nequivalent constraint while fetching Employees for a given Vacancy. The example\nbelow reflects the transformed version of the example given for the contains\nfilter above.\n\n```json\n{\n \"filter\": \"custom_property_is_in\",\n \"from_entity_property\": \"country\",\n \"to_entity_property\": \"allowed_countries\"\n}\n```\n\nWhen the filtering is applied to vacancies, either as `from_entity` or as\n`to_entity`, you can use the prefix `company__` before the actual value of\n`from_entity_property` or `to_entity_property` to apply the filtering on the\nCustom Properties of the external company linked to the Vacancy rather than the\nVacancy itself.\n\nWhen the filtering is applied to external Companies as `to_entity`, the prefix\n`vacancy__` can be used before the actual value of `to_entity_property` to apply\nthe filtering to the Custom Properties associated to the Vacancies linked to the\nexternal Companies instead of the external Companies themselves.\n\n### Custom Property List Overlap\n\nThe `custom_property_list_overlap` filter checks for overlap between two\n`list[text]` Custom Properties. Specifically, this filter selects the target\nentities for which at least one of the values in `to_entity_property` (which\nmust be a list type) is contained in `from_entity_property` of the source\nentity. The example below shows a scenario in which an Employee might indicate\nin which industries they want to be involved, such that only Vacancies that are\nlinked to one of these industries will be returned. If the Custom Property is\nnot set for the source entity, the filter has no effect. Target entities that\nlack the `to_entity_property` property are excluded.\n\n```json\n{\n \"filter\": \"custom_property_list_overlap\",\n \"from_entity_property\": \"desired_industries\",\n \"to_entity_property\": \"industries\"\n}\n```\n\nWhen the filtering is applied to Vacancies, either as `from_entity` or as\n`to_entity`, you can use the prefix `company__` before the actual value of\n`from_entity_property` or `to_entity_property` to apply the filtering on the\nCustom Properties of the External Company linked to the Vacancy rather than the\nVacancy itself.\n\nWhen the filtering is applied to External Companies as `to_entity`, the prefix\n`vacancy__` can be used before the actual value of `to_entity_property` to apply\nthe filtering to the Custom Properties associated to the Vacancies linked to the\nExternal Companies instead the External Companies themselves.\n\n### Last Updated\n\nThe `last_updated` filter allows you to filter the target entities based on\n`last_updated` property. The filter supports a range of greater than / less than\nvarieties.\n\n```json\n{\n \"filter\": \"last_updated\",\n \"operator\": \"gt, gte, lt, lte\",\n \"value\": \"datetime\"\n}\n```\n\n### Last Updated With Taxonomy Change\n\nThe `last_updated_with_taxonomy_change` filter checks if a Taxonomy change took\nplace within the constraints of the filter. If that it the case, all target\nentities are returned, as all can be affected by a Taxonomy change. If no\nTaxonomy change took place, the filter operates like a `last_updated` filter.\n\n```json\n{\n \"filter\": \"last_updated_with_taxonomy_change\",\n \"operator\": \"gt, gte, lt, lte\",\n \"value\": \"datetime\"\n}\n```\n"
},
{
"name": "CustomPropertiesDefinitions",
"x-displayName": "Definitions",
"description": "Custom Properties within the Skill Engine API offer users the capability to\nfinely customize attributes for a wide array of entities, including:\n\n- [taxonomy/domains](/reference/latest/Taxonomy/TaxonomyDomains)\n- [taxonomy/subdomains](/reference/latest/Taxonomy/TaxonomySubdomains)\n- [taxonomy/skill_clusters](/reference/latest/Taxonomy/TaxonomySkillClusters)\n- [taxonomy/skills](/reference/latest/Taxonomy/TaxonomySkills)\n- [employees](/reference/latest/Employees)\n- [organisational_units]()\n- [job_architecture/job_families]()\n- [job_architecture/jobs](/reference/latest/Jobs)\n- [vacancies](/reference/latest/Vacancies)\n- [courses](/reference/latest/Courses)\n- [skill_clusters]()\n- [companies]()\n\nMore info about entities can be found on the\n[How it Works page](/technology/entities/).\n"
},
{
"name": "CustomPropertiesProperties",
"x-displayName": "Properties"
},
{
"name": "TasksCRUD",
"x-displayName": "CRUD"
},
{
"name": "TaskSearch",
"x-displayName": "Task search"
},
{
"name": "TaskValidation",
"x-displayName": "Task validation"
},
{
"name": "ExportTasks",
"x-displayName": "Tasks"
},
{
"name": "JobTaskProfile",
"x-displayName": "Task Profile"
}
],
"paths": {
"/employees": {
"get": {
"tags": [
"EmployeeCRUD"
],
"summary": "List Employees",
"description": "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.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
},
{
"in": "query",
"name": "organisational_unit",
"schema": {
"type": "string",
"example": "c3903505-eb84-42dc-a79f-5d8b1fe897b7"
},
"description": "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."
},
{
"in": "query",
"name": "low_data_availability",
"schema": {
"type": "boolean",
"example": true
},
"description": "This parameter can be used to only include entities for which sufficient data is available (`low_data_availability=false`) or is not available (`low_data_availability=true`) for qualitative Skill inference. If the parameter is not set, all entities will be included."
},
{
"in": "query",
"name": "skill_id",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"description": "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."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to use when passing the `skill_id` query parameter. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Employee objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Employees",
"description": "Subset of Employees starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"type": "object",
"required": [
"last_updated"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"location": {
"lat": 50.0216707,
"lng": 3.6887328
},
"assigned_position": "HR assistant",
"low_data_availability": true,
"organisational_unit": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"last_updated": "2021-01-21T17:32:28Z"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"active": true,
"location": {
"lat": 51.0216707,
"lng": 2.6887328
},
"assigned_position": "Staffing coordinator",
"low_data_availability": false,
"organisational_unit": "7a9f3d72-36b4-4b39-87a2-3df1540ebf9e",
"last_updated": "2021-01-22T15:02:00Z"
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"active": true,
"location": {
"lat": 51.0516707,
"lng": 4.6887328
},
"assigned_position": "HR analyst",
"low_data_availability": false,
"organisational_unit": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"last_updated": "2021-01-21T17:46:29Z"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"EmployeeCRUD"
],
"summary": "Create Employee",
"description": "Submit new Employee information to initialise their Skill Profile inside the Skill Engine API.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
},
{
"in": "query",
"name": "restore",
"schema": {
"type": "boolean",
"default": false
},
"description": "When set to `true`, this parameter restores soft-deleted Employees if the tenant has a configured grace period. If additional fields are provided alongside the `external_id`, the request acts as a restore followed by an update. If the Employee is not soft-deleted, the parameter is ignored and the normal creation flow applies."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position. Only one of `assigned_position` or `assigned_position_id` should be provided upon creation or update. Note that setting `assigned_position` instead of `assigned_position_id` does not provide Skill Profile data, as there is no link to a Job entity."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`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.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
}
]
},
{
"type": "object",
"description": "Employee information to submit for processing by the system.",
"properties": {
"location": {
"description": "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).",
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"employee_documents": {
"type": "array",
"nullable": true,
"description": "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.",
"items": {
"type": "object",
"description": "Base64 encoded CV of the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
}
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created Employee. Please note that this is a different field from the geographic location of the Employee.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Entity Limit",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "Creation has failed because you've reached the entity limit 100. You need to delete other entities to be able to create more."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Organisational Unit Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown organisational_unit for this resource. This Organisational Unit does not exist yet."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"EmployeeCRUD"
],
"summary": "Get Employee",
"description": "Get the Employee information stored inside the system. As resumes are not stored inside our system, they are not returned in this call.",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`external_id` of the Job the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
}
]
},
{
"title": "AttributeInclude",
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
}
],
"example": [
{
"property_name": "creation_date",
"property_value": "2020-03-07"
},
{
"property_name": "language",
"property_value": "de"
}
]
}
}
},
{
"type": "object",
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"EmployeeCRUD"
],
"summary": "Update Employee",
"description": "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.\n\nSince 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.\n\nPassing the `null` value removes non-required attributes. Object attributes will be removed when passing `null`, arrays with `[]` and strings with the empty string `''`.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating Employee data.",
"allOf": [
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position. Only one of `assigned_position` or `assigned_position_id` should be provided upon creation or update. Note that setting `assigned_position` instead of `assigned_position_id` does not provide Skill Profile data, as there is no link to a Job entity."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`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.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
},
{
"type": "object",
"description": "Employee information to submit for processing by the system.",
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"employee_documents": {
"type": "array",
"description": "List of base64 encoded documents (e.g. CVs) related to the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.",
"items": {
"type": "object",
"description": "Base64 encoded CV of the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
}
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
},
{
"title": "Organisational Unit Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown organisational_unit for this resource. This Organisational Unit does not exist yet."
}
]
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"EmployeeCRUD"
],
"summary": "Delete Employee",
"description": "Remove an Employee from the system. This step deletes all information linked exclusively to this Employee. By deleting an Employee, you delete their Skill Profile history, which cannot be recreated or recovered afterwards.\n\nIf grace periods are enabled, Employees are soft deleted and will only be permanently deleted after their grace period ends. During the grace period, soft deleted Employees can be restored by adding the `restore=true` parameter to the create endpoint. This restores the Employee to the state before deletion.",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}/skill_profile": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"EmployeeProfile"
],
"summary": "Get the Skill Profile for an Employee",
"description": "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!",
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"skill_clusters",
"domains",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes and has no effect when `response_format` is set to `domains` or `skill_clusters`.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sources",
"low_data_availability_flag",
"self_rated_proficiency_level",
"self_rated_proficiency_float",
"inferred_proficiency_level",
"inferred_proficiency_float",
"properties",
"skill_source"
]
},
"example": [
"sources"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant, and is not supported when `response_format` is set to `domains` or `skill_clusters`.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "output_skills_sorting",
"required": false,
"description": "Defines the sorting of the Skills in the returned Skill Profile. When set to `alphabetical`, Skills are sorted by name. When set to `confidence`, Skills are sorted by decreasing confidence score.",
"example": "alphabetical",
"schema": {
"type": "string",
"default": "alphabetical",
"enum": [
"alphabetical",
"confidence"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result returned. The profile consists of a list of Skills and their validation states.",
"type": "object",
"required": [
"external_id",
"num_skill_events",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"num_skill_events": {
"type": "integer",
"minimum": 0,
"example": 5,
"description": "The amount of Skill Events an Employee has."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"domains"
],
"properties": {
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
},
{
"title": "Skill Clusters",
"description": "The Skill Profile in Skill Cluster format. The profile consists of a list of Skill Clusters with scores, with each score representing the importance of the Skill Cluster at hand.",
"type": "object",
"required": [
"external_id",
"num_skill_events",
"skill_clusters"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"num_skill_events": {
"type": "integer",
"minimum": 0,
"example": 5,
"description": "The amount of Skill Events an Employee has."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"skill_clusters": {
"type": "array",
"description": "The Skill Clusters contained in this profile, along with their proficiency levels.",
"items": {
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"domain_name",
"proficiency_level",
"validation_state"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"description": "ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "Name of the Skill Cluster."
},
"domain_name": {
"type": "string",
"description": "The name of the Domain associated with this Skill Cluster."
},
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain associated with this Skill Cluster. This field is only applicable in a 4-level Taxonomy."
},
"proficiency_level": {
"type": "integer",
"minimum": 0,
"maximum": 3,
"description": "Proficiency level of the entity in this Skill Cluster."
},
"validation_state": {
"type": "string",
"description": "This field indicates whether this Skill Cluster is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"validated",
"suggested"
]
},
"current_skills": {
"type": "array",
"description": "The Skills of the Skill Cluster that are also in the Skills of the entity.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_name",
"validation_state",
"skill_id"
],
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
}
}
}
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skills were inferred in the Skill Cluster.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
}
}
},
"example": [
{
"skill_cluster_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skill_cluster_name": "Programming Languages",
"domain_name": "Computer Science",
"proficiency_level": 2,
"validation_state": "suggested",
"current_skills": [
{
"skill_name": "Python",
"validation_state": "suggested",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"skill_sources": [
"working_history"
]
},
{
"skill_name": "Java",
"validation_state": "suggested",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"skill_sources": [
"working_history",
"skill_profile_feedback"
]
}
],
"sources": [
"working_history",
"skill_profile_feedback"
]
},
{
"skill_cluster_id": "24180a01-f202-4c43-8a79-0721a1d46ec2",
"skill_cluster_name": "DevOps",
"domain_name": "Computer Science",
"proficiency_level": 3,
"validation_state": "validated",
"current_skills": [
{
"skill_name": "GitLab",
"validation_state": "suggested",
"skill_id": "72dec06b-8614-4930-b296-d7596fd9fd7b",
"skill_sources": [
"working_history"
]
},
{
"skill_name": "Jenkins",
"validation_state": "suggested",
"skill_id": "eebcf485-9045-4669-a6f7-6e7faa465ff9",
"skill_sources": [
"working_history"
]
},
{
"skill_name": "Kubernetes",
"validation_state": "validated",
"skill_id": "94835c7e-4135-40d7-aea6-165b33d01589",
"skill_sources": [
"education_history"
]
}
],
"sources": [
"education_history",
"working_history"
]
}
]
}
}
},
{
"title": "Domains",
"description": "The Skill Profile in Domain format. The profile consists of a list of domains with the Skills belonging to them, and a percentage representing the size of the share of the Skill Profile the Domain represents.",
"type": "object",
"required": [
"external_id",
"num_skill_events",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"num_skill_events": {
"type": "integer",
"minimum": 0,
"example": 5,
"description": "The amount of Skill Events an Employee has."
},
"domains": {
"type": "array",
"description": "The Domains contained in this profile along with the Skills belonging to them, and a percentage representing the size of the share of the Skill Profile the Domain represents.",
"items": {
"type": "object",
"required": [
"name",
"percentage",
"skills"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"example": "Computer Science",
"description": "The name of the Domain."
},
"percentage": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The size of the share of the entire Skill Profile that the Domain represents.",
"example": 0.75
},
"skills": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
},
"description": "The list of Skills from the Skill Profile belonging to the corresponding Domain.",
"example": [
"Python",
"Java",
"Programming"
]
},
"skill_dicts": {
"type": "array",
"items": {
"type": "object",
"description": "A Skill in the Domain.",
"required": [
"skill_name",
"uuid"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the Skill."
},
"uuid": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
"description": "The list of Skills from the Skill Profile belonging to the corresponding Domain.",
"example": [
{
"skill_name": "Python",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
}
]
}
}
},
"example": [
{
"name": "Computer Science",
"percentage": 0.75,
"skills": [
"Python",
"Java",
"Programming"
],
"skill_dicts": [
{
"skill_name": "Python",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
},
{
"skill_name": "Java",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
},
{
"skill_name": "Programming",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
}
]
},
{
"name": "Interpersonal Skills",
"percentage": 0.25,
"skills": [
"Presenting to management"
],
"skill_dicts": [
{
"skill_name": "Presenting to management",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
}
]
}
]
}
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"num_skill_events": 5,
"low_data_availability": false,
"skills": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"validation_state": "suggested",
"sources": [
"working_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "working_history",
"source": "workday"
}
],
"self_rated_proficiency_level": null,
"self_rated_proficiency_float": null,
"inferred_proficiency_level": 2,
"inferred_proficiency_float": 0.4
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"validation_state": "validated",
"sources": [
"education_history",
"working_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "education_history",
"source": "workday"
},
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "working_history",
"source": "workday"
}
],
"self_rated_proficiency_level": 2,
"self_rated_proficiency_float": 0.4,
"inferred_proficiency_level": 3,
"inferred_proficiency_float": 0.6
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"validation_state": "suggested",
"sources": [
"education_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "education_history",
"source": "workday"
}
],
"self_rated_proficiency_level": null,
"self_rated_proficiency_float": null,
"inferred_proficiency_level": null,
"inferred_proficiency_float": null
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested"
}
]
}
},
"skillClustersExample": {
"summary": "Skill Clusters",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"num_skill_events": 5,
"low_data_availability": false,
"skill_clusters": [
{
"skill_cluster_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skill_cluster_name": "Programming Languages",
"domain_name": "Computer Science",
"proficiency_level": 2,
"validation_state": "suggested",
"current_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested",
"skill_sources": [
"working_history"
]
},
{
"skill_name": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_sources": [
"working_history",
"skill_profile_feedback"
]
}
],
"sources": [
"working_history",
"skill_profile_feedback"
]
},
{
"skill_cluster_id": "24180a01-f202-4c43-8a79-0721a1d46ec2",
"skill_cluster_name": "DevOps",
"domain_name": "Computer Science",
"proficiency_level": 3,
"validation_state": "validated",
"current_skills": [
{
"skill_name": "GitLab",
"skill_id": "72dec06b-8614-4930-b296-d7596fd9fd7b",
"validation_state": "suggested",
"skill_sources": [
"working_history"
]
},
{
"skill_name": "Jenkins",
"skill_id": "eebcf485-9045-4669-a6f7-6e7faa465ff9",
"validation_state": "suggested",
"skill_sources": [
"working_history"
]
},
{
"skill_name": "Kubernetes",
"skill_id": "94835c7e-4135-40d7-aea6-165b33d01589",
"validation_state": "validated",
"skill_sources": [
"education_history"
]
}
],
"sources": [
"education_history",
"working_history"
]
}
]
}
},
"domainsExample": {
"summary": "Domains",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"num_skill_events": 5,
"low_data_availability": false,
"domains": [
{
"name": "Computer Science",
"percentage": 0.75,
"skills": [
"Python",
"Java",
"Programming"
],
"skill_dicts": [
{
"skill_name": "Python",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
},
{
"skill_name": "Java",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
},
{
"skill_name": "Programming",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
}
]
},
{
"name": "Interpersonal Skills",
"percentage": 0.25,
"skills": [
"Presenting to management"
],
"skill_dicts": [
{
"skill_name": "Presenting to management",
"uuid": "6b819e9c-f276-41fc-829b-fffcb848b1a9"
}
]
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"EmployeeProfile"
],
"summary": "Partially update an Employee Skill Profile with feedback",
"description": "Provide feedback about an existing Employee Skill Profile to update it inside\nthe system. When the `feedback_format` query parameter is `skills`,\nthe body of the feedback message overwrites, adds or updates Skills in the original profile.\nWhen the `feedback_format` query parameter is `skill_clusters`, this endpoint will change the Skill Cluster\nSkills in the Skill Profile to fit the given Skill Cluster proficiency level.\n",
"parameters": [
{
"in": "query",
"name": "feedback_format",
"required": false,
"description": "The format in which feedback for the Skill Profile is given.",
"schema": {
"type": "string",
"example": "skills",
"enum": [
"skills",
"external_vendor_skills",
"skill_clusters"
],
"default": "skills"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Either `skill` or `skill_id` must be provided, but not both.",
"items": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
},
"self_rated_proficiency_level": {
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency level from the Skill for this Employee. You can only set this for a Skill that is validated (`has_skill` should be `true`). `self_rated_proficiency_level` and `self_rated_proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"self_rated_proficiency_float": {
"description": "The self-rated proficiency (passed as a float) for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency from the Skill for this Employee. You can only set this for a Skill that is validated (`has_skill` should be `true`). `self_rated_proficiency_level` and `self_rated_proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
}
}
}
]
},
"example": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"has_skill": true
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"has_skill": true,
"self_rated_proficiency_level": 2
},
{
"skill_id": "a05c0764-3cde-9200-b6a4-dds7639987ff",
"has_skill": true,
"self_rated_proficiency_level": null
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"has_skill": false
}
]
}
}
},
{
"title": "External Vendor Skills",
"type": "object",
"properties": {
"source_vendor": {
"allOf": [
{
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
],
"description": "The external vendor's vocabulary in which feedback is provided. The vendor must be activated on the tenant for this to work."
},
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "workday"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Both the `skill` and the `skill_id` must be provided.",
"items": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill_id",
"has_skill"
],
"properties": {
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning (ML)",
"description": "The name of the Skill."
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
},
"self_rated_proficiency_level": {
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`).",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"self_rated_proficiency_float": {
"description": "The self-rated proficiency (passed as a float) for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `self_rated_proficiency_level` and `self_rated_proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
}
}
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "111-AAA",
"has_skill": true
},
{
"skill": "Python",
"skill_id": "111-BBB",
"has_skill": true,
"self_rated_proficiency_level": 2
},
{
"skill": "Tensorflow",
"skill_id": "111-CCC",
"has_skill": true,
"self_rated_proficiency_level": null
},
{
"skill": "Java",
"skill_id": "111-DDD",
"has_skill": false
}
]
}
}
},
{
"title": "Skill Clusters",
"description": "Update Skill Cluster profile with following body.",
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "workday"
},
"skill_clusters": {
"type": "array",
"description": "The Skill Clusters along with their proficiency levels. You should supply either a `skill_cluster_name` or a `skill_cluster_id`",
"items": {
"description": "Default structure for a Skill Cluster.",
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"example": "Programming",
"description": "The name of the Skill Cluster."
},
"skill_cluster_id": {
"type": "string",
"minLength": 1,
"example": "6b819e9c-f276-41fc-829b-fffcb848b1a9",
"description": "ID of the Skill Cluster"
},
"proficiency_level": {
"type": "number",
"format": "integer",
"minimum": 0,
"maximum": 3,
"description": "The proficiency level for this Skill Cluster, a level between 0 and 3.",
"example": 2
}
}
},
"example": [
{
"skill_cluster_name": "Programming"
},
{
"skill_cluster_name": "Business Intelligence",
"proficiency_level": 2
}
]
}
}
}
]
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Unrecognized Skill IDs Error",
"description": "Returned when `feedback_format` is `external_vendor_skills` and one or more submitted Skill IDs cannot be matched to a known Skill. The `skills` feedback format keeps its regular validation-error response and never includes `unrecognized_skill_ids`.",
"type": "object",
"required": [
"title",
"description",
"unrecognized_skill_ids"
],
"properties": {
"title": {
"type": "string",
"description": "Name of the error.",
"example": "400 Bad Request"
},
"description": {
"type": "string",
"description": "Human-readable message listing the Skill IDs that could not be matched and how to resolve it (retry without these IDs)."
},
"unrecognized_skill_ids": {
"type": "array",
"description": "The full set of submitted Skill IDs that could not be matched to a known Skill. Remove these IDs and retry the request.",
"items": {
"type": "string"
}
}
},
"example": {
"title": "400 Bad Request",
"description": "The following skill ids could not be matched to a known skill. They are likely vendor synonyms that are not stored as skills in SkillEngine: id1, id2. Retry the request without these skill ids.",
"unrecognized_skill_ids": [
"id1",
"id2"
]
}
}
]
},
"examples": {
"genericBadRequest": {
"summary": "Generic bad request (e.g. malformed body)",
"value": {
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
},
"unrecognizedSkillIds": {
"summary": "Unrecognized Skill IDs (`feedback_format=external_vendor_skills` only)",
"value": {
"title": "400 Bad Request",
"description": "The following skill ids could not be matched to a known skill. They are likely vendor synonyms that are not stored as skills in SkillEngine: id1, id2. Retry the request without these skill ids.",
"unrecognized_skill_ids": [
"id1",
"id2"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/metrics/count": {
"get": {
"tags": [
"EmployeeMetrics"
],
"summary": "Get Employee count",
"description": "Get the total number of Employee objects stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Employee"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Employee objects stored inside the system.",
"example": 1000
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/metrics/adoption_metrics": {
"post": {
"tags": [
"EmployeeMetrics"
],
"summary": "Get Employee adoption metrics",
"description": "Get adoption metrics across a collection of Employee objects stored in the system, aggregated over their Skills and your Taxonomy.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to use for the returned metrics. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of adoption metric queries. Each query corresponds with adoption metrics aggregated across the requested collection of objects.",
"required": [
"queries"
],
"properties": {
"queries": {
"type": "array",
"items": {
"type": "object",
"required": [
"query_id",
"filters"
],
"properties": {
"query_id": {
"type": "string",
"description": "A unique ID linked to the adoption metric query.",
"example": "query-id"
},
"filters": {
"type": "array",
"description": "Filters to be applied on the entities for which adoption metrics need to be aggregated. If left empty, the adoption metrics are aggregated across all entities stored in the system.",
"items": {
"anyOf": [
{
"allOf": [
{
"type": "object",
"required": [
"filter",
"attribute_name",
"operator",
"attribute_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter on all entities for which attribute `attribute_name` is equal to `attribute_value`. Possible values for `attribute_name` are stated below.",
"enum": [
"attribute"
],
"example": "attribute"
},
"attribute_name": {
"type": "string",
"description": "Name of the attribute on which the filter is applied."
},
"operator": {
"type": "string",
"description": "The type of operator to apply on the attribute `attribute_name`.",
"enum": [
"eq"
]
},
"attribute_value": {
"type": "string",
"description": "Value of the attribute `attribute_name`",
"example": "abc-123"
}
}
},
{
"type": "object",
"title": "attribute_equal",
"properties": {
"attribute_name": {
"enum": [
"organisational_unit"
]
}
}
}
]
},
{
"allOf": [
{
"type": "object",
"required": [
"filter",
"attribute_name",
"operator"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter on all entities for which attribute `attribute_name` is empty. Possible values for `attribute_name` are stated below.",
"enum": [
"attribute"
],
"example": "attribute"
},
"attribute_name": {
"type": "string",
"description": "Name of the attribute on which the filter is applied."
},
"operator": {
"type": "string",
"description": "The type of operator to apply on the attribute `attribute_name`.",
"enum": [
"is_empty"
]
}
}
},
{
"type": "object",
"title": "attribute_is_empty",
"properties": {
"attribute_name": {
"enum": [
"organisational_unit"
]
}
}
}
]
}
]
},
"minItems": 0,
"maxItems": 1
}
}
}
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Response structure for Organisational Unit Metrics. Metrics are expressed in the structure of your Taxonomy. When a Skill is not represented in the Taxonomy, it will be included in the \"Skills outside of the Taxonomy\" Domain.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"results"
],
"properties": {
"results": {
"title": "Organisational Unit Results",
"description": "A list of metrics related to each Organisational Unit.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "organisational_unit_metrics",
"required": [
"query_id",
"metrics"
],
"properties": {
"query_id": {
"type": "string",
"description": "The unique ID of the query."
},
"metrics": {
"title": "Metrics",
"description": "Aggregated statistics for the Organisational Unit, broken down by Domains, Skill Clusters, and Skills.",
"type": "object",
"required": [
"domains",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count",
"skills_outside_taxonomy",
"total_employee_skill_count"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains within the Organisational Unit.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"domain_name",
"external_id",
"skill_clusters",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The external ID of the Domain."
},
"skill_clusters": {
"title": "Skill Clusters",
"description": "A list of Skill Clusters within the Domain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"skills",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count"
],
"properties": {
"external_id": {
"type": "string",
"description": "The external ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"skills": {
"title": "Skills",
"description": "A list of Skills within the Skill Cluster.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_employee_count"
],
"properties": {
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees possessing this Skill."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
}
]
}
},
"skills_outside_taxonomy": {
"description": "A list of Skills not present in the Taxonomy.",
"properties": {
"skills": {
"title": "Skills",
"description": "A list of skills that are not present in the Taxonomy.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_employee_count"
],
"properties": {
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees possessing this Skill."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
},
"total_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
}
}
}
}
}
]
}
}
},
"example": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_employee_count": 10
}
],
"sum_employee_skill_count": 10,
"unique_employee_count": 10,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 10,
"unique_employee_count": 10,
"unique_skill_count": 1
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-2",
"skill_name": "Software Debugging",
"unique_employee_count": 5
}
],
"sum_employee_skill_count": 5,
"unique_employee_count": 5,
"unique_skill_count": 1
},
"sum_employee_skill_count": 15,
"unique_employee_count": 15,
"unique_skill_count": 2,
"total_employee_skill_count": 15
}
}
]
}
},
{
"description": "Response structure for Organisational Unit Metrics. Metrics are expressed in the structure of your Taxonomy. When a Skill is not represented in the Taxonomy, it will be included in the \"Skills outside of the Taxonomy\" Domain.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"results"
],
"properties": {
"results": {
"title": "Organisational Unit Results",
"description": "A list of metrics related to each Organisational Unit.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "organisational_unit_metrics",
"required": [
"query_id",
"metrics"
],
"properties": {
"query_id": {
"type": "string",
"description": "The unique ID of the query."
},
"metrics": {
"title": "Metrics",
"description": "Aggregated statistics for the Organisational Unit, broken down by Domains, Subdomains, Skill Clusters, and Skills.",
"type": "object",
"required": [
"domains",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count",
"skills_outside_taxonomy",
"total_employee_skill_count"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains within the Organisational Unit.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"domain_name",
"external_id",
"subdomains",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The external ID of the Domain."
},
"subdomains": {
"title": "Subdomains",
"description": "A list of Subdomains within the Domain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "subdomain_content",
"required": [
"subdomain_name",
"external_id",
"skill_clusters",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The external ID of the Subdomain."
},
"skill_clusters": {
"title": "Skill Clusters",
"description": "A list of Skill Clusters within the Subdomain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"skills",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count"
],
"properties": {
"external_id": {
"type": "string",
"description": "The external ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"skills": {
"title": "Skills",
"description": "A list of Skills within the Skill Cluster.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_employee_count"
],
"properties": {
"unique_employee_count": {
"type": "integer",
"description": "The count of unique Employees possessing this Skill."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
}
]
}
},
"skills_outside_taxonomy": {
"description": "A list of Skills not present in the Taxonomy.",
"properties": {
"skills": {
"title": "Skills",
"description": "A list of skills that are not present in the Taxonomy.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_employee_count"
],
"properties": {
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees possessing this Skill."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
}
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
},
"unique_employee_count": {
"type": "integer",
"description": "Number of distinct Employees with at least one Skill in this Taxonomy level."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Employees within this Taxonomy level."
},
"total_employee_skill_count": {
"type": "integer",
"description": "Total number of times Employees possess Skills within this Taxonomy level, counting each Skill even if an Employee has more than one."
}
}
}
}
}
]
}
}
},
"example": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"subdomains": [
{
"subdomain_name": "Software Development",
"external_id": "subdomain-001",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_employee_count": 125
}
],
"sum_employee_skill_count": 125,
"unique_employee_count": 125,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 125,
"unique_employee_count": 125,
"unique_skill_count": 1
},
{
"subdomain_name": "Data Management",
"external_id": "subdomain-002",
"skill_clusters": [
{
"external_id": "xyz-cluster",
"skill_cluster_name": "Data Engineering",
"skills": [
{
"skill_id": "xyz-skill-2",
"skill_name": "ETL Development",
"unique_employee_count": 30
}
],
"sum_employee_skill_count": 30,
"unique_employee_count": 30,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 30,
"unique_employee_count": 30,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 155,
"unique_employee_count": 130,
"unique_skill_count": 2
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-3",
"skill_name": "Software Debugging",
"unique_employee_count": 100
}
],
"sum_employee_skill_count": 100,
"unique_employee_count": 100,
"unique_skill_count": 1
},
"sum_employee_skill_count": 255,
"unique_employee_count": 150,
"unique_skill_count": 3,
"total_employee_skill_count": 255
}
}
]
}
},
{
"description": "Response structure for Organisational Unit Metrics when no Taxonomy is present. Metrics are grouped by Domains based on TechWolf Domain names, and Skills are directly nested under these Domains.",
"type": "object",
"title": "No Taxonomy",
"required": [
"results"
],
"properties": {
"results": {
"title": "Organisational Unit Results",
"description": "A list of metrics related to each Organisational Unit, grouped by Domains based on TechWolf classifications.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "organisational_unit_metrics",
"required": [
"query_id",
"metrics"
],
"properties": {
"external_id": {
"type": "string",
"description": "The unique ID of the query."
},
"metrics": {
"title": "Metrics",
"description": "Aggregated statistics for the Organisational Unit, grouped by TechWolf Domains, with Skills directly underneath each Domain.",
"type": "object",
"required": [
"domains",
"sum_employee_skill_count",
"unique_employee_count",
"unique_skill_count",
"total_employee_skill_count"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains, using TechWolf classifications, within the Organisational Unit.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"domain_name",
"skills",
"unique_employee_count",
"unique_skill_count",
"sum_employee_skill_count"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain, based on TechWolf classification."
},
"skills": {
"title": "Skills",
"description": "A list of Skills directly under the Domain.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_employee_count"
],
"properties": {
"unique_employee_count": {
"type": "integer",
"description": "The count of unique Employees using this Skill."
}
}
}
]
}
},
"unique_employee_count": {
"type": "integer",
"description": "The count of unique Employees in the Domain."
},
"unique_skill_count": {
"type": "integer",
"description": "The count of unique Skills in the Domain."
},
"sum_employee_skill_count": {
"type": "integer",
"description": "The total Employee skill count in the Domain."
}
}
}
]
}
},
"sum_employee_skill_count": {
"type": "integer",
"description": "Total Employee skill count across all Domains."
},
"unique_employee_count": {
"type": "integer",
"description": "Total count of unique Employees across all Domains."
},
"unique_skill_count": {
"type": "integer",
"description": "Total count of unique Skills across all Domains."
},
"total_employee_skill_count": {
"type": "integer",
"description": "Total Employee Skill count across all Domains. Skills that occur in multiple Skill Clusters are only counted once."
}
}
}
}
}
]
}
}
},
"example": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "TechWolf Domain",
"skills": [
{
"skill_id": "skill_1",
"skill_name": "Skill 1",
"unique_employee_count": 1
},
{
"skill_id": "skill_3",
"skill_name": "Skill 3",
"unique_employee_count": 5
}
],
"unique_employee_count": 6,
"unique_skill_count": 2,
"sum_employee_skill_count": 6
},
{
"domain_name": "TechWolf Domain 2",
"skills": [
{
"skill_id": "skill_4",
"skill_name": "Skill 4",
"unique_employee_count": 30
}
],
"unique_employee_count": 30,
"unique_skill_count": 1,
"sum_employee_skill_count": 30
}
],
"sum_employee_skill_count": 36,
"unique_employee_count": 36,
"unique_skill_count": 3,
"total_employee_skill_count": 36
}
}
]
}
}
]
},
"examples": {
"3levelTaxonomyExample": {
"summary": "3 Level Taxonomy",
"value": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_employee_count": 10
}
],
"sum_employee_skill_count": 10,
"unique_employee_count": 10,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 10,
"unique_employee_count": 10,
"unique_skill_count": 1
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-2",
"skill_name": "Software Debugging",
"unique_employee_count": 5
}
],
"sum_employee_skill_count": 5,
"unique_employee_count": 5,
"unique_skill_count": 1
},
"sum_employee_skill_count": 15,
"unique_employee_count": 15,
"unique_skill_count": 2,
"total_employee_skill_count": 15
}
}
]
}
},
"4levelTaxonomyExample": {
"summary": "4 Level Taxonomy",
"value": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"subdomains": [
{
"subdomain_name": "Software Development",
"external_id": "subdomain-001",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_employee_count": 125
}
],
"sum_employee_skill_count": 125,
"unique_employee_count": 125,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 125,
"unique_employee_count": 125,
"unique_skill_count": 1
},
{
"subdomain_name": "Data Management",
"external_id": "subdomain-002",
"skill_clusters": [
{
"external_id": "xyz-cluster",
"skill_cluster_name": "Data Engineering",
"skills": [
{
"skill_id": "xyz-skill-2",
"skill_name": "ETL Development",
"unique_employee_count": 30
}
],
"sum_employee_skill_count": 30,
"unique_employee_count": 30,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 30,
"unique_employee_count": 30,
"unique_skill_count": 1
}
],
"sum_employee_skill_count": 155,
"unique_employee_count": 130,
"unique_skill_count": 2
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-3",
"skill_name": "Software Debugging",
"unique_employee_count": 100
}
],
"sum_employee_skill_count": 100,
"unique_employee_count": 100,
"unique_skill_count": 1
},
"sum_employee_skill_count": 255,
"unique_employee_count": 150,
"unique_skill_count": 3,
"total_employee_skill_count": 255
}
}
]
}
},
"noTaxonomyExample": {
"summary": "No Taxonomy",
"value": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "TechWolf Domain",
"skills": [
{
"skill_id": "skill_1",
"skill_name": "Skill 1",
"unique_employee_count": 1
},
{
"skill_id": "skill_3",
"skill_name": "Skill 3",
"unique_employee_count": 5
}
],
"unique_employee_count": 6,
"unique_skill_count": 2,
"sum_employee_skill_count": 6
},
{
"domain_name": "TechWolf Domain 2",
"skills": [
{
"skill_id": "skill_4",
"skill_name": "Skill 4",
"unique_employee_count": 30
}
],
"unique_employee_count": 30,
"unique_skill_count": 1,
"sum_employee_skill_count": 30
}
],
"sum_employee_skill_count": 36,
"unique_employee_count": 36,
"unique_skill_count": 3,
"total_employee_skill_count": 36
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}/metrics/employability": {
"post": {
"tags": [
"EmployeeMetrics"
],
"summary": "Get the employability metric using filters and weights",
"description": "Retrieve the employability for this Employee. Employability is influenced by two factors: the number of matching Vacancies (demand) & the number of Employees that could fill those Vacancies (supply). It is reported as a number between 0 and 1, with the upper end indicating that an Employee has many matching opportunities (= high demand) for which there are not many matching Employees (= low supply). A lower score indicates fewer opportunities (= low demand), or that there is already a high supply of those profiles. Only active Vacancies and Employees are taken into account.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"description": "Filters to be applied during the calculation",
"properties": {
"employee_filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
}
},
"vacancy_filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
}
}
}
},
{
"type": "object",
"description": "List of weights to be applied during the calculation",
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for an entity metric",
"required": [
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"type": "object",
"required": [
"entity_type"
],
"properties": {
"entity_type": {
"type": "string",
"example": "Employee"
}
}
}
]
},
{
"type": "object",
"description": "A measure indicating the degree to which this Employee can find other opportunities within your available Vacancies, reported as a number between 0 and 1.",
"required": [
"metric_name",
"metric_value"
],
"properties": {
"metric_name": {
"type": "string",
"example": "configurable_employability"
},
"metric_value": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skill_event_types": {
"get": {
"tags": [
"SkillEvents"
],
"summary": "List the Skill Event types",
"description": "Returns every Skill Event type the tenant can send, with the content fields each one takes: `working_history`, `ticket`, … and, when they are enabled for the tenant, the business record types (`it_incident`, `support_ticket`, `technical_spec`, …). Contact TechWolf to enable the business record types.\n\nUse `data_type_id` as the `event_type` of a Skill Event and `record_schema` to build its `content`: every field marked `required` must be present, and no field outside `record_schema` is accepted. Every text field is used as context to infer the Employee's skills.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"skill_event_types"
],
"properties": {
"skill_event_types": {
"type": "array",
"items": {
"type": "object",
"required": [
"data_type_id",
"name",
"description",
"record_schema"
],
"properties": {
"data_type_id": {
"type": "string",
"description": "Identifier of the type; the value to send as `event_type` on a Skill Event.",
"example": "support_ticket"
},
"name": {
"type": "string",
"example": "support_ticket"
},
"description": {
"type": "string",
"example": "Support ticket — a request routed to an internal support team"
},
"record_schema": {
"type": "array",
"description": "The content fields this type takes. A Skill Event of this type must carry every `required` field and may carry the others; any other key is rejected.",
"items": {
"type": "object",
"required": [
"name",
"required"
],
"properties": {
"name": {
"type": "string",
"example": "summary"
},
"required": {
"type": "boolean",
"example": true
}
}
}
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
}
}
}
},
"/employees/{employee_external_id}/skill_events": {
"get": {
"tags": [
"SkillEvents"
],
"summary": "List Skill Events of an Employee by event type",
"description": "Get all Skill Events of a specified event type linked to an Employee.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "event_type",
"description": "Get only Skill Events of this type. Learn more about the Skill Event Types at [How it works](/technology/skill_events/). Multiple of these includes can be added to the request to get the Skill Events of multiple types.",
"required": false,
"schema": {
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"feedback",
"goal",
"project",
"ticket",
"certificate",
"skill_notes",
"skill_profile_feedback"
],
"example": "learning"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Skill Event type objects linked to the Employee.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Skill Events",
"description": "Subset of Skill Events starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure of a Skill Event.",
"type": "object",
"required": [
"external_id",
"event_type",
"timestamp",
"content"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique Skill Event ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"description": "Type of the Skill Event. Learn more about the Skill Event Types at [How it works](/technology/skill_events/). `GET /skill_event_types` lists the types available to your tenant and the content fields each one takes.",
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"feedback",
"goal",
"project",
"ticket",
"merge_request",
"certificate",
"skill_notes",
"skill_profile_feedback",
"it_incident",
"change_request",
"problem_record",
"service_request",
"hr_case",
"support_ticket",
"work_task",
"employee_recognition",
"customer_case",
"task",
"postmortem",
"deal_note",
"success_plan",
"audit_finding",
"work_order",
"technical_spec",
"technical_documentation",
"product_documentation",
"planning_document",
"process_document",
"meeting_notes",
"knowledge_article",
"performance_review",
"publication",
"patent"
],
"example": "working_history"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Employee is considered to have obtained the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source system of the Skill Event. This is used to keep track of where Skill Events originate from.",
"type": "string",
"format": "free text",
"example": "employee-archives"
},
"content": {
"description": "The content of the Skill Event. Each type of Skill Event has a different content. The content should align with the ``event_type``. Expanding this field shows you the supported Skill Event content bodies.",
"oneOf": [
{
"title": "working_history",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "HR Manager",
"description": "A formal title that describes the Job function."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning",
"description": "A more in depth description of the Job content."
}
}
},
{
"description": "Structure for Working history content by referencing a Job.",
"type": "object",
"title": "working_history_job",
"required": [
"job_id"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "education_history",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "Start date of the education (IS08601 format).",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"example": "Harvard University",
"description": "The institution responsible for the education."
},
"degree_name": {
"type": "string",
"minLength": 1,
"example": "Master in Human Resources Management",
"description": "A title or short description of the education."
}
}
},
{
"type": "object",
"title": "resume_document",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
],
"description": "States the standard media type of the file."
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1,
"description": "A base64 encoded string of the file containing the resume."
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Learning content.",
"type": "object",
"title": "learning",
"required": [
"learning_title",
"learning_description"
],
"properties": {
"learning_title": {
"type": "string",
"example": "Computer Science 101",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Learning."
},
"learning_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Course will start you at the absolute beginning teaching you about the fundamental binary language of modern computers.\n You’ll learn about the Turing Machine—a model for the digital\ncomputer.\n You’ll also learn the basics of analytic logic and how learning and\napplying basic principles of logic can help you both work with and work on technical solutions.\n You’ll work in a managed environment and learn to code your very\nfirst program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Learning."
}
}
},
{
"description": "Structure for Learning content by referencing a Course. The source of the Course will set the source of the Skill Event if the source of the Skill Event is not set.",
"type": "object",
"title": "learning_course",
"required": [
"course_id"
],
"properties": {
"course_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for Feedback content.",
"type": "object",
"title": "feedback",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Goal content.",
"type": "object",
"title": "goal",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Project content.",
"type": "object",
"title": "project",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"maxLength": 10000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
}
}
},
{
"description": "Default structure for Ticket content.",
"type": "object",
"title": "ticket",
"required": [
"ticket_description",
"ticket_title"
],
"properties": {
"ticket_title": {
"type": "string",
"maxLength": 1000,
"description": "The title of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.)."
},
"ticket_description": {
"type": "string",
"maxLength": 50000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
},
"ticket_type": {
"type": "string",
"maxLength": 1000,
"description": "The type of a ticket from a ticketing system (e.g. BUG, TASK, STORY, etc.)."
},
"ticket_system": {
"type": "string",
"maxLength": 100,
"default": "jira",
"enum": [
"jira",
"salesforce-service-cloud"
],
"description": "The ticketing system where the ticket originated from. This field is important for skill inference as different models may be used for different ticketing systems. Defaults to \"jira\" if not specified."
}
}
},
{
"description": "Content for a Merge Request Skill Event. Skills are inferred from the title, description, and commit messages (e.g. from GitLab, GitHub, Bitbucket). Merge request events are processed asynchronously; the Employee's Skill Profile is updated after inference.",
"type": "object",
"title": "merge_request",
"required": [
"title",
"description",
"commits"
],
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "The title of the merge request. Must be non-empty (after trimming whitespace). Used by the Skill Engine to infer skills."
},
"description": {
"type": "string",
"maxLength": 250000,
"description": "The description or body of the merge request. Can be empty. Used by the Skill Engine together with the title and commits to infer skills."
},
"commits": {
"type": "array",
"items": {
"description": "A single commit in a Merge Request Skill Event.",
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "The commit message. Must be non-empty (after trimming whitespace). Used by the Skill Engine to infer skills from the commit history."
}
}
},
"description": "List of commits in the merge request. Each commit must have a non-empty message. The list can be empty if the merge request has no commits yet."
}
}
},
{
"description": "Default structure for Certificate content.",
"type": "object",
"title": "certificate",
"required": [
"certificate_title",
"certificate_description"
],
"properties": {
"certificate_title": {
"type": "string",
"example": "Cloud Practitioner Certificate",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Certificate."
},
"certificate_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate proves that you are fluent and skilled in cloud computing.",
"description": "Textual description of the Certificate."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"title": "skill_profile_feedback",
"type": "object",
"required": [
"source",
"skills"
],
"properties": {
"source": {
"type": "string",
"nullable": true,
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The list of skills in the Skill Profile.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"has_skill"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present.",
"example": true
}
}
}
}
}
},
{
"description": "Content of a Skill Event whose `event_type` is one of `it_incident`, `change_request`, `problem_record`, `service_request`, `hr_case`, `support_ticket`, `work_task`, `employee_recognition`, `customer_case`, `task`, `postmortem`, `deal_note`, `success_plan`, `audit_finding`, `work_order`, `technical_spec`, `technical_documentation`, `product_documentation`, `planning_document`, `process_document`, `meeting_notes`, `knowledge_article`, `performance_review`, `publication` or `patent`. The fields are defined per type by its `record_schema`, served by `GET /skill_event_types`. These types are enabled per tenant; contact TechWolf to enable them.\n\nEvery value is a string of at most 10,000 characters; a record carries at most 25 fields and 50,000 characters in total. Every field the type marks `required` must be present, and a key the type does not declare is rejected. Example: a `support_ticket` requires `summary` and `body` and may carry `category`, `subcategory`, `resolution_notes` and `support_team`.",
"type": "object",
"title": "business record",
"additionalProperties": {
"type": "string",
"maxLength": 10000
},
"maxProperties": 25,
"example": {
"summary": "VPN client fails SAML authentication after macOS update",
"body": "Users on macOS 14 cannot connect to GlobalProtect since this morning's Jamf policy push; the SAML redirect completes but the client reports an expired metadata certificate.",
"category": "Network",
"subcategory": "VPN",
"resolution_notes": "Cleared the cached sp-metadata.xml on the affected clients and pushed the rotated IdP certificate through Jamf; verified on 12 machines.",
"support_team": "Network Operations"
}
}
]
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"timestamp": "2021-01-03",
"content": {
"learning_title": "Computer Science 103",
"learning_description": "A description for the Computer Science 103 Course."
},
"source": "youtube"
},
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f847b",
"event_type": "learning",
"timestamp": "2021-01-02",
"content": {
"learning_title": "Computer Science 102",
"learning_description": "A description for the Computer Science 102 Course."
},
"source": "course"
},
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f1538",
"event_type": "learning",
"timestamp": "2021-01-01",
"content": {
"learning_title": "Computer Science 101",
"learning_description": "A description for the Computer Science 101 Course."
},
"source": "employee-archives"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"SkillEvents"
],
"summary": "Create a new Skill Event for an Employee",
"description": "Create a new Skill Event for an Employee. This can be used to track the Skill Profile of an Employee over time.\n\n**Note:** It may take some time for these changes to be reflected in the employee's final skill profile, since they are processed asynchronously.\n\n`ticket`, `merge_request` and business record Skill Events (`it_incident`, `support_ticket`, … — see `GET /skill_event_types`) require model configuration `MC_2025_Q1_V1` or later. On tenants with an older model configuration the request is rejected with a 422 response stating that the model configuration is outdated and asking to upgrade to the latest model configuration.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
},
{
"in": "query",
"name": "end_active_jobs",
"schema": {
"type": "boolean",
"default": false
},
"description": "If enabled, any currently active working history Skill Event (i.e. one without an `end_date`) for this Employee will be ended automatically when the new Skill Event is created."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure of a Skill Event.",
"type": "object",
"required": [
"external_id",
"event_type",
"timestamp",
"content"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique Skill Event ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"description": "Type of the Skill Event. Learn more about the Skill Event Types at [How it works](/technology/skill_events/). `GET /skill_event_types` lists the types available to your tenant and the content fields each one takes.",
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"feedback",
"goal",
"project",
"ticket",
"merge_request",
"certificate",
"skill_notes",
"skill_profile_feedback",
"it_incident",
"change_request",
"problem_record",
"service_request",
"hr_case",
"support_ticket",
"work_task",
"employee_recognition",
"customer_case",
"task",
"postmortem",
"deal_note",
"success_plan",
"audit_finding",
"work_order",
"technical_spec",
"technical_documentation",
"product_documentation",
"planning_document",
"process_document",
"meeting_notes",
"knowledge_article",
"performance_review",
"publication",
"patent"
],
"example": "working_history"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Employee is considered to have obtained the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source system of the Skill Event. This is used to keep track of where Skill Events originate from.",
"type": "string",
"format": "free text",
"example": "employee-archives"
},
"content": {
"description": "The content of the Skill Event. Each type of Skill Event has a different content. The content should align with the ``event_type``. Expanding this field shows you the supported Skill Event content bodies.",
"oneOf": [
{
"title": "working_history",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "HR Manager",
"description": "A formal title that describes the Job function."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning",
"description": "A more in depth description of the Job content."
}
}
},
{
"description": "Structure for Working history content by referencing a Job.",
"type": "object",
"title": "working_history_job",
"required": [
"job_id"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "education_history",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "Start date of the education (IS08601 format).",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"example": "Harvard University",
"description": "The institution responsible for the education."
},
"degree_name": {
"type": "string",
"minLength": 1,
"example": "Master in Human Resources Management",
"description": "A title or short description of the education."
}
}
},
{
"type": "object",
"title": "resume_document",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
],
"description": "States the standard media type of the file."
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1,
"description": "A base64 encoded string of the file containing the resume."
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Learning content.",
"type": "object",
"title": "learning",
"required": [
"learning_title",
"learning_description"
],
"properties": {
"learning_title": {
"type": "string",
"example": "Computer Science 101",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Learning."
},
"learning_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Course will start you at the absolute beginning teaching you about the fundamental binary language of modern computers.\n You’ll learn about the Turing Machine—a model for the digital\ncomputer.\n You’ll also learn the basics of analytic logic and how learning and\napplying basic principles of logic can help you both work with and work on technical solutions.\n You’ll work in a managed environment and learn to code your very\nfirst program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Learning."
}
}
},
{
"description": "Structure for Learning content by referencing a Course. The source of the Course will set the source of the Skill Event if the source of the Skill Event is not set.",
"type": "object",
"title": "learning_course",
"required": [
"course_id"
],
"properties": {
"course_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for Feedback content.",
"type": "object",
"title": "feedback",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Goal content.",
"type": "object",
"title": "goal",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Project content.",
"type": "object",
"title": "project",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"maxLength": 10000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
}
}
},
{
"description": "Default structure for Ticket content.",
"type": "object",
"title": "ticket",
"required": [
"ticket_description",
"ticket_title"
],
"properties": {
"ticket_title": {
"type": "string",
"maxLength": 1000,
"description": "The title of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.)."
},
"ticket_description": {
"type": "string",
"maxLength": 50000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
},
"ticket_type": {
"type": "string",
"maxLength": 1000,
"description": "The type of a ticket from a ticketing system (e.g. BUG, TASK, STORY, etc.)."
},
"ticket_system": {
"type": "string",
"maxLength": 100,
"default": "jira",
"enum": [
"jira",
"salesforce-service-cloud"
],
"description": "The ticketing system where the ticket originated from. This field is important for skill inference as different models may be used for different ticketing systems. Defaults to \"jira\" if not specified."
}
}
},
{
"description": "Content for a Merge Request Skill Event. Skills are inferred from the title, description, and commit messages (e.g. from GitLab, GitHub, Bitbucket). Merge request events are processed asynchronously; the Employee's Skill Profile is updated after inference.",
"type": "object",
"title": "merge_request",
"required": [
"title",
"description",
"commits"
],
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "The title of the merge request. Must be non-empty (after trimming whitespace). Used by the Skill Engine to infer skills."
},
"description": {
"type": "string",
"maxLength": 250000,
"description": "The description or body of the merge request. Can be empty. Used by the Skill Engine together with the title and commits to infer skills."
},
"commits": {
"type": "array",
"items": {
"description": "A single commit in a Merge Request Skill Event.",
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "The commit message. Must be non-empty (after trimming whitespace). Used by the Skill Engine to infer skills from the commit history."
}
}
},
"description": "List of commits in the merge request. Each commit must have a non-empty message. The list can be empty if the merge request has no commits yet."
}
}
},
{
"description": "Default structure for Certificate content.",
"type": "object",
"title": "certificate",
"required": [
"certificate_title",
"certificate_description"
],
"properties": {
"certificate_title": {
"type": "string",
"example": "Cloud Practitioner Certificate",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Certificate."
},
"certificate_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate proves that you are fluent and skilled in cloud computing.",
"description": "Textual description of the Certificate."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"title": "skill_profile_feedback",
"type": "object",
"required": [
"source",
"skills"
],
"properties": {
"source": {
"type": "string",
"nullable": true,
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The list of skills in the Skill Profile.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"has_skill"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present.",
"example": true
}
}
}
}
}
},
{
"description": "Content of a Skill Event whose `event_type` is one of `it_incident`, `change_request`, `problem_record`, `service_request`, `hr_case`, `support_ticket`, `work_task`, `employee_recognition`, `customer_case`, `task`, `postmortem`, `deal_note`, `success_plan`, `audit_finding`, `work_order`, `technical_spec`, `technical_documentation`, `product_documentation`, `planning_document`, `process_document`, `meeting_notes`, `knowledge_article`, `performance_review`, `publication` or `patent`. The fields are defined per type by its `record_schema`, served by `GET /skill_event_types`. These types are enabled per tenant; contact TechWolf to enable them.\n\nEvery value is a string of at most 10,000 characters; a record carries at most 25 fields and 50,000 characters in total. Every field the type marks `required` must be present, and a key the type does not declare is rejected. Example: a `support_ticket` requires `summary` and `body` and may carry `category`, `subcategory`, `resolution_notes` and `support_team`.",
"type": "object",
"title": "business record",
"additionalProperties": {
"type": "string",
"maxLength": 10000
},
"maxProperties": 25,
"example": {
"summary": "VPN client fails SAML authentication after macOS update",
"body": "Users on macOS 14 cannot connect to GlobalProtect since this morning's Jamf policy push; the SAML redirect completes but the client reports an expired metadata certificate.",
"category": "Network",
"subcategory": "VPN",
"resolution_notes": "Cleared the cached sp-metadata.xml on the affected clients and pushed the rotated IdP certificate through Jamf; verified on 12 machines.",
"support_team": "Network Operations"
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created Skill Event.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/skill_events/{skill_event_external_id}": {
"get": {
"tags": [
"SkillEvents"
],
"summary": "Get a Skill Event",
"description": "Get a single Skill Event for an Employee.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "skill_event_external_id",
"required": true,
"description": "Unique ID linked to a Skill Event, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure of a Skill Event.",
"type": "object",
"required": [
"external_id",
"event_type",
"timestamp",
"content"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique Skill Event ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"description": "Type of the Skill Event. Learn more about the Skill Event Types at [How it works](/technology/skill_events/). `GET /skill_event_types` lists the types available to your tenant and the content fields each one takes.",
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"feedback",
"goal",
"project",
"ticket",
"merge_request",
"certificate",
"skill_notes",
"skill_profile_feedback",
"it_incident",
"change_request",
"problem_record",
"service_request",
"hr_case",
"support_ticket",
"work_task",
"employee_recognition",
"customer_case",
"task",
"postmortem",
"deal_note",
"success_plan",
"audit_finding",
"work_order",
"technical_spec",
"technical_documentation",
"product_documentation",
"planning_document",
"process_document",
"meeting_notes",
"knowledge_article",
"performance_review",
"publication",
"patent"
],
"example": "working_history"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Employee is considered to have obtained the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source system of the Skill Event. This is used to keep track of where Skill Events originate from.",
"type": "string",
"format": "free text",
"example": "employee-archives"
},
"content": {
"description": "The content of the Skill Event. Each type of Skill Event has a different content. The content should align with the ``event_type``. Expanding this field shows you the supported Skill Event content bodies.",
"oneOf": [
{
"title": "working_history",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "HR Manager",
"description": "A formal title that describes the Job function."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning",
"description": "A more in depth description of the Job content."
}
}
},
{
"description": "Structure for Working history content by referencing a Job.",
"type": "object",
"title": "working_history_job",
"required": [
"job_id"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "education_history",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "Start date of the education (IS08601 format).",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"example": "Harvard University",
"description": "The institution responsible for the education."
},
"degree_name": {
"type": "string",
"minLength": 1,
"example": "Master in Human Resources Management",
"description": "A title or short description of the education."
}
}
},
{
"type": "object",
"title": "resume_document",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
],
"description": "States the standard media type of the file."
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1,
"description": "A base64 encoded string of the file containing the resume."
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Learning content.",
"type": "object",
"title": "learning",
"required": [
"learning_title",
"learning_description"
],
"properties": {
"learning_title": {
"type": "string",
"example": "Computer Science 101",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Learning."
},
"learning_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Course will start you at the absolute beginning teaching you about the fundamental binary language of modern computers.\n You’ll learn about the Turing Machine—a model for the digital\ncomputer.\n You’ll also learn the basics of analytic logic and how learning and\napplying basic principles of logic can help you both work with and work on technical solutions.\n You’ll work in a managed environment and learn to code your very\nfirst program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Learning."
}
}
},
{
"description": "Structure for Learning content by referencing a Course. The source of the Course will set the source of the Skill Event if the source of the Skill Event is not set.",
"type": "object",
"title": "learning_course",
"required": [
"course_id"
],
"properties": {
"course_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for Feedback content.",
"type": "object",
"title": "feedback",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Goal content.",
"type": "object",
"title": "goal",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Project content.",
"type": "object",
"title": "project",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"maxLength": 10000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
}
}
},
{
"description": "Default structure for Ticket content.",
"type": "object",
"title": "ticket",
"required": [
"ticket_description",
"ticket_title"
],
"properties": {
"ticket_title": {
"type": "string",
"maxLength": 1000,
"description": "The title of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.)."
},
"ticket_description": {
"type": "string",
"maxLength": 50000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
},
"ticket_type": {
"type": "string",
"maxLength": 1000,
"description": "The type of a ticket from a ticketing system (e.g. BUG, TASK, STORY, etc.)."
},
"ticket_system": {
"type": "string",
"maxLength": 100,
"default": "jira",
"enum": [
"jira",
"salesforce-service-cloud"
],
"description": "The ticketing system where the ticket originated from. This field is important for skill inference as different models may be used for different ticketing systems. Defaults to \"jira\" if not specified."
}
}
},
{
"description": "Content for a Merge Request Skill Event. Skills are inferred from the title, description, and commit messages (e.g. from GitLab, GitHub, Bitbucket). Merge request events are processed asynchronously; the Employee's Skill Profile is updated after inference.",
"type": "object",
"title": "merge_request",
"required": [
"title",
"description",
"commits"
],
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "The title of the merge request. Must be non-empty (after trimming whitespace). Used by the Skill Engine to infer skills."
},
"description": {
"type": "string",
"maxLength": 250000,
"description": "The description or body of the merge request. Can be empty. Used by the Skill Engine together with the title and commits to infer skills."
},
"commits": {
"type": "array",
"items": {
"description": "A single commit in a Merge Request Skill Event.",
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "The commit message. Must be non-empty (after trimming whitespace). Used by the Skill Engine to infer skills from the commit history."
}
}
},
"description": "List of commits in the merge request. Each commit must have a non-empty message. The list can be empty if the merge request has no commits yet."
}
}
},
{
"description": "Default structure for Certificate content.",
"type": "object",
"title": "certificate",
"required": [
"certificate_title",
"certificate_description"
],
"properties": {
"certificate_title": {
"type": "string",
"example": "Cloud Practitioner Certificate",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Certificate."
},
"certificate_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate proves that you are fluent and skilled in cloud computing.",
"description": "Textual description of the Certificate."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"title": "skill_profile_feedback",
"type": "object",
"required": [
"source",
"skills"
],
"properties": {
"source": {
"type": "string",
"nullable": true,
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The list of skills in the Skill Profile.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"has_skill"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present.",
"example": true
}
}
}
}
}
},
{
"description": "Content of a Skill Event whose `event_type` is one of `it_incident`, `change_request`, `problem_record`, `service_request`, `hr_case`, `support_ticket`, `work_task`, `employee_recognition`, `customer_case`, `task`, `postmortem`, `deal_note`, `success_plan`, `audit_finding`, `work_order`, `technical_spec`, `technical_documentation`, `product_documentation`, `planning_document`, `process_document`, `meeting_notes`, `knowledge_article`, `performance_review`, `publication` or `patent`. The fields are defined per type by its `record_schema`, served by `GET /skill_event_types`. These types are enabled per tenant; contact TechWolf to enable them.\n\nEvery value is a string of at most 10,000 characters; a record carries at most 25 fields and 50,000 characters in total. Every field the type marks `required` must be present, and a key the type does not declare is rejected. Example: a `support_ticket` requires `summary` and `body` and may carry `category`, `subcategory`, `resolution_notes` and `support_team`.",
"type": "object",
"title": "business record",
"additionalProperties": {
"type": "string",
"maxLength": 10000
},
"maxProperties": 25,
"example": {
"summary": "VPN client fails SAML authentication after macOS update",
"body": "Users on macOS 14 cannot connect to GlobalProtect since this morning's Jamf policy push; the SAML redirect completes but the client reports an expired metadata certificate.",
"category": "Network",
"subcategory": "VPN",
"resolution_notes": "Cleared the cached sp-metadata.xml on the affected clients and pushed the rotated IdP certificate through Jamf; verified on 12 machines.",
"support_team": "Network Operations"
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"SkillEvents"
],
"summary": "Update Skill Event",
"description": "Update a Skill Event for an Employee.\n\n**Note:** It may take some time for these changes to be reflected in the employee's final skill profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "skill_event_external_id",
"required": true,
"description": "Unique ID linked to a Skill Event, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Update structure of a Skill Event.",
"type": "object",
"properties": {
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Employee is considered to have obtained the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source system of the Skill Event. This is used to keep track of where Skill Events originate from.",
"type": "string",
"format": "free text",
"example": "employee-archives"
},
"content": {
"description": "The content of the Skill Event. Each type of Skill Event has a different content. The content should align with the ``event_type``. Expanding this field shows you the supported Skill Event content bodies.",
"oneOf": [
{
"title": "working_history",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "HR Manager",
"description": "A formal title that describes the Job function."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning",
"description": "A more in depth description of the Job content."
}
}
},
{
"description": "Structure for Working history content by referencing a Job.",
"type": "object",
"title": "working_history_job",
"required": [
"job_id"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "TechWolf BV",
"description": "The Company offering the Job."
},
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "education_history",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "Start date of the education (IS08601 format).",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"example": "Harvard University",
"description": "The institution responsible for the education."
},
"degree_name": {
"type": "string",
"minLength": 1,
"example": "Master in Human Resources Management",
"description": "A title or short description of the education."
}
}
},
{
"type": "object",
"title": "resume_document",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
],
"description": "States the standard media type of the file."
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1,
"description": "A base64 encoded string of the file containing the resume."
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Learning content.",
"type": "object",
"title": "learning",
"required": [
"learning_title",
"learning_description"
],
"properties": {
"learning_title": {
"type": "string",
"example": "Computer Science 101",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Learning."
},
"learning_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Course will start you at the absolute beginning teaching you about the fundamental binary language of modern computers.\n You’ll learn about the Turing Machine—a model for the digital\ncomputer.\n You’ll also learn the basics of analytic logic and how learning and\napplying basic principles of logic can help you both work with and work on technical solutions.\n You’ll work in a managed environment and learn to code your very\nfirst program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Learning."
}
}
},
{
"description": "Structure for Learning content by referencing a Course. The source of the Course will set the source of the Skill Event if the source of the Skill Event is not set.",
"type": "object",
"title": "learning_course",
"required": [
"course_id"
],
"properties": {
"course_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for Feedback content.",
"type": "object",
"title": "feedback",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Goal content.",
"type": "object",
"title": "goal",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"description": "Default structure for Project content.",
"type": "object",
"title": "project",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"maxLength": 10000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
}
}
},
{
"description": "Default structure for Ticket content.",
"type": "object",
"title": "ticket",
"required": [
"ticket_description",
"ticket_title"
],
"properties": {
"ticket_title": {
"type": "string",
"maxLength": 1000,
"description": "The title of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.)."
},
"ticket_description": {
"type": "string",
"maxLength": 50000,
"description": "The textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). Best results come from IT-related tickets between 150 and 1500 characters."
},
"ticket_type": {
"type": "string",
"maxLength": 1000,
"description": "The type of a ticket from a ticketing system (e.g. BUG, TASK, STORY, etc.)."
},
"ticket_system": {
"type": "string",
"maxLength": 100,
"default": "jira",
"enum": [
"jira",
"salesforce-service-cloud"
],
"description": "The ticketing system where the ticket originated from. This field is important for skill inference as different models may be used for different ticketing systems. Defaults to \"jira\" if not specified."
}
}
},
{
"description": "Default structure for Certificate content.",
"type": "object",
"title": "certificate",
"required": [
"certificate_title",
"certificate_description"
],
"properties": {
"certificate_title": {
"type": "string",
"example": "Cloud Practitioner Certificate",
"minLength": 1,
"maxLength": 255,
"description": "Title of the Certificate."
},
"certificate_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate proves that you are fluent and skilled in cloud computing.",
"description": "Textual description of the Certificate."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"SkillEvents"
],
"summary": "Delete Skill Event",
"description": "Remove a Skill Event from an Employee. This step deletes all information linked exclusively to this Skill Event. If a Skill Event contained a non-empty Skill Profile, the Employee's Skill Profile is recalculated with the remaining Skill Events.\n\n**Note:** It may take some time for these changes to be reflected in the employee's final skill profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "skill_event_external_id",
"required": true,
"description": "Unique ID linked to a Skill Event, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/interactions": {
"get": {
"tags": [
"EmployeeInteractions"
],
"summary": "List Interactions of an Employee",
"description": "Get all Interactions linked to an Employee.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Interaction type objects linked to the Employee.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"description": "Subset of Interactions starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure of an Employee Interaction.",
"type": "object",
"required": [
"external_id",
"interaction_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique Employee Interaction ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"interaction_type": {
"description": "Type of the Employee Interaction.",
"type": "string",
"example": "vacancy_liked"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Employee Interaction. This is the point in time at which the Employee interacted with a Vacancy or title. If not given, it will be automatically set to the creation time of the Employee Interaction.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"vacancy_id": {
"description": "The ID of the Vacancy with which the Employee has interacted. Either a vacancy_id or a title should be provided, and not both.",
"type": "string",
"format": "uuid",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"title": {
"description": "The title with which the Employee has interacted. Either a vacancy_id or a title should be provided, but not both. A title can be any kind of free text, and does not need to be associated with an existing Vacancy.",
"type": "string",
"example": "mechanical engineer"
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"interaction_type": "vacancy_liked",
"timestamp": "2023-06-08T14:42:31.130855",
"vacancy_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"interaction_type": "vacancy_disliked",
"timestamp": "2021-01-03T11:49:23.624131",
"title": "Software engineer"
},
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f1538",
"interaction_type": "vacancy_liked",
"timestamp": "2023-06-08T14:34:39.326318",
"vacancy_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"EmployeeInteractions"
],
"summary": "Create a new Interaction for an Employee",
"description": "Create a new Interaction for an Employee.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure of an Employee Interaction.",
"type": "object",
"required": [
"external_id",
"interaction_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique Employee Interaction ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"interaction_type": {
"description": "Type of the Employee Interaction.",
"type": "string",
"example": "vacancy_liked"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Employee Interaction. This is the point in time at which the Employee interacted with a Vacancy or title. If not given, it will be automatically set to the creation time of the Employee Interaction.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"vacancy_id": {
"description": "The ID of the Vacancy with which the Employee has interacted. Either a vacancy_id or a title should be provided, and not both.",
"type": "string",
"format": "uuid",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"title": {
"description": "The title with which the Employee has interacted. Either a vacancy_id or a title should be provided, but not both. A title can be any kind of free text, and does not need to be associated with an existing Vacancy.",
"type": "string",
"example": "mechanical engineer"
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"interaction_type": "vacancy_liked",
"timestamp": "2023-06-08T14:42:31.130855",
"vacancy_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created Skill Event.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/interactions/{interaction_external_id}": {
"get": {
"tags": [
"EmployeeInteractions"
],
"summary": "Get Employee Interaction",
"description": "Get an Employee Interaction from an Employee.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "interaction_external_id",
"required": true,
"description": "Unique ID linked to an Employee Interaction, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure of an Employee Interaction.",
"type": "object",
"required": [
"external_id",
"interaction_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique Employee Interaction ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"interaction_type": {
"description": "Type of the Employee Interaction.",
"type": "string",
"example": "vacancy_liked"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Employee Interaction. This is the point in time at which the Employee interacted with a Vacancy or title. If not given, it will be automatically set to the creation time of the Employee Interaction.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"vacancy_id": {
"description": "The ID of the Vacancy with which the Employee has interacted. Either a vacancy_id or a title should be provided, and not both.",
"type": "string",
"format": "uuid",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"title": {
"description": "The title with which the Employee has interacted. Either a vacancy_id or a title should be provided, but not both. A title can be any kind of free text, and does not need to be associated with an existing Vacancy.",
"type": "string",
"example": "mechanical engineer"
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"interaction_type": "vacancy_liked",
"timestamp": "2023-06-08T14:42:31.130855",
"vacancy_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"EmployeeInteractions"
],
"summary": "Delete Employee Interaction",
"description": "Remove an Employee Interaction from an Employee.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique ID linked to an Employee, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "interaction_external_id",
"required": true,
"description": "Unique ID linked to an Employee Interaction, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/vacancies": {
"get": {
"tags": [
"VacancyCRUD"
],
"summary": "List Vacancies",
"description": "Get a list of all Vacancies available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Vacancy objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Vacancies",
"description": "Subset of Vacancies starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Vacancy data.",
"required": [
"external_id",
"job_title",
"job_description"
],
"allOf": [
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
}
]
},
{
"type": "object",
"required": [
"last_updated"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"job_title": "Staffing coordinator",
"job_description": "We are looking for a competent Staffing coordinator to undertake a variety of tasks such as recruitment, orientation and placement of Employees. You will also be the one to ensure that the Company complies with all relevant laws regarding employment.",
"location": {
"lat": 51.0216707,
"lng": 2.6887328
},
"company": "8cbdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"last_updated": "2021-01-21T17:32:28Z"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"job_title": "HR assistant",
"job_description": "We are looking for an HR Assistant to undertake a variety of HR administrative duties.",
"location": {
"lat": 50.0216707,
"lng": 3.6887328
},
"company": "9abdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"last_updated": "2021-01-22T15:02:00Z"
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"job_title": "HR analyst",
"job_description": "We are looking for an HR Analyst to gather and process qualitative and quantitative data around jobs, compensation and employment trends.",
"location": {
"lat": 51.0516707,
"lng": 4.6887328
},
"company": "9hbdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"last_updated": "2021-01-21T17:46:29Z"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"VacancyCRUD"
],
"summary": "Create Vacancy",
"description": "Submit new Vacancy information to initialise their Skill Profile inside the Skill Engine API.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Vacancy data.",
"required": [
"external_id",
"job_title",
"job_description"
],
"allOf": [
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
}
]
},
{
"type": "object",
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created Vacancy.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Entity Limit",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "Creation has failed because you've reached the entity limit 100. You need to delete other entities to be able to create more."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/vacancies/{external_id}": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"VacancyCRUD"
],
"summary": "Get Vacancy",
"description": "Get the Vacancy information stored inside the system.",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Vacancy data.",
"required": [
"external_id",
"job_title",
"job_description"
],
"allOf": [
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
}
]
},
{
"type": "object",
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "Required languages associated with this Vacancy. List of ISO 639-1 language codes, 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."
}
}
},
{
"title": "AttributeInclude",
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
}
],
"example": [
{
"property_name": "creation_date",
"property_value": "2020-03-07"
},
{
"property_name": "language",
"property_value": "de"
}
]
}
}
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"VacancyCRUD"
],
"summary": "Update Vacancy",
"description": "Submit the most up-to-date Vacancy 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.\nPassing the `null` value removes non-required attributes. Object attributes will be removed when passing `null`, arrays with `[]` and strings with the empty string `''`.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating Vacancy data.",
"allOf": [
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
},
{
"type": "object",
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"VacancyCRUD"
],
"summary": "Delete Vacancy",
"description": "Remove a Vacancy from the system. This step deletes all information linked exclusively to this Vacancy. If these need to be removed as well, make sure to do this separately. By deleting a Vacancy, you delete their Skill Profile history, which cannot be recreated or recovered afterwards.",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/vacancies/{external_id}/skill_profile": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"VacancyProfile"
],
"summary": "Get the Skill Profile for a Vacancy",
"description": "Get an export of the Vacancy 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!",
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result returned. The profile consists of a list of Skills with scores, with each score representing the importance of the Skill at hand.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de"
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"domains"
],
"properties": {
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de"
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"VacancyProfile"
],
"summary": "Update a Vacancy Skill Profile with feedback",
"description": "Provide feedback about an existing Vacancy Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message updates the existing Skill Profile, so if a Skill is not present in the body, it will not be affected. The feedback can contain updates that either validate or remove the Skill.",
"parameters": [
{
"in": "query",
"name": "feedback_format",
"required": false,
"description": "The format in which feedback for the Skill Profile is given.",
"schema": {
"type": "string",
"example": "skills",
"enum": [
"skills",
"external_vendor_skills"
],
"default": "skills"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Either `skill` or `skill_id` must be provided, but not both.",
"items": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
}
}
}
]
},
"example": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"has_skill": true
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"has_skill": true
},
{
"skill_id": "a05c0764-3cde-9200-b6a4-dds7639987ff",
"has_skill": true
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"has_skill": false
}
]
}
}
},
{
"title": "External Vendor Skills",
"type": "object",
"properties": {
"source_vendor": {
"allOf": [
{
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
],
"description": "The external vendor's vocabulary in which feedback is provided. The vendor must be activated on the tenant for this to work."
},
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "workday"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Both the `skill` and the `skill_id` must be provided.",
"items": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill_id",
"has_skill"
],
"properties": {
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
}
}
}
]
},
"example": [
{
"skill_id": "111-AAA",
"has_skill": true
},
{
"skill_id": "111-BBB",
"has_skill": true
},
{
"skill_id": "111-CCC",
"has_skill": true
},
{
"skill_id": "111-DDD",
"has_skill": false
}
]
}
}
}
]
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/vacancies/metrics/count": {
"get": {
"tags": [
"VacancyMetrics"
],
"summary": "Get Vacancy count",
"description": "Get the total number of Vacancy objects stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Vacancy"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Vacancy objects stored inside the system.",
"example": 1000
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/courses": {
"get": {
"tags": [
"CourseCRUD"
],
"summary": "List Courses",
"description": "Get a list of all Courses available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Course objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Courses",
"description": "Subset of Courses starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Course data.",
"type": "object",
"required": [
"external_id",
"course_title",
"course_description"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
},
{
"properties": {
"source": {
"description": "Source system or location of this Course.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Udemy"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Course will not be used in matching if active is `false`. This is useful when a Course is being phased out."
}
}
}
]
},
{
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"course_title": "Programming Fundamentals",
"active": true,
"course_description": "Programming is an increasingly important Skill, whether you aspire to a career in software development, or in other fields. This Course is the first in the specialization Introduction to Programming in C, but its lessons extend to any language you might want to learn. This is because programming is fundamentally about figuring out how to solve a class of problems and writing the algorithm, a clear set of steps to solve any problem in its class. This Course will introduce you to a powerful problem-solving process—the Seven Steps—which you can use to solve any programming problem. In this Course, you will learn how to develop an algorithm, then progress to reading code and understanding how programming concepts relate to algorithms.",
"last_updated": "2021-01-21T17:32:28Z",
"source": null
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"course_title": "Product Marketing Core",
"active": true,
"course_description": "From research to optimization, Product Marketing Core explores (cliche alert!) the A to Z of product marketing, and with PMMC in your pocket, you’ll have a richer understanding of the what, why, and how of every product marketing principle. And that’s a promise.",
"last_updated": "2021-01-22T15:02:00Z",
"source": "Workday"
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"course_title": "Data Structures and Algorithms",
"active": true,
"course_description": "You will analyze both road networks and social networks and will learn how to compute the shortest route between New York and San Francisco (1000 times faster than the standard shortest path algorithms!) Afterwards, you will learn how to assemble genomes from millions of short fragments of DNA and how assembly algorithms fuel recent developments in personalized medicine.",
"last_updated": "2021-01-21T17:46:29Z",
"source": "Udemy"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"CourseCRUD"
],
"summary": "Create Course",
"description": "Submit new Course information to initialise its Skill Profile inside the Skill Engine API.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Course data.",
"type": "object",
"required": [
"external_id",
"course_title",
"course_description"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
},
{
"properties": {
"source": {
"description": "Source system or location of this Course.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Udemy"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Course will not be used in matching if active is `false`. This is useful when a Course is being phased out."
}
}
}
]
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of created Course.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Entity Limit",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "Creation has failed because you've reached the entity limit 100. You need to delete other entities to be able to create more."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/courses/{external_id}": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"CourseCRUD"
],
"summary": "Get Course",
"description": "Get the Course information stored inside the system.",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Course data.",
"type": "object",
"required": [
"external_id",
"course_title",
"course_description"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
},
{
"properties": {
"source": {
"description": "Source system or location of this Course.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Udemy"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Course will not be used in matching if active is `false`. This is useful when a Course is being phased out."
}
}
}
]
},
{
"title": "AttributeInclude",
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
}
],
"example": [
{
"property_name": "creation_date",
"property_value": "2020-03-07"
},
{
"property_name": "language",
"property_value": "de"
}
]
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"CourseCRUD"
],
"summary": "Update Course",
"description": "Submit the most up-to-date Course 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.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "strict",
"schema": {
"type": "boolean",
"default": false
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Course data.",
"type": "object",
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
},
"source": {
"description": "Source system or location of this Course.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Course will not be used in matching if active is `false`. This is useful when a Course is being phased out."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"CourseCRUD"
],
"summary": "Delete Course",
"description": "Remove a Course from the system. This step deletes all information linked exclusively to this Course and cannot be undone.",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/courses/{external_id}/skill_profile": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"CourseProfile"
],
"summary": "Get the Skill Profile for a Course",
"description": "Get an export of the Course 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!",
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result returned. The profile consists of a list of Skills with scores, with each score representing the importance of the Skill at hand.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de"
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"domains"
],
"properties": {
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de"
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"CourseProfile"
],
"summary": "Update a Course Skill Profile with feedback",
"description": "Provide feedback about an existing Course Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message updates the existing Skill Profile, so if a Skill is not present in the body, it will not be affected. The feedback can contain updates that either validate or remove the Skill.",
"parameters": [
{
"in": "query",
"name": "feedback_format",
"required": false,
"description": "The format in which feedback for the Skill Profile is given.",
"schema": {
"type": "string",
"example": "skills",
"enum": [
"skills",
"external_vendor_skills"
],
"default": "skills"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Either `skill` or `skill_id` must be provided, but not both.",
"items": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
}
}
}
]
},
"example": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"has_skill": true
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"has_skill": true
},
{
"skill_id": "a05c0764-3cde-9200-b6a4-dds7639987ff",
"has_skill": true
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"has_skill": false
}
]
}
}
},
{
"title": "External Vendor Skills",
"type": "object",
"properties": {
"source_vendor": {
"allOf": [
{
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
],
"description": "The external vendor's vocabulary in which feedback is provided. The vendor must be activated on the tenant for this to work."
},
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "workday"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Both the `skill` and the `skill_id` must be provided.",
"items": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill_id",
"has_skill"
],
"properties": {
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
}
}
}
]
},
"example": [
{
"skill_id": "111-AAA",
"has_skill": true
},
{
"skill_id": "111-BBB",
"has_skill": true
},
{
"skill_id": "111-CCC",
"has_skill": true
},
{
"skill_id": "111-DDD",
"has_skill": false
}
]
}
}
}
]
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/organisational_units": {
"get": {
"tags": [
"OrganisationalUnits"
],
"summary": "List Organisational Units",
"description": "Get a list of all Organisational Units available in the system.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "parent_id",
"schema": {
"type": "string",
"example": "c3903505-eb84-42dc-a79f-5d8b1fe897b7"
},
"description": "This parameter can be used to only include Organisational Units with the specified `parent_id` as their direct parent. If `parent_id=\"null\"`, only root Organisational Units are included. If the parameter is not set, all entities will be included."
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Organisational Unit objects stored in the system. If filtered by `parent_id`, only the matching units are counted.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Organisational Unit",
"description": "Subset of Organisational Unit starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"description": "Default structure for Organisational Unit data.",
"type": "object",
"required": [
"external_id",
"name",
"parent_id",
"active",
"total_nr_of_employees"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "Engineering",
"description": "The name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not."
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. Organisational Units with `parent_id=null` are root Organisational Units."
}
}
},
{
"properties": {
"total_nr_of_employees": {
"type": "integer",
"minimum": 0,
"example": 13,
"description": "Total number of Employees in this Organisational Unit and all its subordinate Organisational Units."
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"name": "Engineering",
"total_nr_of_employees": 20,
"active": true,
"parent_id": null
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"name": "IT",
"total_nr_of_employees": 6,
"active": true,
"parent_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"name": "Finance",
"total_nr_of_employees": 8,
"active": true,
"parent_id": null
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Parent Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown parent_id for this resource. This Organisational Unit does not exist yet."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"OrganisationalUnits"
],
"summary": "Create Organisational Unit",
"description": "Create a new Organisational Unit in the Skill Engine API.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Information needed for creating an Organisational Unit.",
"type": "object",
"required": [
"external_id",
"name"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "Engineering",
"description": "The name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not.",
"default": true
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"default": null,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. Organisational Units with `parent_id=null` are root Organisational Units."
}
}
}
]
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of created Organisational Unit.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Entity Limit",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "Creation has failed because you've reached the entity limit 100. You need to delete other entities to be able to create more."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Parent Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown parent_id for this resource. This Organisational Unit does not exist yet."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/organisational_units/{external_id}": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"OrganisationalUnits"
],
"summary": "Get Organisational Unit",
"description": "Get the Organisational Unit information stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Organisational Unit data.",
"type": "object",
"required": [
"external_id",
"name",
"parent_id",
"active",
"total_nr_of_employees"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "Engineering",
"description": "The name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not."
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. Organisational Units with `parent_id=null` are root Organisational Units."
}
}
},
{
"properties": {
"total_nr_of_employees": {
"type": "integer",
"minimum": 0,
"example": 13,
"description": "Total number of Employees in this Organisational Unit and all its subordinate Organisational Units."
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"OrganisationalUnits"
],
"summary": "Update Organisational Unit",
"description": "Submit the most up-to-date Organisational Unit information. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Organisational Unit data.",
"type": "object",
"allOf": [
{
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Engineering",
"description": "Name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not.",
"default": true
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. If updated with `parent_id=null`, the Organisational Unit becomes a root Organisational Unit."
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Child To Parent",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "400 Bad request",
"description": "The parent_id of an Organisational Unit cannot be set to one of its current subordinate units. Please select a different parent_id."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
},
{
"title": "Parent Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown parent_id for this resource. This Organisational Unit does not exist yet."
}
]
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"OrganisationalUnits"
],
"summary": "Delete Organisational Unit",
"description": "Remove an Organisational Unit and all its subordinate units from the system. This action will remove all information associated exclusively with these units and cannot be undone.",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/organisational_units/export": {
"get": {
"tags": [
"OrganisationalStructureExport"
],
"summary": "Export Organisational Structure hierarchy",
"description": "Export the Organisational Structure as a hierarchy. Each Organisational Unit can have at most one parent unit, with no limit on the number of levels.\n",
"parameters": [
{
"in": "query",
"name": "skill_id",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"description": "The unique ID of a Skill, consisting of alphanumeric characters and hyphens. Setting this parameter will include only Organisational Units with Employees that have this Skill in their Skill Profile, and per Organisational Unit only count the number of Employees with this Skill."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to use when passing the `skill_id` query parameter. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "When set to `low_data_availability_flag`, the response will include information about the total number of Employees with low data availability within each Organisational Unit. For Employees, this field is equal to 1 or 0 depending on whether the Employee has low data availability.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"low_data_availability_flag"
]
},
"default": [],
"example": [
"low_data_availability_flag"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"organisational_structure"
],
"properties": {
"organisational_structure": {
"description": "A list of Organisational Units that do not have a parent.",
"type": "array",
"items": {
"type": "object",
"required": [
"external_id",
"name",
"total_nr_of_employees",
"children"
],
"properties": {
"external_id": {
"type": "string",
"description": "Unique ID linked to the Organisational Unit, consisting of alphanumeric characters, hyphens and underscores.",
"example": "c3903505-eb84-42dc-a79f-5d8b1fe897b7"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Organisational Unit.",
"example": "Engineering"
},
"total_nr_of_employees": {
"type": "integer",
"description": "Total number of Employees in this Organisational Unit, including those in all subordinate units.",
"example": 16
},
"low_data_availability": {
"type": "integer",
"description": "The total number of Employees with low data availability within this Organisational Unit."
},
"children": {
"type": "array",
"description": "List of Organisational Units that are direct children.",
"items": {
"type": "object",
"required": [
"external_id",
"name",
"total_nr_of_employees",
"children"
],
"properties": {
"external_id": {
"type": "string",
"description": "Unique ID linked to the Organisational Unit, consisting of alphanumeric characters, hyphens and underscores.",
"example": "d3903505-eb84-42dc-a79f-5d8b1fe897b7"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Organisational Unit.",
"example": "Frontend Engineering"
},
"total_nr_of_employees": {
"type": "integer",
"description": "Total number of Employees in this Organisational Unit, including those in all subordinate units.",
"example": 9
},
"low_data_availability": {
"type": "integer",
"description": "The total number of Employees with low data availability within this Organisational Unit."
},
"children": {
"type": "array",
"items": {
"type": "object"
},
"description": "List of Organisational Units that are direct children."
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/courses/metrics/count": {
"get": {
"tags": [
"CourseMetrics"
],
"summary": "Get Course count",
"description": "Get the total number of Course objects stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Course"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Course objects stored inside the system.",
"example": 1000
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skill_clusters": {
"get": {
"deprecated": true,
"tags": [
"SkillClusterCRUD"
],
"summary": "List Skill Clusters",
"description": "Get a list of all Skill Clusters available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Skill Cluster objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Skill Clusters",
"description": "Subset of Skill Clusters starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Skill Cluster data.",
"type": "object",
"required": [
"external_id",
"skill_cluster_name",
"skill_cluster_name_description",
"skill_cluster_name_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Audit",
"description": "Name of the Skill Cluster. Must be unique in the system."
},
"skill_cluster_description": {
"type": "string",
"minLength": 1,
"example": "The ability and Skill to conduct audits, identifying exceptions and developing specific solutions or recommendations",
"description": "Textual description of the Skill Cluster."
},
"skill_cluster_type": {
"type": "string",
"example": "taxonomy",
"description": "The type of the Skill Cluster",
"enum": [
"inferred",
"taxonomy"
]
}
}
},
{
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skill_cluster_name": "Debug Software",
"skill_cluster_description": "Repair computer code by analysing testing results, locating the defects causing the software to output an incorrect or unexpected result and removing these faults.",
"last_updated": "2021-01-21T17:32:28Z",
"skill_cluster_type": "taxonomy"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"skill_cluster_name": "Program Firmware",
"skill_cluster_description": "Program permanent software with a read-only memory (ROM) on a hardware device, such as an integrated circuit.",
"last_updated": "2021-01-22T15:02:00Z",
"skill_cluster_type": "inferred"
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"skill_cluster_name": "Utilise Machine Learning",
"skill_cluster_description": "Use techniques and algorithms that are able to extract mastery out of data, learn from it and make predictions, to be used for program optimisation, application adaptation, pattern recognition, filtering, search engines and computer vision.",
"last_updated": "2021-01-21T17:46:29Z",
"skill_cluster_type": "inferred"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skill_clusters/{external_id}": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"deprecated": true,
"tags": [
"SkillClusterCRUD"
],
"summary": "Get Skill Cluster",
"description": "Get the Skill Cluster information stored inside the system.",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Skill Cluster data.",
"type": "object",
"required": [
"external_id",
"skill_cluster_name",
"skill_cluster_name_description",
"skill_cluster_name_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Audit",
"description": "Name of the Skill Cluster. Must be unique in the system."
},
"skill_cluster_description": {
"type": "string",
"minLength": 1,
"example": "The ability and Skill to conduct audits, identifying exceptions and developing specific solutions or recommendations",
"description": "Textual description of the Skill Cluster."
},
"skill_cluster_type": {
"type": "string",
"example": "taxonomy",
"description": "The type of the Skill Cluster",
"enum": [
"inferred",
"taxonomy"
]
}
}
},
{
"title": "AttributeInclude",
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
}
],
"example": [
{
"property_name": "creation_date",
"property_value": "2020-03-07"
},
{
"property_name": "language",
"property_value": "de"
}
]
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skill_clusters/{external_id}/skill_profile": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"deprecated": true,
"tags": [
"SkillClusterProfile"
],
"summary": "Get the Skill Profile for a Skill Cluster",
"description": "Get an export of the Skill Cluster Skill Profile to leverage it for user interaction.",
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format in which the Skill Profile needs to be returned. More info about adding your Skill Clusters can be found in the [tutorials](/tutorials/skill-clusters/skill-cluster-framework/).",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list"
],
"default": "list"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The Skills of the Skill Cluster. This is what is returned when Skill Clusters are managed by TechWolf.",
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this Skill Cluster.",
"items": {
"description": "Default structure for Skill Cluster.",
"type": "object",
"required": [
"skill"
],
"properties": {
"skill": {
"type": "string"
}
}
},
"example": [
{
"skill": "Programming"
},
{
"skill": "Business Intelligence"
},
{
"skill": "Machine Learning"
}
]
},
"domain": {
"type": "string",
"description": "The Domain this Skill Cluster belongs to.",
"example": "Machine Learning"
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skill_clusters/metrics/count": {
"get": {
"deprecated": true,
"tags": [
"SkillClusterMetrics"
],
"summary": "Get Skill Cluster count",
"description": "Get the total number of Skill Cluster objects stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "SkillCluster"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Skill Cluster objects stored inside the system.",
"example": 1000
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies": {
"get": {
"tags": [
"CompanyCRUD"
],
"summary": "List External Companies",
"description": "Get a list of all External Companies available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of External Company objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "External Companies",
"description": "Subset of External Companies starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for External Company data.",
"type": "object",
"required": [
"external_id",
"name",
"vat"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
}
}
},
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"name": "TechWolf",
"vat": "BE0702852201",
"location": {
"lat": 51.0216707,
"lng": 2.6887328
}
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"name": "Example BVBA",
"vat": "BE0702852201",
"location": {
"lat": 50.0216707,
"lng": 3.6887328
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"CompanyCRUD"
],
"summary": "Create External Company",
"description": "Submit new External Company information to store inside the Skill Engine API.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "Default structure for External Company data.",
"type": "object",
"required": [
"external_id",
"name",
"vat"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
}
}
},
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for language requirements of the External Company, 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."
}
}
}
]
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created External Company.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Entity Limit",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "Creation has failed because you've reached the entity limit 100. You need to delete other entities to be able to create more."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies/{external_id}": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"CompanyCRUD"
],
"summary": "Get External Company",
"description": "Get the External Company information stored inside the system.",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "Default structure for External Company data.",
"type": "object",
"required": [
"external_id",
"name",
"vat"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
}
}
},
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
},
{
"type": "object",
"properties": {
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for language requirements of the External Company, combined with the proficiency level.\n The proficiency levels go from 1 (elementary proficiency) to 5\n(native proficiency). If the level is omitted, the default proficiency level of 2 is used."
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"CompanyCRUD"
],
"summary": "Update External Company",
"description": "Submit the most up-to-date External Company information to update the information stored inside the system. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating External Company data.",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for language requirements of the External Company, 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."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"CompanyCRUD"
],
"summary": "Delete External Company",
"description": "Remove an External Company from the system. The External Company's linked Vacancies will be processed in cascade based on:\n * linked __active__ Vacancy: the reference to the External Company is\nremoved, but the Vacancy itself is not removed from the system.\n * linked __inactive__ Vacancy: the reference to the External Company as\nwell as the Vacancy itself is removed from the system.",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies/{external_id}/vacancies": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"CompanyCRUD"
],
"summary": "List External Company's Vacancies",
"description": "Get an overview of all the Vacancies stored inside the system that are linked to the specified External Company.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Vacancy objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Vacancies",
"description": "Subset of Vacancies starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Vacancy data.",
"required": [
"external_id",
"job_title",
"job_description"
],
"allOf": [
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
}
]
},
{
"type": "object",
"required": [
"last_updated"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"job_title": "Staffing coordinator",
"job_description": "We are looking for a competent Staffing coordinator to undertake a variety of tasks such as recruitment, orientation and placement of Employees. You will also be the one to ensure that the Company complies with all relevant laws regarding employment.",
"location": {
"lat": 51.0216707,
"lng": 2.6887328
},
"company": "8cbdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"last_updated": "2021-01-21T17:32:28Z"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"job_title": "HR assistant",
"job_description": "We are looking for an HR Assistant to undertake a variety of HR administrative duties.",
"location": {
"lat": 50.0216707,
"lng": 3.6887328
},
"company": "9abdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"last_updated": "2021-01-22T15:02:00Z"
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"job_title": "HR analyst",
"job_description": "We are looking for an HR Analyst to gather and process qualitative and quantitative data around jobs, compensation and employment trends.",
"location": {
"lat": 51.0516707,
"lng": 4.6887328
},
"company": "9hbdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"last_updated": "2021-01-21T17:46:29Z"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies/{external_id}/desired_functions": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"post": {
"tags": [
"CompanyCRUD"
],
"summary": "Upload and add desired functions",
"description": "Upload a list of desired functions that will be created as inactive pseudo Vacancies linked to the External Company. If no Skill Profile can be created from the Job title alone, the desired function will not be stored. The desired function Vacancies will be added to the already existing desired function Vacancies of the External Company.",
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "request_format",
"required": false,
"description": "Explicitly sets the input format used to represent the submitted desired functions as either:\n * a structured list of Job title objects.\n * free-text multiline string input in which each line contains at most one Job title.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"free_text"
],
"default": "list"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "list",
"description": "Collection of desired functions that should be considered in matching.",
"type": "object",
"required": [
"titles"
],
"properties": {
"titles": {
"type": "array",
"items": {
"title": "job_title",
"type": "object",
"required": [
"job_title"
],
"properties": {
"job_title": {
"type": "string"
}
}
},
"example": [
{
"job_title": "Business analyst"
},
{
"job_title": "Data Scientist"
}
]
}
}
},
{
"title": "free_text",
"description": "Collection of desired functions that should be considered in matching.",
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"example": "Software Consultant\n- opvolgen van klanten\n- opleidingen geven aan zowel interne als externe klanten \nMag volledig BEL zijn\n\nGeen medische sector\n\nLoon: €3000 bruto met wagen/kaart, hospi/groeps, laptop/gsm, MC €8"
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"put": {
"tags": [
"CompanyCRUD"
],
"summary": "Replace existing desired functions",
"description": "Replace the list of desired functions that are used as inactive pseudo Vacancies linked to the External Company. If no Skill Profile can be created from the Job title alone, the desired function will not be stored. Previously existing desired function Vacancies will be removed when using this endpoint.",
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
},
{
"in": "query",
"name": "request_format",
"required": false,
"description": "Explicitly sets the input format used to represent the submitted desired functions as either:\n * a structured list of Job title objects.\n * free-text multiline string input in which each line contains at most one Job title.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"free_text"
],
"default": "list"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "list",
"description": "Collection of desired functions that should be considered in matching.",
"type": "object",
"required": [
"titles"
],
"properties": {
"titles": {
"type": "array",
"items": {
"title": "job_title",
"type": "object",
"required": [
"job_title"
],
"properties": {
"job_title": {
"type": "string"
}
}
},
"example": [
{
"job_title": "Business analyst"
},
{
"job_title": "Data Scientist"
}
]
}
}
},
{
"title": "free_text",
"description": "Collection of desired functions that should be considered in matching.",
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"example": "Software Consultant\n- opvolgen van klanten\n- opleidingen geven aan zowel interne als externe klanten \nMag volledig BEL zijn\n\nGeen medische sector\n\nLoon: €3000 bruto met wagen/kaart, hospi/groeps, laptop/gsm, MC €8"
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies/{external_id}/nace": {
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"post": {
"tags": [
"CompanyCRUD"
],
"summary": "Profile External Company's hiring activity with NACE-codes",
"description": "Profiles the market-average hiring activity of an External Company based on their linked NACE-codes by creating corresponding pseudo-Vacancies in the system. This operation is **additive** and remembers previously profiled pseudo-Vacancies.",
"parameters": [
{
"in": "query",
"name": "type",
"required": true,
"description": "As European member states are free to deepen the baselist of NACE codes to classify economic activities, this parameter specifies the derivative set of NACE codes used as input. For example, NACE**BEL**-codes are standard use in Belgium.",
"schema": {
"type": "string",
"minLength": 1,
"example": "nace_bel",
"enum": [
"nace_bel"
]
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"nace_codes"
],
"properties": {
"nace_codes": {
"description": "Collection of NACE-codes used to profile the External Company. Cannot be empty.",
"type": "array",
"minLength": 1,
"maxLength": 7,
"items": {
"title": "NACE-code",
"type": "string"
},
"example": [
"10110",
"94910"
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"put": {
"tags": [
"CompanyCRUD"
],
"summary": "Reprofile External Company's hiring activity with NACE-codes",
"description": "Profiles the market-average hiring activity of an External Company based on their linked NACE-codes by creating corresponding pseudo-Vacancies in the system. This operation is **substituting** and replaces previously profiled pseudo-Vacancies.",
"parameters": [
{
"in": "query",
"name": "type",
"required": true,
"description": "As European member states are free to deepen the baselist of NACE codes to classify economic activities, this parameter specifies the derivative set of NACE codes used as input. For example, NACE**BEL**-codes are standard use in Belgium.",
"schema": {
"type": "string",
"minLength": 1,
"example": "nace_bel",
"enum": [
"nace_bel"
]
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"nace_codes"
],
"properties": {
"nace_codes": {
"description": "Collection of NACE-codes used to profile the External Company. When empty, all existing pseudo-Vacancies are removed.",
"type": "array",
"items": {
"title": "NACE-code",
"type": "string"
},
"example": [
"10110",
"94910"
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skills/search": {
"get": {
"tags": [
"Skill Search"
],
"summary": "Search for Skills similar to the text provided",
"parameters": [
{
"in": "query",
"name": "query",
"required": true,
"schema": {
"type": "string",
"example": "Machine%20le",
"maxLength": 100
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "search_method",
"required": false,
"description": "Indicates how Skills are searched for with the given query.",
"schema": {
"type": "string",
"example": "autocomplete",
"enum": [
"autocomplete"
],
"default": "autocomplete"
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which you want to search for Skills. This will only work for vendors that are activated on your tenant. When specified, the query parameter `domain_namespace` will not work, and Domains will not be returned in the response, as they are not supported on external vendor Skills.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"name": "properties",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"description": "Filter skills by their properties. Use the format `properties[property_name]=value` to filter skills that have a specific property with a specific value.\nFor example, `properties[sap_status]=active` will only return skills that have the `sap_status` property set to `active`.\n\n**Available properties:**\n- `sap_status`: Status of the Skill in the SAP Attribute Library (possible values: `active`, `inactive`)\n",
"schema": {
"type": "object"
}
},
{
"in": "query",
"required": false,
"name": "vocab_language",
"description": "The display language in which the Skill names are provided.\nIf not specified, the default language (`en_uk`) will be used.\nThe `en` language is an alias for `en_uk`.\n",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"required": [
"skill",
"skill_id",
"domain_name"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill. If an external vendor is specified in the query parameter `external_vendor`, the Skill name will be the external vendor's Skill name."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally unique ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. If an external vendor is specified in the query parameter `external_vendor`, the Skill ID will be the external vendor's Skill ID.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The Domain of the Skill. Not present if an external vendor is specified in the query parameter `external_vendor`."
}
}
}
]
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/vacancies/{vacancy_external_id}/gap": {
"get": {
"tags": [
"Skill Gaps"
],
"summary": "Get the Skillgap between an Employee and a Vacancy",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "vacancy_external_id",
"required": true,
"description": "Unique external ID linked to this Vacancy, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_name",
"skill_id"
]
}
]
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/skills/lookup": {
"post": {
"tags": [
"Skill Lookup"
],
"summary": "Look up the Skill IDs of a list of Skill names",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "normalized",
"required": false,
"description": "When set to `true`, both the input Skill names and the stored Skill names are compared after lowercasing and stripping Latin diacritics (using the same normalization as the Skill search index). This makes matches case-insensitive and accent-insensitive, so inputs like `Café`, `café`, and `cafe` all resolve to the same Skill. When set to `false` (default), names must match exactly, including casing and diacritics.\n\nEach input still receives exactly one row in the response, even when multiple inputs normalize to the same key.\n\n**Note on CJK characters:** normalization only affects Latin characters. Japanese voicing marks (dakuten / handakuten), Hangul syllables, and simplified ↔ traditional Han are not folded. For pure CJK names, normalized matching behaves like exact matching; for mixed-script names, only the Latin portion is normalized.",
"schema": {
"type": "boolean",
"example": true,
"default": false
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for a request body containing a list of Skill names.",
"type": "object",
"title": "skill_names",
"required": [
"skill_names"
],
"properties": {
"skill_names": {
"type": "array",
"description": "A list of Skill names.",
"items": {
"type": "string"
},
"example": [
"Machine Learning",
"Python",
"Tensorflow"
]
}
}
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"skill_name",
"query",
"skill_id"
],
"properties": {
"skill_name": {
"type": "string",
"description": "The canonical name of the matched Skill. When `normalized=false`, this is always equal to `query`. When `normalized=true` and the Skill is matched, this is the canonical DB-stored name, which may differ from `query` in casing or Latin diacritics. On a miss, this falls back to the input `query` so the field is always non-null."
},
"query": {
"type": "string",
"description": "The Skill name as provided in the request body. Always echoed back unchanged, regardless of whether the Skill was matched or whether `normalized` was set."
},
"skill_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"nullable": true,
"description": "The unique ID of the matched Skill, or `null` when the Skill name could not be resolved."
}
}
}
}
},
"example": {
"results": [
{
"skill_name": "Machine Learning",
"query": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill_name": "Python",
"query": "Python",
"skill_id": null
},
{
"skill_name": "Tensorflow",
"query": "Tensorflow",
"skill_id": null
}
]
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/tasks": {
"post": {
"tags": [
"TasksCRUD"
],
"summary": "Create a custom task",
"description": "Create a new custom Task in the catalogue.\n\nThe `task_id` is derived deterministically from `task_name`, so\nre-submitting the same name returns `409`. Custom Tasks are immediately\nmatchable.\n",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"task_name"
],
"properties": {
"task_name": {
"type": "string",
"description": "The composed task name. Must satisfy the same structural heuristics enforced by `POST /tasks/validate` (length 15–320, ≥3 words, ≤30% non-letter characters); a candidate that fails them is rejected with `422`.",
"example": "Review quarterly performance reports for direct reports"
},
"source": {
"type": "string",
"maxLength": 100,
"nullable": true,
"description": "Optional free-text label recording where this Task originated (for example the system or workflow that created it). Stored with the Task for attribution and not returned by the read endpoints.",
"example": "workforce-planning-import"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"task_id",
"task_name"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task_name": {
"type": "string",
"description": "The stored task name.",
"example": "Review quarterly performance reports for direct reports"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/tasks/{task_id}": {
"parameters": [
{
"in": "path",
"name": "task_id",
"required": true,
"description": "The identifier of the Task.",
"schema": {
"type": "string",
"format": "slug",
"maxLength": 100,
"example": "ba418404-3df1-cb19-a73c-1fb9351846d5"
}
}
],
"get": {
"tags": [
"TasksCRUD"
],
"summary": "Get a Task",
"description": "Fetch a single Task by its `task_id`.\n\nThe `task_id` of Tasks can be found via the task search or task export\nendpoints. For custom Tasks, the `POST /tasks` endpoint also returns the\nassociated `task_id`. By default the response contains only `task_id` and\n`task_name`; request additional attributes via `include`.\n",
"parameters": [
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ai_impact",
"hierarchy",
"task_source",
"enrichment_status"
]
}
},
"description": "Additional attributes to include in the response. This query parameter can be added multiple times to include more attributes. By default none of these are returned.\n\n- `ai_impact` — includes AI impact level and rationale.\n- `hierarchy` — includes the task's position in the work taxonomy (domain → subdomain → cluster → canonical task).\n- `task_source` — distinguishes standard work-taxonomy Tasks (`vocabulary`) from Tasks created through the `POST /tasks` endpoint (`custom`).\n- `enrichment_status` — includes the status of the task's asynchronous AI-impact enrichment (`pending`, `complete`, or `failed`).\n",
"example": [
"task_source",
"enrichment_status"
]
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"task_id",
"task_name"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task_name": {
"type": "string",
"description": "Name/description of the task.",
"example": "Write unit tests for backend services"
},
"ai_impact": {
"description": "AI impact level and rationale for this task. Only present when `include=ai_impact`.",
"allOf": [
{
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
}
]
},
"hierarchy": {
"description": "Position of this task in the work taxonomy (domain → subdomain → cluster → canonical task). Only present when `include=hierarchy`. Either all fields are populated, or all fields are `null` when the task has no position in the work taxonomy.",
"allOf": [
{
"type": "object",
"nullable": true,
"description": "The position of this task in the task hierarchy\n(domain → subdomain → cluster → canonical task).\nEither all fields are populated, or all fields are null\nwhen the task has no position in the task hierarchy.\n",
"properties": {
"domain_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy domain.",
"example": "Computer Science"
},
"domain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy domain.",
"example": "576132d7-83d2-bcba-78db-e14c073409dd"
},
"subdomain_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy subdomain.",
"example": "Software Engineering"
},
"subdomain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy subdomain.",
"example": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab"
},
"cluster_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy cluster.",
"example": "Monitoring and alerting"
},
"cluster_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy cluster.",
"example": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1"
},
"canonical_task_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy canonical task.",
"example": "Configure observability monitoring tools"
},
"canonical_task_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy canonical task.",
"example": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
}
}
}
]
},
"task_source": {
"description": "Origin of the task. Only present when `include=task_source`.",
"allOf": [
{
"type": "string",
"description": "Origin of the Task.\n\n`vocabulary` = a Task from the standard work taxonomy (the default for\npipeline-extracted Tasks). `custom` = a Task created through the\n`POST /tasks` endpoint.\n",
"enum": [
"vocabulary",
"custom"
],
"example": "vocabulary"
}
]
},
"enrichment_status": {
"description": "Status of the task's asynchronous AI-impact enrichment. Only present when `include=enrichment_status`.",
"allOf": [
{
"type": "string",
"description": "Status of the asynchronous AI-impact enrichment for this Task.\n\n`pending` = enrichment is queued or in progress. `complete` = enrichment\nfinished and AI-impact data is available. `failed` = enrichment failed after\nretries. Pipeline-extracted Tasks default to `complete`.\n",
"enum": [
"pending",
"complete",
"failed"
],
"example": "complete"
}
]
}
}
},
"examples": {
"Default": {
"summary": "Default (no include)",
"value": {
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services"
}
},
"WithIncludes": {
"summary": "With all includes",
"value": {
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services",
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"hierarchy": {
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
},
"task_source": "vocabulary",
"enrichment_status": "complete"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"TasksCRUD"
],
"summary": "Delete a custom Task",
"description": "Delete a custom Task from the catalogue.\n\nOnly Tasks with `task_source: \"custom\"` can be deleted. Standard Tasks\n(`task_source: \"vocabulary\"`) return `403`.\n\nAfter deletion, the Task no longer appears in any Job or Employee task\nprofile.\n",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/tasks/search": {
"get": {
"tags": [
"TaskSearch"
],
"summary": "Search Tasks",
"description": "\n\nSearch for Tasks using a fuzzy text query. Results are ordered by similarity\nto the query string (highest first). Low-confidence matches are excluded.\nUseful for looking up tasks by name when building or updating task profiles.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"name": "query",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 100
},
"description": "The search query to match against task names. Typically a short partial term — fuzzy matching expands it across stored task names.",
"example": "unit tests"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
"description": "Maximum number of results to return.",
"example": 10
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ai_impact",
"hierarchy",
"task_source",
"enrichment_status"
]
}
},
"description": "Additional attributes that will be included in each result. This query parameter can be added multiple times to include more attributes. By default none of these are returned.\n\n- `ai_impact` — includes AI impact level and rationale per task.\n- `hierarchy` — includes the task's position in the work taxonomy (domain → subdomain → cluster → canonical task).\n- `task_source` — distinguishes standard work-taxonomy Tasks (`vocabulary`) from Tasks created through the `POST /tasks` endpoint (`custom`).\n- `enrichment_status` — includes the status of the task's asynchronous AI-impact enrichment (`pending`, `complete`, or `failed`).\n",
"example": [
"ai_impact",
"hierarchy"
]
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"required": [
"task_id",
"task_name"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task_name": {
"type": "string",
"description": "Name/description of the task.",
"example": "Write unit tests for backend services"
},
"ai_impact": {
"description": "AI impact level and rationale for this task. Only present when `include=ai_impact`.",
"allOf": [
{
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
}
]
},
"hierarchy": {
"description": "Position of this task in the work taxonomy (domain → subdomain → cluster → canonical task). Only present when `include=hierarchy`. Either all fields are populated, or all fields are `null` when the task has no position in the work taxonomy.",
"allOf": [
{
"type": "object",
"nullable": true,
"description": "The position of this task in the task hierarchy\n(domain → subdomain → cluster → canonical task).\nEither all fields are populated, or all fields are null\nwhen the task has no position in the task hierarchy.\n",
"properties": {
"domain_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy domain.",
"example": "Computer Science"
},
"domain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy domain.",
"example": "576132d7-83d2-bcba-78db-e14c073409dd"
},
"subdomain_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy subdomain.",
"example": "Software Engineering"
},
"subdomain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy subdomain.",
"example": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab"
},
"cluster_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy cluster.",
"example": "Monitoring and alerting"
},
"cluster_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy cluster.",
"example": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1"
},
"canonical_task_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy canonical task.",
"example": "Configure observability monitoring tools"
},
"canonical_task_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy canonical task.",
"example": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
}
}
}
]
},
"task_source": {
"description": "Origin of the task. Only present when `include=task_source`.",
"allOf": [
{
"type": "string",
"description": "Origin of the Task.\n\n`vocabulary` = a Task from the standard work taxonomy (the default for\npipeline-extracted Tasks). `custom` = a Task created through the\n`POST /tasks` endpoint.\n",
"enum": [
"vocabulary",
"custom"
],
"example": "vocabulary"
}
]
},
"enrichment_status": {
"description": "Status of the task's asynchronous AI-impact enrichment. Only present when `include=enrichment_status`.",
"allOf": [
{
"type": "string",
"description": "Status of the asynchronous AI-impact enrichment for this Task.\n\n`pending` = enrichment is queued or in progress. `complete` = enrichment\nfinished and AI-impact data is available. `failed` = enrichment failed after\nretries. Pipeline-extracted Tasks default to `complete`.\n",
"enum": [
"pending",
"complete",
"failed"
],
"example": "complete"
}
]
}
}
}
},
"examples": {
"Default": {
"summary": "Default",
"value": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services"
},
{
"task_id": "8c1e4313-cb49-9055-74c9-5976970fa335",
"task_name": "Write integration tests for the payment API"
}
]
},
"WithIncludes": {
"summary": "With includes",
"value": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services",
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"hierarchy": {
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
},
"task_source": "vocabulary",
"enrichment_status": "complete"
},
{
"task_id": "8c1e4313-cb49-9055-74c9-5976970fa335",
"task_name": "Write integration tests for the payment API",
"ai_impact": {
"level": "H3",
"rationale": "Some automation possible but context-dependent"
},
"hierarchy": {
"domain_name": null,
"domain_id": null,
"subdomain_name": null,
"subdomain_id": null,
"cluster_name": null,
"cluster_id": null,
"canonical_task_name": null,
"canonical_task_id": null
},
"task_source": "custom",
"enrichment_status": "pending"
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/tasks/validate": {
"post": {
"tags": [
"TaskValidation"
],
"summary": "Validate Tasks",
"description": "Validate a batch of 1-15 candidate Task names before persisting them, without\ncreating anything. Each candidate is screened with fast whole-string quality\nheuristics and a near-duplicate lookup against your existing Tasks.\n\n- **Quality heuristics** are hard rejections. A candidate that trips one or more\n heuristics gets `status: \"rejected:formatting\"` and a `rejection_reasons` list\n naming the failing codes (`too_short`, `too_long`, `too_few_words`,\n `low_letter_ratio`).\n- **Near-duplicate detection** is advisory only. `similar_tasks` lists\n existing Tasks similar to the candidate (highest similarity first),\n populated only for candidates that pass the quality heuristics and empty\n otherwise. It never rejects on its own, so the caller decides whether a\n match is a true duplicate.\n\nA candidate that passes the heuristics has `status: \"valid\"` and an empty\n`rejection_reasons`, even when `similar_tasks` is non-empty.\n",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tasks"
],
"properties": {
"tasks": {
"type": "array",
"minItems": 1,
"maxItems": 15,
"description": "Candidate Tasks to validate. Between 1 and 15 per request; requests with more than 15 are rejected with `422`.",
"items": {
"type": "object",
"required": [
"task_name"
],
"properties": {
"task_name": {
"type": "string",
"description": "The composed Task name to validate.",
"example": "Review quarterly performance reports for direct reports"
}
}
}
}
}
},
"examples": {
"Default": {
"summary": "Default",
"value": {
"tasks": [
{
"task_name": "Review quarterly performance reports for direct reports"
},
{
"task_name": "Run"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "One result per input Task, in the same order as the request.",
"items": {
"type": "object",
"required": [
"task_name",
"task_id",
"status",
"rejection_reasons",
"similar_tasks"
],
"properties": {
"task_name": {
"type": "string",
"description": "Echo of the candidate Task name.",
"example": "Run"
},
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
}
],
"nullable": true,
"description": "The Task id this candidate will receive on create. Present for `valid` candidates so the caller can attach it without a separate create round-trip; `null` for `rejected:formatting` candidates, which can never be persisted."
},
"status": {
"type": "string",
"enum": [
"valid",
"rejected:formatting"
],
"description": "`valid` when the candidate passes all quality heuristics (it is not yet persisted); `rejected:formatting` when one or more heuristics fail.",
"example": "rejected:formatting"
},
"rejection_reasons": {
"type": "array",
"description": "Failing quality-heuristic codes. Empty when `status` is `valid`; populated when `status` is `rejected:formatting`.",
"items": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"enum": [
"too_short",
"too_long",
"too_few_words",
"low_letter_ratio"
],
"description": "`too_short` (fewer than 15 characters), `too_long` (more than 320 characters), `too_few_words` (fewer than 3 whitespace-separated words), `low_letter_ratio` (more than 30% non-letter characters).",
"example": "too_short"
}
}
}
},
"similar_tasks": {
"type": "array",
"description": "Existing Tasks similar to the candidate, highest similarity first. Advisory only and always present; populated for candidates that pass the quality heuristics (`status: valid`) and empty otherwise. The caller decides whether a match is a true duplicate.",
"items": {
"type": "object",
"required": [
"task_id",
"task_name",
"similarity",
"match_type"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
}
],
"description": "Unique identifier of the similar Task."
},
"task_name": {
"type": "string",
"description": "Name of the similar Task.",
"example": "Write quarterly budget report"
},
"similarity": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "Similarity score (0-1).",
"example": 0.92
},
"match_type": {
"type": "string",
"enum": [
"prefix",
"semantic"
],
"description": "How this similar Task was found. `prefix` is a text match on the Task name; `semantic` is an embedding-based match on meaning.",
"example": "prefix"
}
}
}
}
}
}
}
}
},
"examples": {
"Default": {
"summary": "Default",
"value": {
"results": [
{
"task_name": "Review quarterly performance reports for direct reports",
"task_id": "a1b2c3d4-5e6f-7081-9abc-def012345678",
"status": "valid",
"rejection_reasons": [],
"similar_tasks": []
},
{
"task_name": "Run",
"task_id": null,
"status": "rejected:formatting",
"rejection_reasons": [
{
"code": "too_short"
},
{
"code": "too_few_words"
}
],
"similar_tasks": []
}
]
}
},
"WithSimilar": {
"summary": "Valid with an advisory similar Task",
"value": {
"results": [
{
"task_name": "Write quarterly budget report",
"task_id": "7f1e2d3c-4b5a-6978-8c7d-6e5f4a3b2c1d",
"status": "valid",
"rejection_reasons": [],
"similar_tasks": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Prepare quarterly budget reports",
"similarity": 0.93,
"match_type": "prefix"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/tasks": {
"post": {
"tags": [
"ExportTasks"
],
"summary": "Export Tasks",
"description": "\n\nExport the information for all Tasks in the system. Results are paginated\nwith a default limit of 50,000. This limit is required due to the large\ndataset size. Setting a lower limit would not improve performance and is\ntherefore not supported.\n\nUse the `include` query parameter to expand each Task with AI impact\ninformation, its position in the work taxonomy, and/or the Jobs it is\nassigned to. Use `filters` to narrow the set of Tasks returned.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ai_impact",
"hierarchy",
"task_source",
"enrichment_status",
"linked_jobs"
]
}
},
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.\n\n- `ai_impact` — includes AI impact level and rationale per task.\n- `hierarchy` — includes the task's position in the work taxonomy (domain → subdomain → cluster → canonical task).\n- `task_source` — distinguishes standard work-taxonomy Tasks (`vocabulary`) from Tasks created through the `POST /tasks` endpoint (`custom`).\n- `enrichment_status` — includes the status of the task's asynchronous AI-impact enrichment (`pending`, `complete`, or `failed`).\n- `linked_jobs` — includes the complete set of Jobs each Task is assigned to, each with its `validation_state`, `weekly_hours`, and `linked_skills` (Skill ID and name). Assignments rejected via feedback are excluded; a Task that is not assigned to any Job has an empty list. Use the `external_vendor` query parameter to display the linked Skill names in an external vendor vocabulary (`external_vendor` is only accepted together with this include). Only accepted when `limit` is set to at most 200 — use `starting_after` pagination for larger reads.\n",
"example": [
"ai_impact",
"hierarchy"
]
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"default": 50000,
"description": "Number of Tasks to return per page.",
"example": 50000
},
"starting_after": {
"type": "string",
"format": "slug",
"maxLength": 100,
"description": "The `task_id` of the last Task seen. Used for cursor-based pagination. Omit on the first request.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Tasks.",
"items": {
"anyOf": [
{
"type": "object",
"title": "task_id_is_in_list",
"required": [
"filter",
"task_ids"
],
"properties": {
"filter": {
"type": "string",
"enum": [
"task_id_is_in_list"
],
"description": "Filter type.",
"example": "task_id_is_in_list"
},
"task_ids": {
"type": "array",
"description": "List of task IDs to include.",
"items": {
"type": "string",
"format": "slug",
"maxLength": 100
},
"example": [
"56dcdb53-264e-f380-50bf-5179e2d082af",
"b7d08d86-e744-1807-4a56-a08f854e9b2e"
]
}
}
},
{
"type": "object",
"title": "canonical_task_id_is_in_list",
"required": [
"filter",
"canonical_task_ids"
],
"properties": {
"filter": {
"type": "string",
"enum": [
"canonical_task_id_is_in_list"
],
"description": "Filter type.",
"example": "canonical_task_id_is_in_list"
},
"canonical_task_ids": {
"type": "array",
"description": "List of canonical task IDs. Only Tasks belonging to these canonical tasks are included.",
"items": {
"type": "string",
"format": "slug",
"maxLength": 100
},
"example": [
"2213cfe4-d3dd-f568-b7e9-be8c0089f9f3",
"8f0a44f1-91f9-46c9-a58a-9a0c3ac33c2b"
]
}
}
}
]
}
}
}
},
"examples": {
"Default": {
"summary": "Default",
"value": {
"limit": 50000
}
},
"WithFilter": {
"summary": "Filtered by task IDs",
"value": {
"limit": 50000,
"filters": [
{
"filter": "task_id_is_in_list",
"task_ids": [
"56dcdb53-264e-f380-50bf-5179e2d082af",
"b7d08d86-e744-1807-4a56-a08f854e9b2e"
]
}
]
}
},
"WithCanonicalTaskFilter": {
"summary": "Filtered by canonical task IDs",
"value": {
"limit": 50000,
"filters": [
{
"filter": "canonical_task_id_is_in_list",
"canonical_task_ids": [
"2213cfe4-d3dd-f568-b7e9-be8c0089f9f3",
"8f0a44f1-91f9-46c9-a58a-9a0c3ac33c2b"
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The cursor value to use as `starting_after` on the next request. Only present when `has_next` is `true`.",
"type": "string",
"format": "slug",
"maxLength": 100,
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"records": {
"description": "List of Task records.",
"type": "array",
"items": {
"type": "object",
"required": [
"task_id",
"task_name"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task_name": {
"type": "string",
"description": "Name/description of the task.",
"example": "Write unit tests for backend services"
},
"ai_impact": {
"description": "AI impact level and rationale for this task. Only present when `include=ai_impact`.",
"allOf": [
{
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
}
]
},
"hierarchy": {
"description": "Position of this task in the work taxonomy (domain → subdomain → cluster → canonical task). Only present when `include=hierarchy`. Either all fields are populated, or all fields are `null` when the task has no position in the work taxonomy.",
"allOf": [
{
"type": "object",
"nullable": true,
"description": "The position of this task in the task hierarchy\n(domain → subdomain → cluster → canonical task).\nEither all fields are populated, or all fields are null\nwhen the task has no position in the task hierarchy.\n",
"properties": {
"domain_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy domain.",
"example": "Computer Science"
},
"domain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy domain.",
"example": "576132d7-83d2-bcba-78db-e14c073409dd"
},
"subdomain_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy subdomain.",
"example": "Software Engineering"
},
"subdomain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy subdomain.",
"example": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab"
},
"cluster_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy cluster.",
"example": "Monitoring and alerting"
},
"cluster_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy cluster.",
"example": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1"
},
"canonical_task_name": {
"type": "string",
"nullable": true,
"description": "Name of the task hierarchy canonical task.",
"example": "Configure observability monitoring tools"
},
"canonical_task_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy canonical task.",
"example": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
}
}
}
]
},
"task_source": {
"description": "Origin of the task. Only present when `include=task_source`.",
"allOf": [
{
"type": "string",
"description": "Origin of the Task.\n\n`vocabulary` = a Task from the standard work taxonomy (the default for\npipeline-extracted Tasks). `custom` = a Task created through the\n`POST /tasks` endpoint.\n",
"enum": [
"vocabulary",
"custom"
],
"example": "vocabulary"
}
]
},
"enrichment_status": {
"description": "Status of the task's asynchronous AI-impact enrichment. Only present when `include=enrichment_status`.",
"allOf": [
{
"type": "string",
"description": "Status of the asynchronous AI-impact enrichment for this Task.\n\n`pending` = enrichment is queued or in progress. `complete` = enrichment\nfinished and AI-impact data is available. `failed` = enrichment failed after\nretries. Pipeline-extracted Tasks default to `complete`.\n",
"enum": [
"pending",
"complete",
"failed"
],
"example": "complete"
}
]
},
"linked_jobs": {
"type": "array",
"description": "The complete set of Jobs this task is assigned to. Only present when `include=linked_jobs`. Assignments rejected via feedback are excluded; a task that is not assigned to any Job has an empty list.",
"items": {
"type": "object",
"title": "linked_job",
"required": [
"external_id",
"validation_state",
"weekly_hours",
"linked_skills"
],
"properties": {
"external_id": {
"type": "string",
"description": "The external identifier of the Job the Task is assigned to.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated"
],
"description": "This field indicates whether the Task assignment is validated or still in the suggested state. Assignments rejected via feedback are excluded from `linked_jobs`.\n",
"example": "validated"
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this Task per week on this Job.",
"example": 6
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this Task on this Job, with Skill ID and name.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
}
}
}
}
}
}
}
}
},
"examples": {
"Default": {
"summary": "Default",
"value": {
"records": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services"
},
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task_name": "Review pull requests for the analytics team"
}
],
"has_next": false
}
},
"WithIncludes": {
"summary": "With includes",
"value": {
"records": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services",
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"hierarchy": {
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
},
"task_source": "vocabulary",
"enrichment_status": "complete"
},
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task_name": "Review pull requests for the analytics team",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment for code quality assessment"
},
"hierarchy": {
"domain_name": null,
"domain_id": null,
"subdomain_name": null,
"subdomain_id": null,
"cluster_name": null,
"cluster_id": null,
"canonical_task_name": null,
"canonical_task_id": null
},
"task_source": "custom",
"enrichment_status": "pending"
}
],
"has_next": true,
"next_starting_after": "b7d08d86-e744-1807-4a56-a08f854e9b2e"
}
},
"WithLinkedJobs": {
"summary": "With linked Jobs",
"value": {
"records": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task_name": "Write unit tests for backend services",
"linked_jobs": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"validation_state": "validated",
"weekly_hours": 6,
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "b7f3f24f-53da-4f04-9c0e-cb0f0246676e",
"skill": "Unit Testing"
}
]
},
{
"external_id": "c1229eb1-2b8b-4b6a-91b1-9f6dd1dbe1a4",
"validation_state": "suggested",
"weekly_hours": 2,
"linked_skills": []
}
]
},
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task_name": "Review pull requests for the analytics team",
"linked_jobs": []
}
],
"has_next": false
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}/matching_vacancies": {
"post": {
"tags": [
"Vacancy Matching"
],
"summary": "Get the top matching Vacancies for an Employee",
"description": "You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used. Only active Vacancies are included in the results.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the titles and descriptions of the matched Vacancies.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity",
"location",
"score_breakdown",
"match_feedback"
]
},
"example": [
"custom_properties",
"entity",
"location"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"filter",
"multi_max_geo_distances"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distances`. This filter cannot be used together with the `max_geo_distance` filter",
"enum": [
"multi_max_geo_distances"
],
"example": "multi_max_geo_distances"
},
"multi_max_geo_distances": {
"type": "array",
"description": "List of locations and maximum distances. The list must contain at least one item and at most three.",
"items": {
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"max_geo_distance",
"location"
],
"properties": {
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
}
}
},
{
"type": "object",
"title": "language",
"required": [
"filter",
"max_overqualification",
"max_underqualification"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all Employees for which the language level is not within the range defined by `level - max_underqualification` and `level + max_overqualification`, with `level` being the language level of Vacancies. If `level - max_underqualification <= 0`, the filter does not filter any entity without the language.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be above the required level of the Vacancy.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be below the required level of the Vacancy. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "multi_max_geo_distances",
"multi_max_geo_distances": [
{
"max_geo_distance": 20,
"location": {
"lat": 51.34,
"lng": 3.15
}
},
{
"max_geo_distance": 20,
"location": {
"country": "BE",
"postal_code": 9000
}
}
]
},
{
"filter": "language",
"max_overqualification": 2,
"max_underqualification": 1
},
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"description": "List of weights to be applied during matching",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"value": 0.1,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"value": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"value": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"value": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"value": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"value": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"value": 0.04,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
},
{
"type": "object",
"properties": {
"used_event_types": {
"type": "array",
"description": "Type of the Skill Event. 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](/technology/skill_events/).",
"items": {
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"goal",
"project",
"ticket",
"merge_request",
"certificate",
"skill_notes"
],
"example": "working_history"
},
"example": [
"working_history",
"education_history"
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the Job title and Job description of the matching Vacancy.",
"required": [
"job_title",
"job_description"
],
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
}
}
}
]
}
}
}
},
{
"title": "Location",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the location of the matching entity.",
"required": [
"location"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
}
}
}
},
{
"title": "Score Breakdown",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The *geo distance* weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in* weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you are calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in list* weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains* weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains element* weight applies the specified\nscore boosting effect (`value`) to all the entities for which the\nvalues list of a Custom Property contains a given value.\n",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Is a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *list overlap* weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"contribution": 0.53
},
{
"weight": "desired_functions",
"contribution": 0.03
},
{
"weight": "geo_distance",
"contribution": 0.02,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"contribution": 0.03,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"contribution": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"contribution": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"contribution": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"contribution": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"contribution": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"contribution": 0.02,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
}
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
},
"entityExample": {
"summary": "Entity Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_title": "Software Engineer",
"job_description": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus."
}
]
}
},
"locationExample": {
"summary": "Location Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"location": [
{
"lat": 51.0216707,
"lng": 3.6887328
}
]
}
]
}
},
"scoreBreakdownExample": {
"summary": "Score Breakdown Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"weights": [
{
"weight": "skills_match",
"contribution": 0.53
},
{
"weight": "desired_functions",
"contribution": 0.03
},
{
"weight": "geo_distance",
"contribution": 0.02,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"contribution": 0.03,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"contribution": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"contribution": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"contribution": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"contribution": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"contribution": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"contribution": 0.02,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacency_score": 0.8
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/vacancies/{vacancy_external_id}/match": {
"get": {
"tags": [
"Vacancy Matching"
],
"summary": "Get the match score between an Employee and a Vacancy",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "vacancy_external_id",
"required": true,
"description": "Unique external ID linked to this Vacancy, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"match_score": 0.87657
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"match_score": 0.87657,
"missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a39c3505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"present_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/vacancies/{external_id}/matching_employees": {
"post": {
"tags": [
"Vacancy Matching"
],
"summary": "Get the top matching Employees for a Vacancy.",
"description": "You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the assigned positions and working histories of the matched Employees.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity",
"location",
"score_breakdown",
"match_feedback"
]
},
"example": [
"custom_properties",
"entity",
"location"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"filter",
"multi_max_geo_distances"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distances`. This filter cannot be used together with the `max_geo_distance` filter",
"enum": [
"multi_max_geo_distances"
],
"example": "multi_max_geo_distances"
},
"multi_max_geo_distances": {
"type": "array",
"description": "List of locations and maximum distances. The list must contain at least one item and at most three.",
"items": {
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"max_geo_distance",
"location"
],
"properties": {
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
}
}
},
{
"type": "object",
"title": "language",
"required": [
"filter",
"max_overqualification",
"max_underqualification"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all Employees for which the language level is not within the range defined by `level - max_underqualification` and `level + max_overqualification`, with `level` being the language level of Vacancies. If `level - max_underqualification <= 0`, the filter does not filter any entity without the language.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be above the required level of the Vacancy.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be below the required level of the Vacancy. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "multi_max_geo_distances",
"multi_max_geo_distances": [
{
"max_geo_distance": 20,
"location": {
"lat": 51.34,
"lng": 3.15
}
},
{
"max_geo_distance": 20,
"location": {
"country": "BE",
"postal_code": 9000
}
}
]
},
{
"filter": "language",
"max_overqualification": 2,
"max_underqualification": 1
},
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"description": "List of weights to be applied during matching",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"value": 0.1,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"value": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"value": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"value": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"value": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"value": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"value": 0.04,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the assigned position and working history of the matching Employee.",
"required": [
"assigned_position",
"working_history"
],
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
}
}
}
]
}
}
}
},
{
"title": "Location",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the location of the matching entity.",
"required": [
"location"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
}
}
}
},
{
"title": "Score Breakdown",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The *geo distance* weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in* weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you are calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in list* weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains* weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains element* weight applies the specified\nscore boosting effect (`value`) to all the entities for which the\nvalues list of a Custom Property contains a given value.\n",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Is a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *list overlap* weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"contribution": 0.53
},
{
"weight": "desired_functions",
"contribution": 0.03
},
{
"weight": "geo_distance",
"contribution": 0.02,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"contribution": 0.03,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"contribution": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"contribution": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"contribution": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"contribution": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"contribution": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"contribution": 0.02,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
}
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
},
"entityExample": {
"summary": "Entity Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"assigned_position": "Python Developer",
"working_history": [
{
"job_title": "HR Manager",
"start_date": "2018-09-05",
"end_date": "2020-06-17",
"company": "TechWolf BV",
"job_description": "Manage the HR department and perform workforce planning"
}
]
}
]
}
},
"locationExample": {
"summary": "Location Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"location": [
{
"lat": 51.0216707,
"lng": 3.6887328
}
]
}
]
}
},
"scoreBreakdownExample": {
"summary": "Score Breakdown Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"weights": [
{
"weight": "skills_match",
"contribution": 0.53
},
{
"weight": "desired_functions",
"contribution": 0.03
},
{
"weight": "geo_distance",
"contribution": 0.02,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"contribution": 0.03,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"contribution": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"contribution": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"contribution": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"contribution": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"contribution": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"contribution": 0.02,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"results": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacency_score": 0.8
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/recommended_courses": {
"get": {
"tags": [
"Course Recommendations"
],
"summary": "Get Course recommendations to improve the Skill Profile of an Employee",
"deprecated": true,
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The response format determines which additional data is returned along with the matches. Currently only supports the 'simple' format.",
"example": "simple",
"schema": {
"type": "string",
"enum": [
"simple"
],
"default": "simple"
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"properties": {
"score": {
"type": "number",
"format": "float",
"description": "The match score between an Employee and a Course, expressed as a number between 0 and 1.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Course Recommendations"
],
"summary": "Get Course recommendations to improve the Skill Profile of an Employee",
"description": "Courses that are connected through a SkillEvent with the Employee, indicating that the Employee has already taken the Course, are excluded from the recommendations. Additionally, Courses of which the `active` attribute is set to `false` are filtered out as well.\n",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the recommendation."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "use_adjacent_skills",
"schema": {
"type": "boolean",
"default": true,
"example": false
},
"description": "If set to `true`, Course recommendations will consider adjacent Skills in addition to literal Skill overlap. If set to `false`, recommendations will be based solely on literal Skill overlap."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the titles and descriptions of the recommended Courses.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"filters",
"weights"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
}
]
}
},
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"properties": {
"score": {
"type": "number",
"format": "float",
"description": "The match score between an Employee and a Course, expressed as a number between 0 and 1.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"score": {
"type": "number",
"format": "float",
"description": "The match score between an Employee and a Course, expressed as a number between 0 and 1.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"relevant_skills": {
"type": "array",
"description": "A list of Skills that the Course provides that are relevant for the Skill Profile of the Employee.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"additional_skills": {
"type": "array",
"description": "A list of extra Skills that the Course provides that are unrelated to the Skill Profile of the Employee.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"score": {
"type": "number",
"format": "float",
"description": "The match score between an Employee and a Course, expressed as a number between 0 and 1.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"score": {
"type": "number",
"format": "float",
"description": "The match score between an Employee and a Course, expressed as a number between 0 and 1.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"results": [
{
"score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"results": [
{
"score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"relevant_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"additional_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
}
]
}
]
}
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": {
"results": [
{
"score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"custom_properties": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
},
"entityExample": {
"summary": "Entity Example",
"value": {
"results": [
{
"score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"course_title": "Computer Science 101",
"course_description": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists."
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses": {
"post": {
"tags": [
"Course Recommendations"
],
"summary": "Get Course recommendations to bridge the Skill gap between an Employee and a Vacancy",
"description": "Courses that are connected through a SkillEvent with the Employee, indicating that the Employee has already taken the Course, are excluded from the recommendations. Additionally, Courses of which the `active` attribute is set to `false` are filtered out as well.\n",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "vacancy_external_id",
"required": true,
"description": "Unique external ID linked to this Vacancy, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the recommendation."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "use_adjacent_skills",
"schema": {
"type": "boolean",
"default": true,
"example": false
},
"description": "If set to `true`, Course recommendations will consider adjacent Skills in addition to literal Skill overlap. If set to `false`, recommendations will be based solely on literal Skill overlap."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the titles and descriptions of the recommended Courses.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"filters",
"weights"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
}
]
}
},
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"addressed_skill_gap": {
"type": "array",
"description": "A list of Skills of the Skill gap.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"properties": {
"relevant_course_skills": {
"type": "array",
"description": "A list of Course Skills that are relevant for the Skill gap Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
}
]
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"addressed_skill_gap": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"relevant_course_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
]
}
]
}
]
}
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"custom_properties": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
},
"entityExample": {
"summary": "Entity Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"course_title": "Computer Science 101",
"course_description": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists."
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses": {
"post": {
"tags": [
"Course Recommendations"
],
"summary": "Get Course recommendations to bridge the Skill gap between an Employee and a Job",
"description": "Courses that are connected through a SkillEvent with the Employee, indicating that the Employee has already taken the Course, are excluded from the recommendations. Additionally, Courses of which the `active` attribute is set to `false` are filtered out as well.\n",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the recommendation."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "use_adjacent_skills",
"schema": {
"type": "boolean",
"default": true,
"example": false
},
"description": "If set to `true`, Course recommendations will consider adjacent Skills in addition to literal Skill overlap. If set to `false`, recommendations will be based solely on literal Skill overlap."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the titles and descriptions of the recommended Courses.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"addressed_skill_gap": {
"type": "array",
"description": "A list of Skills of the Skill gap.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"properties": {
"relevant_course_skills": {
"type": "array",
"description": "A list of Course Skills that are relevant for the Skill gap Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
}
]
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"addressable_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The score of the Course recommendation.",
"example": 0.8
},
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"addressed_skill_gap": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"relevant_course_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
]
}
]
}
]
}
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"custom_properties": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
},
"entityExample": {
"summary": "Entity Example",
"value": {
"results": [
{
"addressable_score": 0.8,
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"course_title": "Computer Science 101",
"course_description": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists."
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies/{external_id}/matching_employees": {
"post": {
"tags": [
"External Company Matching"
],
"summary": "Find the best Employees for a given External Company",
"description": "You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "language",
"required": [
"filter",
"max_overqualification",
"max_underqualification"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the language level is not within the range defined by `level - max_underqualification` and `level + max_overqualification`. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "language",
"max_overqualification": 2,
"max_underqualification": 1
},
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"description": "List of weights to be applied during matching",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "custom_property",
"value": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"value": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"value": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"value": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"value": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"value": 0.04,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"description": "A match result between an Employee and an External Company.",
"type": "object",
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"company_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "c350500-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The maximum matching rate between an Employee and an External Company, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
},
"matching_vacancies": {
"description": "An overview of the match results between an Employee and the most recent open positions for this External Company sorted by match score.",
"type": "array",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager",
"description": "Title of the Vacancy."
}
}
}
]
},
"example": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "a4003805-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.9,
"job_title": "Business Analyst"
},
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b4003805-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.7,
"job_title": "Data Scientist"
}
]
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}/matching_companies": {
"post": {
"tags": [
"External Company Matching"
],
"summary": "Find the best External Companies for a given Employee",
"description": "You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "language",
"required": [
"filter",
"max_overqualification",
"max_underqualification"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the language level is not within the range defined by `level - max_underqualification` and `level + max_overqualification`. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "language",
"max_overqualification": 2,
"max_underqualification": 1
},
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"description": "List of weights to be applied during matching",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"value": 0.1,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"value": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"value": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"value": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"value": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"value": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"value": 0.04,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"description": "A match result between an Employee and an External Company.",
"type": "object",
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"company_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "c350500-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The maximum matching rate between an Employee and an External Company, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
},
"matching_vacancies": {
"description": "An overview of the match results between an Employee and the most recent open positions for this External Company sorted by match score.",
"type": "array",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager",
"description": "Title of the Vacancy."
}
}
}
]
},
"example": [
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "a4003805-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.9,
"job_title": "Business Analyst"
},
{
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"vacancy_id": "b4003805-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.7,
"job_title": "Data Scientist"
}
]
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/match_assigned_position": {
"post": {
"tags": [
"ExportEmployeeAssignedPosition"
],
"summary": "Get the match scores between Employees and their assigned position in bulk.",
"description": "Employees without an assigned position will be included in the result, with `job_id=null` and `score=0.0`.",
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Employees to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Employee to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the Employees.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesExplained` schema for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
},
"records": {
"description": "A list containing the match of each Employee with their assigned position, limited by the `limit` parameter.",
"type": "array",
"items": {
"type": "object",
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
},
"records": {
"description": "A list containing the match of each Employee with their assigned position, limited by the `limit` parameter.",
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
},
"records": {
"description": "A list containing the match of each Employee with their assigned position, limited by the `limit` parameter.",
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"has_next": true,
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002",
"records": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"has_next": true,
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002",
"records": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a39c3505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"present_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"has_next": true,
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002",
"records": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/match_assigned_position": {
"get": {
"tags": [
"Job Matching"
],
"summary": "Get the match score between an Employee and their assigned position",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesExplained` schema for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
{
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a39c3505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"present_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{external_id}/market_alignment": {
"get": {
"tags": [
"Job Matching"
],
"summary": "Get the match scores between a Job and its market Skill Profiles",
"description": "We calculate two types of match scores for every Skill Profile in the market, \nlinked to a peer group. More information about external market Skill Profiles \ncan be found in the documentation of the relevant [endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-skill-profiles). \nThe Job to peer score indicates how well the Job Skill Profile covers the Skill \nrequirement of the external market Skill Profile of a certain peer group. The \nsecond score is the peer to Job score, which indicates how well the market \nSkill Profile of a peer group covers the Skill requirements of the Job Skill \nProfile. The higher the score, the better the match.\n",
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"description": "A match result between a Job and its market Skill Profiles.",
"type": "object",
"required": [
"job_id",
"alignment_scores"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"alignment_scores": {
"description": "The market alignment scores for the Job, for every peer Skill Profile.",
"type": "array",
"items": {
"type": "object",
"required": [
"peer_group",
"job_to_peer_score",
"peer_to_job_score"
],
"properties": {
"peer_group": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the peer group."
},
"job_to_peer_score": {
"description": "The matching score between the Job and the peer Skill Profile, expressed as a number between 0 and 1. This indicates how well the Job Skill Profile covers the Skill requirements of the peer Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"peer_to_job_score": {
"description": "The matching score between the peer Skill Profile and the Job, expressed as a number between 0 and 1. This indicates how well a peer Skill Profile covers the Skill requirements of the Job Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
}
}
},
"example": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8
}
]
}
}
},
{
"title": "Explained",
"description": "A match result between a Job and its market Skill Profiles.",
"type": "object",
"required": [
"job_id",
"alignment_scores"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"alignment_scores": {
"description": "The market alignment scores for the Job, for every peer Skill Profile.",
"type": "array",
"items": {
"type": "object",
"required": [
"peer_group",
"job_to_peer_score",
"peer_to_job_score",
"job_missing_skills",
"peer_missing_skills",
"overlapping_skills"
],
"properties": {
"peer_group": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the peer group.",
"example": "B2B"
},
"job_to_peer_score": {
"description": "The matching score between the Job and the peer Skill Profile, expressed as a number between 0 and 1. This indicates how well the Job Skill Profile covers the Skill requirements of the peer Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"peer_to_job_score": {
"description": "The matching score between the peer Skill Profile and the Job, expressed as a number between 0 and 1. This indicates how well a peer Skill Profile covers the Skill requirements of the Job Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"job_missing_skills": {
"description": "The list of Skills that are required by the peer Skill Profile but are missing from the Job Skill Profile.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"peer_missing_skills": {
"description": "The list of Skills that are required by the Job Skill Profile but are missing from the peer Skill Profile.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"overlapping_skills": {
"description": "The list of Skills that are either directly present or are sufficiently adjacent to present Skills in both the Job Skill Profile and the peer Skill Profile.",
"type": "array",
"items": {
"type": "object",
"required": [
"skill_name",
"skill_id",
"job_adjacent_skill_name",
"job_adjacent_skill_id",
"job_adjacency_score",
"peer_adjacent_skill_name",
"peer_adjacent_skill_id",
"peer_adjacency_score"
],
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_adjacent_skill_name": {
"type": "string",
"minLength": 1,
"description": "The name of the adjacent Skill in the Job Skill Profile."
},
"job_adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"description": "The universally unique ID of the adjacent Skill in the Job Skill Profile, 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The adjacency score between the Skill and the adjacent Skill in the Job Skill Profile."
},
"peer_adjacent_skill_name": {
"type": "string",
"minLength": 1,
"description": "The name of the adjacent Skill in the peer Skill Profile."
},
"peer_adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"description": "The universally unique ID of the adjacent Skill in the peer Skill Profile, 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"peer_adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The adjacency score between the Skill and the adjacent Skill in the peer Skill Profile."
}
}
}
}
}
},
"example": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9,
"job_missing_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
}
],
"peer_missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"overlapping_skills": [
{
"skill_name": "SQL",
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"job_adjacent_skill_name": "PostgreSQL",
"job_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"job_adjacency_score": 0.7,
"peer_adjacent_skill_name": "SQL",
"peer_adjacent_skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"peer_adjacency_score": 1
}
]
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8,
"job_missing_skills": [
{
"skill_name": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
],
"peer_missing_skills": [
{
"skill_name": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
],
"overlapping_skills": [
{
"skill_name": "JavaScript",
"skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacent_skill_name": "JavaScript",
"job_adjacent_skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacency_score": 1,
"peer_adjacent_skill_name": "TypeScript",
"peer_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"peer_adjacency_score": 0.7
}
]
}
]
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"alignment_scores": [
{
"peer_group": "B2B",
"jobn_to_peer_score": 0.85,
"peer_to_job_score": 0.9
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8
}
]
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"alignment_scores": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9,
"job_missing_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
}
],
"peer_missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"overlapping_skills": [
{
"skill_name": "SQL",
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"job_adjacent_skill_name": "PostgreSQL",
"job_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"job_adjacency_score": 0.7,
"peer_adjacent_skill_name": "SQL",
"peer_adjacent_skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"peer_adjacency_score": 1
}
]
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8,
"job_missing_skills": [
{
"skill_name": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
],
"peer_missing_skills": [
{
"skill_name": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
],
"overlapping_skills": [
{
"skill_name": "JavaScript",
"skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacent_skill_name": "JavaScript",
"job_adjacent_skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacency_score": 1,
"peer_adjacent_skill_name": "TypeScript",
"peer_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"peer_adjacency_score": 0.7
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/jobs/{job_external_id}/match": {
"get": {
"tags": [
"Job Matching"
],
"summary": "Get the match score between an Employee and a Job",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesExplained` schema for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
{
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a39c3505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"present_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}/matching_jobs": {
"post": {
"tags": [
"Job Matching"
],
"summary": "Get the top matching Jobs for an Employee",
"description": "Get an export of the best matching Jobs for an Employee. Only active Jobs are included in the export. The Employee's current Job is excluded from the results.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "include_overqualified",
"schema": {
"type": "boolean",
"example": true,
"default": true
},
"description": "When set to true, includes matches where the Employee is overqualified for the Job. Overqualified matches are those where the Employee's skill level significantly exceeds the requirements. This filter will only work if proficiency matching is enabled on the tenant."
},
{
"in": "query",
"name": "min_critical_skills_match_ratio",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"nullable": true,
"example": 0.8,
"default": null
},
"description": "The minimum ratio of critical skills that must be matched. Only matches meeting or exceeding this ratio will be returned. When not provided, no critical skills ratio filtering is applied. This filter will only work if the \"use_criticalities\" feature flag is enabled."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the name of the Job and the external ID of the corresponding Job Family.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesSimple` and `PropertiesExplained` schemas for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the name of the Job and the external ID of the corresponding Job Family.",
"required": [
"job_title",
"job_description",
"job_name"
],
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Job."
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
},
{
"title": "PropertiesSimple",
"description": "Match results with skill properties in simple format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"description": "A match result between an Employee and a Job, including overqualified status.",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
}
}
}
},
{
"title": "PropertiesExplained",
"description": "Match results with skill properties in explained format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_values": [
"B",
"C"
]
}
]
}
]
},
"entityExample": {
"summary": "Entity Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_name": "Software Engineer"
}
]
},
"explainedExample": {
"summary": "Explained Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
},
"propertiesSimpleExample": {
"summary": "Matching with properties simple example",
"value": {
"results": [
{
"employee_id": "E-123",
"job_id": "J-456",
"score": 0.58,
"overqualified": false
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"results": [
{
"employee_id": "E-123",
"job_id": "J-456",
"score": 0.58,
"overqualified": false,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{external_id}/matching_employees": {
"post": {
"tags": [
"Job Matching"
],
"summary": "Get the top matching Employees for a Job",
"description": "Get an export of the best matching Employees for a Job. Only active Employees are included in the export. The Employees that have the Job assigned are excluded from the results.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "include_overqualified",
"schema": {
"type": "boolean",
"example": true,
"default": true
},
"description": "When set to true, includes matches where the Employee is overqualified for the Job. Overqualified matches are those where the Employee's skill level significantly exceeds the requirements. This filter will only work if proficiency matching is enabled on the tenant."
},
{
"in": "query",
"name": "min_critical_skills_match_ratio",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"nullable": true,
"example": 0.8,
"default": null
},
"description": "The minimum ratio of critical skills that must be matched. Only matches meeting or exceeding this ratio will be returned. When not provided, no critical skills ratio filtering is applied. This filter will only work if the \"use_criticalities\" feature flag is enabled."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the assigned position and working history of the Employee.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesSimple` and `PropertiesExplained` schemas for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"type": "integer",
"description": "Number of available results for the provided parameters.",
"example": 1
},
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the assigned position and working history of the Employee.",
"required": [
"assigned_position",
"working_history"
],
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
},
{
"title": "PropertiesSimple",
"description": "Match results with skill properties in simple format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"description": "A match result between an Employee and a Job, including overqualified status.",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
}
}
}
},
{
"title": "PropertiesExplained",
"description": "Match results with skill properties in explained format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
},
"entityExample": {
"summary": "Entity Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"assigned_position": "Python Developer",
"working_history": [
{
"job_title": "HR Manager",
"start_date": "2018-09-05",
"end_date": "2020-06-17",
"company": "TechWolf BV",
"job_description": "Manage the HR department and perform workforce planning"
}
]
}
]
},
"explainedExample": {
"summary": "Explained Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
},
"propertiesSimpleExample": {
"summary": "Matching with properties simple example",
"value": {
"results": [
{
"employee_id": "E-123",
"job_id": "J-456",
"score": 0.58,
"overqualified": false
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"results": [
{
"employee_id": "E-123",
"job_id": "J-456",
"score": 0.58,
"overqualified": false,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{external_id}/matching_source_jobs": {
"post": {
"tags": [
"Job Matching"
],
"summary": "Get the most relevant jobs from which can be hired for the given job.",
"description": "Identify the most relevant jobs from which potential candidates can be hired to fill the given job's skill requirements. Relevant for succession planning. Only active Jobs are included in the results.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the job name of the source Job.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a source Job, including the Custom Properties of the source Job.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a source Job, including the name of the source Job.",
"required": [
"job_name"
],
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Job."
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a source Job, including an explanation of what Skills are missing and what Skills are present in the source Job's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the source Job does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the source Job possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"source_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"source_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
},
"entityExample": {
"summary": "Entity Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"source_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_name": "Software Engineer"
}
]
},
"explainedExample": {
"summary": "Explained Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"source_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{external_id}/matching_target_jobs": {
"post": {
"tags": [
"Job Matching"
],
"summary": "Get the most relevant jobs to which can be moved from the given job.",
"description": "Identify the most relevant jobs to which employees in the given job can be moved based on job skill requirements. Relevant for career development and internal mobility opportunities. Only active Jobs are included in the results.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the job name of the target Job.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a target Job, including the Custom Properties of the target Job.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a target Job, including the name of the target Job.",
"required": [
"job_name"
],
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Job."
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a target Job, including an explanation of what Skills are missing and what Skills are present in the target Job's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the target Job requires, but the provided Job does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the target Job requires and the provided Job possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
},
"entityExample": {
"summary": "Entity Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_name": "Software Engineer"
}
]
},
"explainedExample": {
"summary": "Explained Example",
"value": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match": {
"get": {
"tags": [
"Job Matching"
],
"summary": "Get the task-based match score between two Jobs",
"description": "Get the symmetric task-based match score between two Jobs, computed from their task profiles. The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions, and is symmetric: swapping the two Jobs yields the same score.",
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "other_job_external_id",
"required": true,
"description": "Unique external ID linked to the target Job to compare against, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"description": "A task-based match result between two Jobs.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"title": "Explained",
"allOf": [
{
"title": "Simple",
"description": "A task-based match result between two Jobs.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result between two Jobs, including a per-Task breakdown of the match. Each Task on either side of the pair is reported once per direction as either present (it has a sufficiently similar Task on the other side) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task on the other side of the pair.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task on the other side of the pair.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"job_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.42
}
},
"explainedExample": {
"summary": "With response_format=explained",
"value": {
"job_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.42,
"present_tasks": [
{
"task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"task_name": "Write unit tests for backend services",
"direction": "source_to_target",
"adjacent_task_id": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
"adjacent_task_name": "Add automated test coverage for backend services",
"adjacency_score": 0.91,
"hours_share": 0.6
}
],
"missing_tasks": [
{
"task_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"task_name": "Operate legacy mainframe for payroll processing",
"direction": "target_to_source"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks": {
"post": {
"tags": [
"Job Matching"
],
"summary": "Get the most task-relevant Jobs to the given Job",
"description": "Identify the Jobs whose task profiles best match the given Job's task profile, ranked by symmetric task-match score (descending). The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions. Whether suggested tasks contribute alongside validated tasks is governed by the tenant's `tasks_on_jobs` setting.\nResults are subject to a result-level minimum score: matches scoring below 0.30 are not returned. A Job whose best match falls below this floor returns an empty result list rather than a weak, potentially misleading ranking.",
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional attributes to include per result. This query parameter can be added multiple times to include more attributes. `entity` adds the target Job's `job_name`; `custom_properties` adds the target Job's custom properties.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "Top matching Jobs, ranked by `score` descending.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A task-based match result between two Jobs.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result, optionally enriched with attributes requested via the `include` query parameter.",
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the target Job. Present when `include=entity`."
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "Top matching Jobs, ranked by `score` descending, each with a per-Task breakdown.",
"items": {
"title": "Explained",
"allOf": [
{
"title": "Simple",
"description": "A task-based match result between two Jobs.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result between two Jobs, including a per-Task breakdown of the match. Each Task on either side of the pair is reported once per direction as either present (it has a sufficiently similar Task on the other side) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task on the other side of the pair.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task on the other side of the pair.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"results": [
{
"job_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
},
{
"job_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "c1203505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.41231
}
]
}
},
"includeExample": {
"summary": "With include=entity and include=custom_properties",
"value": {
"results": [
{
"job_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_name": "Senior Data Engineer",
"custom_properties": [
{
"property_name": "department",
"property_value": "Engineering"
}
]
}
]
}
},
"explainedExample": {
"summary": "With response_format=explained",
"value": {
"results": [
{
"job_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"present_tasks": [
{
"task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"task_name": "Write unit tests for backend services",
"direction": "source_to_target",
"adjacent_task_id": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
"adjacent_task_name": "Add automated test coverage for backend services",
"adjacency_score": 0.91,
"hours_share": 0.6
}
],
"missing_tasks": [
{
"task_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"task_name": "Operate legacy mainframe for payroll processing",
"direction": "target_to_source"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/tasks/matching": {
"post": {
"tags": [
"Task Matching"
],
"summary": "Get the task-based match score between two task sets",
"description": "Get the symmetric task-based match score between two explicit sets of tasks, computed directly from their task embeddings. Unlike the job task-match endpoints, the two sides are caller-supplied task lists rather than job profiles. Each task may carry an optional weekly_hours weight, so tasks with more weekly hours contribute proportionally more to the score; when weekly_hours is omitted the tasks are weighted equally, reducing to an unweighted mean. The score is a continuous task similarity, harmonic-meaned across both directions, and is symmetric. Swapping the two sets yields the same score.",
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "A pair of task sets to compare. Both sides are explicit lists of existing tasks, each optionally weighted by weekly hours; the match score is computed directly from their task embeddings.",
"type": "object",
"required": [
"source_tasks",
"target_tasks"
],
"properties": {
"source_tasks": {
"description": "Source task set. Must contain between 1 and 100 tasks; every task_id must reference an existing Task in the system.",
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"task_id"
],
"properties": {
"task_id": {
"description": "Identifier of an existing Task in the system.",
"type": "string",
"format": "uuid",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"weekly_hours": {
"description": "Optional per-task weight, expressed as estimated weekly hours. Tasks with more weekly hours contribute proportionally more to the match score. When omitted, the task is weighted equally (as if 1), so a request with no weekly_hours reduces to an unweighted mean.",
"type": "integer",
"minimum": 1,
"maximum": 40,
"default": 1,
"example": 5
}
}
},
"example": [
{
"task_id": "a7844da2-b2b2-42da-818a-006785d8e78d",
"weekly_hours": 8
},
{
"task_id": "dc6b2225-fa29-4c4b-8102-b218b70a8287"
}
]
},
"target_tasks": {
"description": "Target task set. Must contain between 1 and 100 tasks; every task_id must reference an existing Task in the system.",
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"task_id"
],
"properties": {
"task_id": {
"description": "Identifier of an existing Task in the system.",
"type": "string",
"format": "uuid",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"weekly_hours": {
"description": "Optional per-task weight, expressed as estimated weekly hours. Tasks with more weekly hours contribute proportionally more to the match score. When omitted, the task is weighted equally (as if 1), so a request with no weekly_hours reduces to an unweighted mean.",
"type": "integer",
"minimum": 1,
"maximum": 40,
"default": 1,
"example": 5
}
}
},
"example": [
{
"task_id": "d7b51744-5c02-4274-85ac-d6fe1a480a85"
},
{
"task_id": "960bc9a9-cbaa-4c84-8539-7c0755b27ef9",
"weekly_hours": 4
}
]
}
}
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"source_tasks": [
{
"task_id": "a7844da2-b2b2-42da-818a-006785d8e78d",
"weekly_hours": 8
},
{
"task_id": "dc6b2225-fa29-4c4b-8102-b218b70a8287"
}
],
"target_tasks": [
{
"task_id": "d7b51744-5c02-4274-85ac-d6fe1a480a85"
},
{
"task_id": "960bc9a9-cbaa-4c84-8539-7c0755b27ef9",
"weekly_hours": 4
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"description": "An ad-hoc task-based match result between two task sets.",
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"description": "The symmetric task-based match score between the two task sets, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"title": "Explained",
"allOf": [
{
"title": "Simple",
"description": "An ad-hoc task-based match result between two task sets.",
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"description": "The symmetric task-based match score between the two task sets, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "An ad-hoc task-based match result between two task sets, including a per-Task breakdown of the match. Each Task on either side is reported once per direction as either present (it has a sufficiently similar Task in the other set) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task in the other set.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task in the other set.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"score": 0.42
}
},
"explainedExample": {
"summary": "With response_format=explained",
"value": {
"score": 0.42,
"present_tasks": [
{
"task_id": "a7844da2-b2b2-42da-818a-006785d8e78d",
"task_name": "Write unit tests for backend services",
"direction": "source_to_target",
"adjacent_task_id": "d7b51744-5c02-4274-85ac-d6fe1a480a85",
"adjacent_task_name": "Add automated test coverage for backend services",
"adjacency_score": 0.91,
"hours_share": 0.6
}
],
"missing_tasks": [
{
"task_id": "960bc9a9-cbaa-4c84-8539-7c0755b27ef9",
"task_name": "Operate legacy mainframe for payroll processing",
"direction": "target_to_source"
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/job_families/{job_family_external_id}/match": {
"get": {
"tags": [
"Job Family Matching"
],
"summary": "Get the match score between an Employee and a Job Family",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job Family, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a39c3505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"present_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{external_id}/matching_job_families": {
"post": {
"tags": [
"Job Family Matching"
],
"summary": "Get the top matching Job Families for an Employee",
"description": "Get an export of the best matching Job Families for an Employee. Only active Job Families are included in the results.",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the name of the Job Family and Job Family Group. attributes. When include `entity` is used, the response will include the name of the Job Family and Job Family Group.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"entity",
"custom_properties"
]
},
"example": [
"entity",
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job Family matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the name of the Job Family and Job Family Group",
"required": [
"job_family_name",
"job_family_group"
],
"properties": {
"job_family_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software Development",
"description": "Name of the Job Family."
},
"job_family_group": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Information Technology",
"description": "Name of the Job Family Group."
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job Family, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
},
"entityExample": {
"summary": "Entity Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_family_name": "Software Development",
"job_family_group": "Information Technology"
}
]
},
"explainedExample": {
"summary": "Explained Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{external_id}/matching_employees": {
"post": {
"tags": [
"Job Family Matching"
],
"summary": "Get the top matching Employees for a Job Family",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include `entity` is used, the response will include the assigned position and working history of the Employee. Only active Employees are included in the results.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job Family matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
},
{
"title": "Custom Properties",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Entity",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the assigned position and working history of the Employee.",
"required": [
"assigned_position",
"working_history"
],
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of match results.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job Family, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
}
]
},
"customPropertiesExample": {
"summary": "Custom Properties Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"custom_properties": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
},
"entityExample": {
"summary": "Entity Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"assigned_position": "Python Developer",
"working_history": [
{
"job_title": "HR Manager",
"start_date": "2018-09-05",
"end_date": "2020-06-17",
"company": "TechWolf BV",
"job_description": "Manage the HR department and perform workforce planning"
}
]
}
]
},
"explainedExample": {
"summary": "Explained Example",
"value": [
{
"job_family_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "b85469d-6729-4d70-9876-a0faa2a2f63b"
}
],
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
}
]
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match": {
"get": {
"tags": [
"Job Family Matching"
],
"summary": "Get the task-based match score between two Job Families",
"description": "Get the symmetric task-based match score between two Job Families, computed from their merged member-Job task profiles. The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions, and is symmetric: swapping the two Job Families yields the same score.",
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "other_job_family_external_id",
"required": true,
"description": "Unique external ID linked to the target Job Family to compare against, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"description": "A task-based match result between two Job Families.",
"type": "object",
"required": [
"job_family_id",
"target_job_family_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Job Families, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"title": "Explained",
"allOf": [
{
"description": "A task-based match result between two Job Families.",
"type": "object",
"required": [
"job_family_id",
"target_job_family_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Job Families, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result between two Job Families, including a per-Task breakdown of the match. Each Task on either side of the pair is reported once per direction as either present (it has a sufficiently similar Task on the other side) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task on the other side of the pair.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task on the other side of the pair.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"job_family_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_family_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.42
}
},
"explainedExample": {
"summary": "With response_format=explained",
"value": {
"job_family_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_family_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.42,
"present_tasks": [
{
"task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"task_name": "Write unit tests for backend services",
"direction": "source_to_target",
"adjacent_task_id": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
"adjacent_task_name": "Add automated test coverage for backend services",
"adjacency_score": 0.91,
"hours_share": 0.6
}
],
"missing_tasks": [
{
"task_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"task_name": "Operate legacy mainframe for payroll processing",
"direction": "target_to_source"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks": {
"post": {
"tags": [
"Job Family Matching"
],
"summary": "Get the most task-relevant Job Families to the given Job Family",
"description": "Identify the Job Families whose merged member-Job task profiles best match the given Job Family's task profile, ranked by symmetric task-match score (descending). The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions. Whether suggested tasks contribute alongside validated tasks is governed by the tenant's `tasks_on_jobs` setting.\nResults are subject to a result-level minimum score: matches scoring below 0.30 are not returned. A Job Family whose best match falls below this floor returns an empty result list rather than a weak, potentially misleading ranking.",
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "Unique external ID linked to this Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional attributes to include per result. This query parameter can be added multiple times to include more attributes. `entity` adds the target Job Family's `job_family_name` and `job_family_group`; `custom_properties` adds the target Job Family's custom properties.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"entity"
]
},
"example": [
"custom_properties",
"entity"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "Top matching Job Families, ranked by `score` descending.",
"items": {
"allOf": [
{
"description": "A task-based match result between two Job Families.",
"type": "object",
"required": [
"job_family_id",
"target_job_family_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Job Families, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result, optionally enriched with attributes requested via the `include` query parameter.",
"properties": {
"job_family_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software Engineering",
"description": "Name of the target Job Family. Present when `include=entity`."
},
"job_family_group": {
"type": "string",
"maxLength": 255,
"example": "Engineering",
"description": "Group of the target Job Family. Present when `include=entity`."
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "Top matching Job Families, ranked by `score` descending, each with a per-Task breakdown.",
"items": {
"title": "Explained",
"allOf": [
{
"description": "A task-based match result between two Job Families.",
"type": "object",
"required": [
"job_family_id",
"target_job_family_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Job Families, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result between two Job Families, including a per-Task breakdown of the match. Each Task on either side of the pair is reported once per direction as either present (it has a sufficiently similar Task on the other side) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task on the other side of the pair.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task on the other side of the pair.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"results": [
{
"job_family_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_family_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657
},
{
"job_family_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_family_id": "c1203505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.41231
}
]
}
},
"includeExample": {
"summary": "With include=entity and include=custom_properties",
"value": {
"results": [
{
"job_family_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_family_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"job_family_name": "Software Engineering",
"job_family_group": "Engineering",
"custom_properties": [
{
"property_name": "department",
"property_value": "Engineering"
}
]
}
]
}
},
"explainedExample": {
"summary": "With response_format=explained",
"value": {
"results": [
{
"job_family_id": "b0035050-eb84-42dc-a79f-5e7b1fe897b7",
"target_job_family_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.87657,
"present_tasks": [
{
"task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"task_name": "Write unit tests for backend services",
"direction": "source_to_target",
"adjacent_task_id": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
"adjacent_task_name": "Add automated test coverage for backend services",
"adjacency_score": 0.91,
"hours_share": 0.6
}
],
"missing_tasks": [
{
"task_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"task_name": "Operate legacy mainframe for payroll processing",
"direction": "target_to_source"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/vacancies/{vacancy_external_id}/match_feedback": {
"post": {
"tags": [
"Match Feedback"
],
"summary": "Give feedback on the match between an Employee and a Vacancy",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "vacancy_external_id",
"required": true,
"description": "Unique external ID linked to this Vacancy, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"feedback"
],
"properties": {
"feedback": {
"type": "string",
"description": "Thumbs up or down can indicate whether a match is positive or negative.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"Match Feedback"
],
"summary": "Delete feedback on the match between an Employee and a Vacancy",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "vacancy_external_id",
"required": true,
"description": "Unique external ID linked to this Vacancy, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/{employee_external_id}/courses/{course_external_id}/match_feedback": {
"post": {
"tags": [
"Match Feedback"
],
"summary": "Give feedback on the recommendation of a Course for an Employee.",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "course_external_id",
"required": true,
"description": "Unique external ID linked to this Course, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"feedback"
],
"properties": {
"feedback": {
"type": "string",
"description": "Thumbs up or down can indicate whether a match is positive or negative.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"Match Feedback"
],
"summary": "Delete feedback on the match between an Employee and a Course",
"parameters": [
{
"in": "path",
"name": "employee_external_id",
"required": true,
"description": "Unique external ID linked to this Employee, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "course_external_id",
"required": true,
"description": "Unique external ID linked to this Course, consisting of alphanumeric characters, hyphens and underscores.",
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/suggestions/skills": {
"post": {
"tags": [
"EmployeeSuggestions"
],
"summary": "Get suggestions, validated and rejected Skills for selected Employees",
"description": "\n\nThis endpoint retrieves Skill suggestions and validated and rejected Skills for selected Employees. Users can\ncustomize the response with optional query parameters like language, the\nnumber of suggestions, and the format (Skill Profiles or Skill Clusters). It\nsupports filtering by Skill types (suggested, validated, rejected). The response\nincludes detailed Skill suggestions, with translated names and sources.\n",
"parameters": [
{
"in": "query",
"required": false,
"name": "language",
"description": "The display languages for which Skill names are provided.\nIf not specified, the default language (`en_uk`) will be used.\nThe `en` language is an alias for `en_uk`. Languages for which no Skill names are available will be excluded from the response.\n",
"schema": {
"type": "array",
"default": [
"en_uk"
],
"items": {
"name": "language",
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
},
{
"in": "query",
"required": false,
"name": "suggestion_count",
"description": "The maximum number of suggested Skills to be returned and displayed within each Employee's Skill Profile.",
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"in": "query",
"required": false,
"name": "max_skills_per_cluster",
"description": "The maximum number of Skills to return for each Skill Cluster.\nThis only applies when `response_format` is set to `skill_clusters`.\n",
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which you want the Skill suggestions to be returned. This will only work for vendors that are activated on your tenant. If no external vendor is specified, Skills will be returned in the TechWolf vocabulary.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"name": "properties",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"description": "Filter skills by their properties. Use the format `properties[property_name]=value` to filter skills that have a specific property with a specific value.\nFor example, `properties[sap_status]=active` will only return skills that have the `sap_status` property set to `active`.\n\n**Available properties:**\n- `sap_status`: Status of the Skill in the SAP Attribute Library (possible values: `active`, `inactive`)\n",
"schema": {
"type": "object"
}
},
{
"in": "query",
"required": false,
"name": "include",
"description": "The type of Skills to include in the response and which Skill properties to include.\n`suggested_skills` - Include the suggested Skills in the response.\n`validated_skills` - Include the validated Skills in the response.\n`rejected_skills` - Include the rejected Skills in the response.\n`proficiency` - Include the self-rated proficiency level for the Skills in the response.\n`job_critical` - Include whether the Skill is a critical Skill for the Job of the Employee.\n",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"suggested_skills",
"validated_skills",
"rejected_skills",
"proficiency",
"job_critical"
]
},
"example": [
"suggested_skills"
],
"default": [
"suggested_skills"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"employee_ids"
],
"properties": {
"employee_ids": {
"type": "array",
"description": "The IDs of the Employees for which to get the suggestions.\n**Maximum of 50 Employees.**\n",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 50
},
"response_format": {
"type": "string",
"description": "The format in which the suggestions should be returned.\n`skill_profiles` - Return the suggestions as a list of the Employee Skill Profiles.\n`skill_clusters` - Return the suggestions as a list of the Employee Skill Clusters.\nResponse format `skill_clusters` requires a taxonomy with skill clusters to be activated on your tenant.\n",
"enum": [
"skill_profiles",
"skill_clusters"
],
"default": "skill_profiles"
}
}
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"suggestions": {
"type": "array",
"description": "An array containing Skill suggestions for the requested Employees.",
"items": {
"type": "object",
"required": [
"employee_id",
"skills"
],
"properties": {
"employee_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The array of suggested Skills for the Employee.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill_names",
"sources"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_names": {
"type": "array",
"description": "The array of translated Skill names for the Skill.",
"items": {
"type": "object",
"required": [
"language",
"skill_name"
],
"properties": {
"language": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
},
"skill_name": {
"type": "string",
"description": "The translated name of the Skill."
}
}
}
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "The type of Skill Event sources from which the Skill was derived."
},
"skill_cluster_id": {
"description": "The ID of the Skill Cluster to which the Skill belongs. This is only returned when `response_format` is set to `skill_clusters`.",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster to which the Skill belongs. This is only returned when `response_format` is set to `skill_clusters`."
},
"inferred_proficiency_level": {
"type": "integer",
"nullable": true,
"description": "The inferred proficiency level for the Skill."
},
"self_rated_proficiency_level": {
"type": "integer",
"nullable": true,
"description": "The self-rated proficiency level for the Skill."
},
"is_job_critical_skill": {
"type": "boolean",
"description": "Whether the Skill is a critical Skill for the Job of the Employee."
}
}
}
}
}
},
"example": [
{
"employee_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"skills": [
{
"skill_id": "95747a9e-57e7-4892-967d-37e6c126e35e",
"skill_names": [
{
"language": "en_uk",
"skill_name": "Python"
},
{
"language": "nl",
"skill_name": "Python"
}
],
"sources": [
"education_history"
],
"inferred_proficiency_level": 2,
"self_rated_proficiency_level": null,
"is_job_critical_skill": true
},
{
"skill_id": "6b665a95-dba8-4f76-85d7-a4669da01c26",
"skill_names": [
{
"language": "en_uk",
"skill_name": "Programming"
},
{
"language": "nl",
"skill_name": "Programmeren"
}
],
"sources": [
"education_history"
],
"inferred_proficiency_level": 3,
"self_rated_proficiency_level": null,
"is_job_critical_skill": false
}
]
}
]
},
"validated": {
"type": "array",
"description": "An array containing validated Skill suggestions for the requested Employees.",
"items": {
"type": "object",
"required": [
"employee_id",
"skills"
],
"properties": {
"employee_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The array of validated Skills for the Employee.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill_names",
"sources"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_names": {
"type": "array",
"description": "The array of translated Skill names for the Skill.",
"items": {
"type": "object",
"required": [
"language",
"skill_name"
],
"properties": {
"language": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
},
"skill_name": {
"type": "string",
"description": "The translated name of the Skill."
}
}
}
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "The type of Skill Event sources from which the Skill was derived."
},
"skill_cluster_id": {
"description": "The ID of the Skill Cluster to which the Skill belongs. This is only returned when `response_format` is set to `skill_clusters`.",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster to which the Skill belongs. This is only returned when `response_format` is set to `skill_clusters`."
},
"inferred_proficiency_level": {
"type": "integer",
"nullable": true,
"description": "The inferred proficiency level for the Skill."
},
"self_rated_proficiency_level": {
"type": "integer",
"nullable": true,
"description": "The self-rated proficiency level for the Skill."
},
"is_job_critical_skill": {
"type": "boolean",
"description": "Whether the Skill is a critical Skill for the Job of the Employee."
}
}
}
}
}
},
"example": [
{
"employee_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"skills": [
{
"skill_id": "81fcc471-cef7-448d-824c-2e2ebf1ce8be",
"skill_names": [
{
"language": "en_uk",
"skill_name": "Agile Development"
},
{
"language": "nl",
"skill_name": "Agile Ontwikkeling"
}
],
"sources": [
"education_history"
]
},
{
"skill_id": "7d34b72e-7ca5-45fd-80e0-8ed7e615ee53",
"skill_names": [
{
"language": "en_uk",
"skill_name": "Automated Testing"
},
{
"language": "nl",
"skill_name": "Geautomatiseerd Testen"
}
],
"sources": [
"education_history"
],
"inferred_proficiency_level": 2,
"self_rated_proficiency_level": 2,
"is_job_critical_skill": true
}
]
}
]
},
"rejected": {
"type": "array",
"description": "An array containing rejected Skill suggestions for the requested Employees.",
"items": {
"type": "object",
"required": [
"employee_id",
"skills"
],
"properties": {
"employee_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The array of rejected Skills for the Employee.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill_names"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_names": {
"type": "array",
"description": "The array of translated Skill names for the Skill.",
"items": {
"type": "object",
"required": [
"language",
"skill_name"
],
"properties": {
"language": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
},
"skill_name": {
"type": "string",
"description": "The translated name of the Skill."
}
}
}
},
"inferred_proficiency_level": {
"type": "integer",
"nullable": true,
"description": "The inferred proficiency level for the Skill."
},
"self_rated_proficiency_level": {
"type": "integer",
"nullable": true,
"description": "The self-rated proficiency level for the Skill."
},
"is_job_critical_skill": {
"type": "boolean",
"description": "Whether the Skill is a critical Skill for the Job of the Employee."
}
}
}
}
}
},
"example": [
{
"employee_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"skills": [
{
"skill_id": "6843733c-e646-4a77-ae70-c0da60618ffe",
"skill_names": [
{
"language": "en_uk",
"skill_name": "Business Requirement Analysis"
},
{
"language": "nl",
"skill_name": "Analyse Van Bedrijfsvereisten"
}
],
"inferred_proficiency_level": null,
"self_rated_proficiency_level": null,
"is_job_critical_skill": false
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/employees/search": {
"post": {
"tags": [
"EmployeeSearch"
],
"summary": "Search for Employees based on free text",
"description": "Search for Employees",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "language",
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"default": "auto",
"example": "en"
},
"description": "The language of the input text. `auto` will automatically detect the language used."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Request structure for free text search.",
"required": [
"text",
"filters",
"weights"
],
"properties": {
"text": {
"type": "string",
"description": "Input text.",
"example": "Bakery"
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"search_for",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"search_for": {
"type": "string",
"description": "The `external_id` of the entity for which match feedback is filtered out.",
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"external_id_1",
"external_id_2",
"external_id_3"
]
},
{
"filter": "exclude_match_feedback",
"search_for": "vacancy_id",
"exclude_match_feedback": "thumbs_up"
}
]
},
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "max_geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 15
},
{
"weight": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe",
"operator": "eq",
"value": 0.04
},
{
"weight": "custom_property",
"property_name": "yearly_salary",
"property_value": 45000,
"operator": "gte",
"value": 0.04
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of search results.",
"items": {
"type": "object",
"properties": {
"employee_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"score": {
"description": "The matching score between an Employee and the provided text, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
},
"example": {
"results": [
{
"employee_id": "euid-123",
"score": 0.82
},
{
"employee_id": "euid-456",
"score": 0.74
},
{
"employee_id": "euid-789",
"score": 0.56
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/vacanies/search": {
"post": {
"tags": [
"VacancySearch"
],
"summary": "Search for Vacancies based on free text",
"description": "Search for Vacancies. Unlike other entities, searching happens based on the `job_title` text match by default, not based on Skills match. Literal string matching is fuzzy, meaning that typo's and misspellings should still turn up desired results. For example, searching for `deceptionist` could still show `receptionist` Vacancy results. Literal search will always result in a score of `1.0`. A combination of both types is possible.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "language",
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"default": "auto",
"example": "en"
},
"description": "The language of the input text. `auto` will automatically detect the language used."
},
{
"in": "query",
"name": "match_type",
"schema": {
"type": "string",
"enum": [
"literal",
"skills"
],
"default": "literal",
"example": "skills"
},
"description": "The type of matching. `literal` will search text-based. `skills` will use the Skills extracted from the input to find the best-matching Vacancies."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Request structure for free text search.",
"required": [
"text",
"filters",
"weights"
],
"properties": {
"text": {
"type": "string",
"description": "Input text.",
"example": "Software Engineer"
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"search_for",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"search_for": {
"type": "string",
"description": "The `external_id` of the entity for which match feedback is filtered out.",
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"external_id_1",
"external_id_2",
"external_id_3"
]
},
{
"filter": "is_active",
"is_active": true
},
{
"filter": "exclude_match_feedback",
"search_for": "employee_id",
"exclude_match_feedback": "thumbs_up"
}
]
},
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "max_geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 15
},
{
"weight": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe",
"operator": "eq",
"value": 0.04
},
{
"weight": "custom_property",
"property_name": "yearly_salary",
"property_value": 45000,
"operator": "gte",
"value": 0.04
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of search results.",
"items": {
"type": "object",
"properties": {
"vacancy_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"score": {
"description": "The matching score between a Vacancy and the provided text, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
},
"example": {
"results": [
{
"vacancy_id": "vuid-123",
"score": 0.82
},
{
"vacancy_id": "vuid-456",
"score": 0.74
},
{
"vacancy_id": "vuid-789",
"score": 0.56
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/companies/search": {
"post": {
"tags": [
"CompanySearch"
],
"summary": "Search for External Companies based on free text",
"description": "Search for External Companies",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10
},
"description": "The maximal number of results returned."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit."
},
{
"in": "query",
"name": "score_min_threshold",
"schema": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5
},
"description": "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."
},
{
"in": "query",
"name": "language",
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"default": "auto",
"example": "en"
},
"description": "The language of the input text. `auto` will automatically detect the language used."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Request structure for free text search.",
"required": [
"text",
"filters",
"weights"
],
"properties": {
"text": {
"type": "string",
"description": "Input text.",
"example": "Bakery"
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"external_id_1",
"external_id_2",
"external_id_3"
]
}
]
},
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "max_geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 15
},
{
"weight": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe",
"operator": "eq",
"value": 0.04
},
{
"weight": "custom_property",
"property_name": "yearly_salary",
"property_value": 45000,
"operator": "gte",
"value": 0.04
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "List of search results.",
"items": {
"type": "object",
"properties": {
"company_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"score": {
"description": "The matching score between an External Company and the provided text, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
},
"matching_vacancies": {
"description": "An overview of the match results between the provided text and the most recent open positions for this External Company sorted by match score.",
"type": "array",
"items": {
"type": "object",
"required": [
"vacancy_id",
"score",
"job_title"
],
"properties": {
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between the provided text and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager",
"description": "Title of the Vacancy."
}
}
}
}
}
}
}
},
"example": {
"results": [
{
"company_id": "cuid-123",
"score": 0.9,
"matching_vacancies": [
{
"vacancy_id": "a4003805-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.9,
"job_title": "Business Analyst"
},
{
"vacancy_id": "b4003805-eb84-42dc-a79f-5e7b1fe897b7",
"score": 0.7,
"job_title": "Data Scientist"
}
]
},
{
"company_id": "cuid-456",
"score": 0.8,
"matching_vacancies": [
{
"vacancy_id": "e1d2b367-d899-474f-a3e4-4f926e2bf6d9",
"score": 0.8,
"job_title": "Software Engineer"
},
{
"vacancy_id": "3d21ce18-f599-43e6-9a57-10e13916f1dd",
"score": 0.7,
"job_title": "Data Scientist"
}
]
}
]
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/skill_clusters": {
"post": {
"tags": [
"ExportEmployeesSkillClusters"
],
"summary": "Export Employee Skill Clusters data.",
"description": "Export all Skill Clusters of all Employees by paginating through the data.\nThe Employees are returned based on their creation time, with those created first being returned first.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Employees to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Employee to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Employees.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "The type of filter to apply.",
"enum": [
"last_updated",
"last_updated_with_taxonomy_change"
],
"example": "last_updated"
},
"value": {
"type": "string",
"maxLength": 255,
"description": "The value to filter against, IS08601-formatted\ndate(time).\n",
"format": "date-time",
"example": "2022-03-12"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the filter value and the entities value. The following operators are supported per property type:\n * `datetime`: `lt`, `lte`, `gte`, `gt`",
"default": "gte",
"enum": [
"lt",
"lte",
"gte",
"gt"
]
}
}
}
]
}
},
"include": {
"type": "array",
"description": "Expand the results with extra data.",
"items": {
"type": "string",
"enum": [
"current_skills",
"related_skills",
"rejected_skills",
"sources"
],
"description": "Include:\n * `current_skills` - Show the current Skills for the\nprofile.\n * `related_skills` - Show the related Skills for the\nprofile.\n * `sources` - Show the event type sources that led to this\nSkill Cluster.\n"
},
"example": [
"sources",
"current_skills",
"related_skills",
"rejected_skills"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"type": "object",
"required": [
"external_id",
"skill_clusters"
],
"properties": {
"external_id": {
"type": "string",
"description": "The unique ID of the entity in your system, consisting of alphanumeric characters, hyphens and underscores."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters for the entity.",
"items": {
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"domain_name",
"proficiency_level",
"validation_state"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"description": "ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "Name of the Skill Cluster."
},
"domain_name": {
"type": "string",
"description": "The name of the Domain associated with this Skill Cluster."
},
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain associated with this Skill Cluster. This field is only applicable in a 4-level Taxonomy."
},
"proficiency_level": {
"type": "integer",
"minimum": 0,
"maximum": 3,
"description": "Proficiency level of the entity in this Skill Cluster."
},
"validation_state": {
"type": "string",
"description": "This field indicates whether this Skill Cluster is already validated or rejected by a manager or Employee or still in the suggested state.",
"enum": [
"validated",
"suggested",
"rejected"
]
},
"current_skills": {
"type": "array",
"description": "The Skills of the Skill Cluster that are also in the Skills of the entity.",
"items": {
"type": "object",
"description": "A Skill in the Skill Cluster.",
"required": [
"name",
"skill_id",
"validation_state"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Skill is already validated or rejected by a manager or Employee or still in the suggested state."
},
"skill_sources": {
"type": "array",
"description": "The Skill Event types that led to the Skill.",
"items": {
"type": "string",
"description": "A type of Skill Event."
}
}
}
}
},
"related_skills": {
"type": "array",
"description": "The Skills of the Skill Cluster that are not in the Skills of the entity.",
"items": {
"type": "object",
"description": "A Skill in the Skill Cluster.",
"required": [
"name",
"skill_id",
"validation_state"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"rejected"
],
"description": "This field indicates whether this Skill is already validated or rejected by a manager or Employee or still in the suggested state."
},
"skill_sources": {
"type": "array",
"description": "The Skill Event types that led to the Skill.",
"items": {
"type": "string",
"description": "A type of Skill Event."
}
}
}
}
},
"sources": {
"type": "array",
"description": "The Skill Event types from which the Skills of the Skill Cluster were inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
}
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skill_clusters": [
{
"skill_cluster_id": "51e605a8-ca08-4ba6-a359-28bad07b38f6",
"skill_cluster_name": "DevOps",
"domain_name": "Computer Science",
"proficiency_level": 3,
"validation_state": "validated",
"current_skills": [
{
"name": "Git",
"skill_id": "ed8a3b44-59a0-44a6-a283-6c0e4b303be1",
"validation_state": "suggested",
"skill_sources": [
"working_history",
"resume_document"
]
},
{
"name": "Jenkins",
"skill_id": "eebcf485-9045-4669-a6f7-6e7faa465ff9",
"validation_state": "suggested",
"skill_sources": [
"resume_document"
]
},
{
"name": "Kubernetes",
"skill_id": "94835c7e-4135-40d7-aea6-165b33d01589",
"validation_state": "validated",
"skill_sources": [
"working_history",
"resume_document"
]
}
],
"related_skills": [
{
"name": "Helm",
"skill_id": "63454703-6462-4ccc-bb50-34a0e99bfbf3",
"validation_state": "suggested",
"skill_sources": [
"resume_document",
"education_history"
]
}
],
"sources": [
"working_history",
"education_history",
"resume_document"
]
},
{
"skill_cluster_id": "df96accd-cfa9-414e-96e8-2f6421e9a768",
"skill_cluster_name": "Programming Languages",
"domain_name": "Computer Science",
"proficiency_level": 2,
"validation_state": "suggested",
"current_skills": [
{
"name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"validation_state": "suggested",
"skill_sources": [
"working_history"
]
},
{
"name": "Java",
"skill_id": "9e914d31-9db1-4d2d-8d16-ed8a88539879",
"validation_state": "rejected",
"skill_sources": [
"working_history"
]
}
],
"related_skills": [
{
"name": "Django",
"skill_id": "eeb27f67-8abc-4ad9-babb-7868eaa13078",
"validation_state": "suggested",
"skill_sources": [
"working_history"
]
},
{
"name": "Spring Framework",
"skill_id": "f21b6e1a-dee2-478a-b92f-b4641237af6b",
"validation_state": "suggested",
"skill_sources": [
"working_history"
]
}
],
"sources": [
"working_history"
]
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skill_clusters": [
{
"skill_cluster_id": "32575bc1-5c01-4d6f-89dc-8b4dceccf98a",
"skill_cluster_name": "Financial accounting",
"domain_name": "Finance",
"proficiency_level": 2,
"current_skills": [
{
"name": "Balance Sheet",
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"validation_state": "validated",
"skill_sources": []
},
{
"name": "IFRS",
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"validation_state": "suggested",
"skill_sources": [
"learning"
]
}
],
"related_skills": [],
"sources": [
"learning"
]
}
]
}
]
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/skill_profiles": {
"post": {
"tags": [
"ExportEmployeesSkillClusters"
],
"summary": "Export Employee Skill Profile data",
"description": "Export all Skill Profiles of all Employees by paginating through the data.\nThe Employees are returned based on their creation time, with those created first being returned first.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Employees shown on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Employee to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Employees.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
}
},
"include": {
"type": "array",
"description": "Expand the results with extra data.",
"items": {
"type": "string",
"enum": [
"skill_validation_state",
"sources",
"rejected_skills",
"low_data_availability_flag",
"self_rated_proficiency_level",
"self_rated_proficiency_float",
"inferred_proficiency_level",
"inferred_proficiency_float",
"properties",
"custom_properties",
"skill_source"
],
"description": "Include:\n * `sources` - Show the event type sources that led to this\nSkill Cluster.\n * `seniority` - Show the seniority of the Employee.\n * `rejected_skills` - Show Skills that got rejected through Skill Profile feedback.\n * `low_data_availability_flag` - Show whether there is low data availability for each Employee.\n * `self_rated_proficiency_level` - Show the self-rated proficiency level of each Skill in each Employee's profile. This value depends on the maximum proficiency level set on your tenant (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. \n * `self_rated_proficiency_float` - Show the self-rated proficiency float of each Skill in each Employee's profile. This value represents the self-rated proficiency level of the Skill, scaled to a range between between `0.0` and `1.0`. If the self-rated proficiency level is not set, `null` is returned. \n * `inferred_proficiency_level` - Show the inferred proficiency level of each Skill in each Employee's profile. This value depends on the maximum proficiency level set on your tenant (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned.\n * `inferred_proficiency_float` - Show the inferred proficiency float of each Skill in each Employee's profile. This value represents the inferred proficiency level of the Skill, scaled to a range between between `0.0` and `1.0`. If the inferred proficiency level is not set, `null` is returned.\n * `properties` - Show the skill information properties of each Skill.\n * `custom_properties` - Show the custom properties of each Skill, as a mapping of property name to value. Returns `{}` for a Skill that has none.\n * `skill_source` - Show whether each Skill originates from the TechWolf vocabulary or is a custom Skill.\n"
},
"example": [
"skill_validation_state",
"sources",
"rejected_skills",
"low_data_availability_flag"
]
},
"output_skills_sorting": {
"type": "string",
"description": "Sort the Skills in the results alphabetically or by decreasing confidence.",
"enum": [
"alphabetical",
"confidence"
],
"example": "alphabetical",
"default": "alphabetical"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result returned. The profile consists of a list of Skills and their validation states.",
"type": "object",
"required": [
"external_id",
"num_skill_events",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"num_skill_events": {
"type": "integer",
"minimum": 0,
"example": 5,
"description": "The amount of Skill Events an Employee has."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"domains"
],
"properties": {
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill",
"validation_state"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"validation_state": {
"type": "string",
"example": "suggested",
"description": "This field indicates whether this Skill is already validated by a manager or Employee or still in the suggested state.",
"enum": [
"suggested",
"validated"
]
},
"sources": {
"type": "array",
"deprecated": true,
"description": "The Skill Event types from which the Skill was inferred.",
"items": {
"type": "string",
"description": "A type of Skill Event."
},
"example": [
"working_history"
]
},
"source_events": {
"type": "array",
"description": "The Skill Events from which the Skill was inferred.",
"items": {
"type": "object",
"required": [
"external_id",
"event_type",
"source"
],
"description": "Skill Event information",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"event_type": {
"type": "string",
"description": "A type of Skill Event."
},
"source": {
"type": "string",
"description": "The source of the Skill Event."
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "learning",
"source": "youtube"
}
]
},
"self_rated_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the self-rated proficiency level is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 2
},
"self_rated_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The self-rated proficiency (as a float) for this Skill that is associated with the Employee. If the self-rated proficiency is not set, `null` is returned. The self-rated proficiency of a suggested Skill will always be `null`.",
"example": 0.4
},
"inferred_proficiency_level": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The inferred proficiency level for this Skill that is associated with the Employee. It cannot be greater that the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"example": 3
},
"inferred_proficiency_float": {
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"description": "The inferred proficiency (as a float) for this Skill that is associated with the Employee. If no inferred proficiency is available, `null` is returned.",
"example": 0.6
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"num_skill_events": 2,
"low_data_availability": false,
"seniority": 4.290482248178559,
"skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python",
"validation_state": "suggested",
"sources": [
"education_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "education_history",
"source": "workday"
}
],
"self_rated_proficiency_level": 2,
"self_rated_proficiency_float": 0.4,
"inferred_proficiency_level": 5,
"inferred_proficiency_float": 1
},
{
"skill_id": "267d511f-26d4-4c84-b2ae-eae89627deba",
"skill": "Unit Testing",
"validation_state": "suggested",
"sources": [
"working_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "working_history",
"source": "workday"
}
],
"self_rated_proficiency_level": 2,
"self_rated_proficiency_float": 0.4,
"inferred_proficiency_level": 3,
"inferred_proficiency_float": 0.6
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120007"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"low_data_availability": false,
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested",
"sources": [
"education_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "education_history",
"source": "workday"
}
],
"self_rated_proficiency_level": 2,
"self_rated_proficiency_float": 0.4,
"inferred_proficiency_level": 5,
"inferred_proficiency_float": 1
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"sources": [
"working_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "working_history",
"source": "workday"
}
],
"self_rated_proficiency_level": 2,
"self_rated_proficiency_float": 0.4,
"inferred_proficiency_level": 3,
"inferred_proficiency_float": 0.6
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"sources": [
"education_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "education_history",
"source": "workday"
}
],
"self_rated_proficiency_level": null,
"self_rated_proficiency_float": null,
"inferred_proficiency_level": 1,
"inferred_proficiency_float": 0.2
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"sources": [
"working_history"
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "working_history",
"source": "workday"
}
],
"self_rated_proficiency_level": 2,
"self_rated_proficiency_float": 0.4,
"inferred_proficiency_level": 5,
"inferred_proficiency_float": 1
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120007"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/task_profiles": {
"post": {
"tags": [
"ExportEmployeesSkillClusters"
],
"summary": "Export Employee Task Profile data",
"description": "\n\nExport Task Profiles for all Employees by paginating through the data.\nEmployees are returned in the order they were created (oldest first).\nEmployees without a task profile will be included with an empty `tasks` array.\nUse the `include` parameter to optionally expand tasks with AI impact\ninformation and/or their source events. Use `filters` to narrow the set of\nEmployees returned.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Number of Employees to return per page.",
"example": 10
},
"starting_after": {
"type": "string",
"format": "slug",
"maxLength": 100,
"description": "The external_id of the last Employee seen. Used for cursor-based pagination. Omit on the first request.",
"example": "id_9"
},
"include": {
"type": "array",
"description": "Additional attributes that will be included in the response body.\n\n- `ai_impact` — includes AI impact level and rationale per task.\n- `source_events` — includes the source events behind each task.\n- `linked_skills` — includes Skills linked to each task, with Skill ID and name. Use the `external_vendor` query parameter to display Skill names in an external vendor vocabulary.\n- `rejected_tasks` — includes tasks that were rejected via PATCH feedback (excluded by default).\n- `weekly_hours` — includes the estimated number of hours spent on each task per week.\n",
"items": {
"type": "string",
"enum": [
"ai_impact",
"source_events",
"linked_skills",
"rejected_tasks",
"weekly_hours"
]
},
"example": [
"ai_impact",
"source_events"
]
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Employees.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
}
]
}
}
}
},
"example": {
"limit": 10,
"include": [
"ai_impact",
"source_events"
],
"filters": [
{
"filter": "is_active",
"is_active": true
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The cursor value to use as starting_after on the next request. Only present when has_next is true.",
"type": "string",
"format": "slug",
"maxLength": 100,
"example": "id_4"
},
"records": {
"description": "List of Employee task profile records.\nShape depends on `response_format`: each record contains either a flat `tasks` array (`list`) or a nested hierarchy tree (`hierarchy`).\n",
"type": "array",
"items": {
"oneOf": [
{
"description": "Record shape when `response_format=list` (default). The profile consists of a flat list of Tasks assigned to the Employee.",
"type": "object",
"required": [
"external_id",
"tasks"
],
"properties": {
"external_id": {
"type": "string",
"description": "Employee external_id.",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
},
"tasks": {
"type": "array",
"description": "Tasks in the Employee's profile (empty if none assigned).",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager or Employee via Employee feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_events": {
"type": "array",
"description": "Source events that contributed to this task (only present when include=source_events).",
"items": {
"type": "object",
"required": [
"external_id",
"event_type"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the source Skill Event in case of a Skill Event, or the external ID of the Job in case the task originates from Job Data.",
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
},
"event_type": {
"type": "string",
"description": "The event type of the source Skill Event in case of a Skill Event, or the external ID of the Job in case the task originates from Job Data.",
"enum": [
"project",
"job"
],
"example": "project"
}
}
}
}
}
}
}
},
"example": {
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"tasks": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task": "Write unit tests for backend services",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill": "Test-Driven Development"
}
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
},
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task": "Review pull requests for the analytics team",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment for code quality assessment"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
}
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "job"
}
]
}
]
}
},
{
"description": "Record shape when `response_format=hierarchy`. Tasks are grouped into a nested domain → subdomain → cluster → canonical task tree. Tasks without a fully-populated hierarchy are placed in `tasks_outside_hierarchy`.",
"type": "object",
"required": [
"external_id",
"domains",
"tasks_outside_hierarchy"
],
"properties": {
"external_id": {
"type": "string",
"description": "Employee external_id.",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
},
"domains": {
"type": "array",
"description": "Tasks grouped by domain → subdomain → cluster → canonical task.",
"items": {
"type": "object",
"required": [
"domain_name",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "Name of the task hierarchy domain.",
"example": "Computer Science"
},
"domain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy domain.",
"example": "576132d7-83d2-bcba-78db-e14c073409dd"
},
"subdomains": {
"type": "array",
"items": {
"type": "object",
"required": [
"subdomain_name",
"clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "Name of the task hierarchy subdomain.",
"example": "Software Engineering"
},
"subdomain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy subdomain.",
"example": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab"
},
"clusters": {
"type": "array",
"items": {
"type": "object",
"required": [
"cluster_name",
"canonical_tasks"
],
"properties": {
"cluster_name": {
"type": "string",
"description": "Name of the task hierarchy cluster.",
"example": "Programming Languages"
},
"cluster_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy cluster.",
"example": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1"
},
"canonical_tasks": {
"type": "array",
"items": {
"type": "object",
"required": [
"canonical_task_name",
"tasks"
],
"properties": {
"canonical_task_name": {
"type": "string",
"description": "Name of the canonical task.",
"example": "Standardized Testing"
},
"canonical_task_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the canonical task.",
"example": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
},
"tasks": {
"type": "array",
"description": "Tasks under this canonical task.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager or Employee via Employee feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_events": {
"type": "array",
"description": "Source events that contributed to this task (only present when include=source_events).",
"items": {
"type": "object",
"required": [
"external_id",
"event_type"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the source Skill Event in case of a Skill Event, or the external ID of the Job in case the task originates from Job Data.",
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
},
"event_type": {
"type": "string",
"description": "The event type of the source Skill Event in case of a Skill Event, or the external ID of the Job in case the task originates from Job Data.",
"enum": [
"project",
"job"
],
"example": "project"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"tasks_outside_hierarchy": {
"type": "array",
"description": "Tasks where at least one hierarchy field is null or missing.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager or Employee via Employee feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_events": {
"type": "array",
"description": "Source events that contributed to this task (only present when include=source_events).",
"items": {
"type": "object",
"required": [
"external_id",
"event_type"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the source Skill Event in case of a Skill Event, or the external ID of the Job in case the task originates from Job Data.",
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a"
},
"event_type": {
"type": "string",
"description": "The event type of the source Skill Event in case of a Skill Event, or the external ID of the Job in case the task originates from Job Data.",
"enum": [
"project",
"job"
],
"example": "project"
}
}
}
}
}
}
}
},
"example": {
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"domains": [
{
"domain_name": "Computer Science",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"clusters": [
{
"cluster_name": "Programming Languages",
"canonical_tasks": [
{
"canonical_task_name": "Standardized Testing",
"tasks": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task": "Write unit tests for backend services",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
}
]
}
]
}
]
}
]
}
],
"tasks_outside_hierarchy": [
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task": "Review pull requests for the analytics team",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment for code quality assessment"
},
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
}
]
}
}
]
}
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"next_starting_after": "id_4",
"records": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"tasks": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task": "Write unit tests for backend services",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill": "Test-Driven Development"
}
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
},
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task": "Review pull requests for the analytics team",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment for code quality assessment"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
}
],
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
}
]
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": false,
"records": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"domains": [
{
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"clusters": [
{
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_tasks": [
{
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3",
"tasks": [
{
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task": "Write unit tests for backend services",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H2",
"rationale": "Portions can be automated via LLM test generation"
},
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
}
]
}
]
}
]
}
]
}
],
"tasks_outside_hierarchy": [
{
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task": "Review pull requests for the analytics team",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment for code quality assessment"
},
"source_events": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"event_type": "project"
}
]
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/ai_goals": {
"post": {
"tags": [
"ExportEmployeesSkillClusters"
],
"summary": "Export Employee AI Goals",
"description": "\n\nExport AI Goals for Employees by paginating through the data. By\ndefault the latest AI Goal per Employee is returned; set the\n`versions` query parameter to `all` to return every version per\nEmployee instead. Use `filters` to narrow the set of Employees\nreturned.\n\nPagination is always at Employee granularity: `limit` bounds the\nnumber of Employees scanned per page, and `starting_after` is the\n`external_id` of the last Employee from the previous page.\nEmployees without an AI Goal are silently skipped, so the returned\n`records` array can be shorter than `limit`. With `versions=all`,\nevery version for each Employee in the page is returned — the same\n`external_id` can appear multiple times and `records` can be longer\nthan `limit`. Records are ordered by `external_id` ascending and\nthen `version` descending, so the latest version for each Employee\nappears first.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"name": "versions",
"in": "query",
"required": false,
"description": "Which versions of the AI Goal to return per Employee.\n\n- `latest` (default) — one record per Employee, the highest version.\n- `all` — every version per Employee, ordered newest first.\n",
"schema": {
"type": "string",
"enum": [
"latest",
"all"
],
"default": "latest"
},
"example": "latest"
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Number of Employees to return per page."
},
"starting_after": {
"type": "string",
"format": "slug",
"maxLength": 100,
"description": "The `external_id` of the last Employee seen, used for\ncursor-based pagination. Pagination is always at Employee\ngranularity: with `versions=all` the page returns every\nversion for the Employees in the window, so the `records`\narray can be longer than `limit`. Omit on the first request.\n"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Employees.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
}
]
}
}
}
},
"example": {
"limit": 10,
"filters": [
{
"filter": "is_active",
"is_active": true
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean"
},
"next_starting_after": {
"description": "The cursor value to use as starting_after on the next request. Only present when has_next is true.",
"type": "string",
"format": "slug",
"maxLength": 100
},
"records": {
"description": "AI Goal records. With `versions=latest` (default), one\nrecord per Employee. With `versions=all`, one record\nper AI Goal version — the same `external_id` can\nrepeat. Employees without any AI Goal are omitted.\n",
"type": "array",
"items": {
"type": "object",
"required": [
"external_id",
"goal",
"description",
"target_skills",
"target_tasks",
"version",
"created_on",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"description": "The external_id of the Employee this AI Goal belongs to."
},
"goal": {
"type": "string",
"description": "Short title of the AI Goal."
},
"description": {
"type": "string",
"description": "Longer free-text description of the AI Goal."
},
"target_skills": {
"type": "array",
"description": "Skills the Employee is working towards for this AI Goal. Skill IDs are returned in the vocabulary of the `external_vendor` query parameter.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"maxLength": 100,
"description": "Identifier of a Skill in the requested vendor's vocabulary."
},
"skill": {
"type": "string",
"description": "Human-readable name of the Skill in the tenant's default vocabulary language."
}
}
}
},
"target_tasks": {
"type": "array",
"description": "Tasks the Employee is working towards for this AI Goal.",
"items": {
"type": "object",
"required": [
"task_id",
"task"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Human-readable name of the Task."
}
}
}
},
"job_id": {
"type": "string",
"nullable": true,
"description": "The external_id of the target Job for this AI Goal, or null if no Job is targeted."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Version number of this AI Goal record."
},
"created_on": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when this AI Goal version was created."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp of the last update to this AI Goal version. Equal to `created_on` for newly-created versions; updates in place for the latest version when a plain PUT is used."
}
}
}
}
}
},
"example": {
"has_next": true,
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002",
"records": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"goal": "Grow into a Senior Machine Learning Engineer role",
"description": "Move from Data Scientist to Senior Machine Learning Engineer within 12 months by deepening expertise in MLOps, owning production model deployments, and mentoring two junior team members on experiment design.",
"target_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "MLOps"
},
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Model Deployment"
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill": "Mentoring"
}
],
"target_tasks": [
{
"task_id": "2d245417-d1cb-fee5-5502-5accf77b98a0",
"task": "Design machine learning systems for fraud detection"
},
{
"task_id": "6e4dad56-822f-f0ed-0004-aaf2ef7335bf",
"task": "Deploy models to production to power the recommendations service"
}
],
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"version": 2,
"created_on": "2026-04-17T09:12:43.521000+00:00",
"last_updated": "2026-04-18T14:02:07.911000+00:00"
}
]
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export": {
"get": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Architecture hierarchy",
"description": "Export the Job Architecture as a hierarchical structure.\nJob Families are grouped by their `job_family_group_name` and consist of multiple Jobs.\nJobs that are not part of a Job Family, appear in a nameless Job Family entity.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
},
{
"in": "query",
"name": "skill_id",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"description": "The unique ID of a Skill, consisting of alphanumeric characters and hyphens. Setting this parameter will include only Job Families and Job Family Groups with Jobs that have this Skill in their Skill Profile."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to use when passing the `skill_id` query parameter. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "When set to `low_data_availability_flag`, the response will include information about the total number of Jobs with low data availability within each Job Family or Job Family Group. For Jobs, this field is equal to 1 or 0 depending on whether the Job has low data availability.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"low_data_availability_flag",
"issues",
"changes",
"job_description"
]
},
"default": [],
"example": [
"low_data_availability_flag"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_family_groups"
],
"properties": {
"job_family_groups": {
"description": "A list of Job Family Groups.",
"type": "array",
"items": {
"type": "object",
"required": [
"job_family_group_name",
"job_families",
"job_count"
],
"properties": {
"job_family_group_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family Group.",
"example": "IT & Engineering"
},
"job_count": {
"type": "integer",
"description": "The total number of Jobs within this Job Family Group."
},
"low_data_availability": {
"type": "integer",
"description": "The total number of Jobs with low data availability within this Job Family Group."
},
"job_families": {
"type": "array",
"description": "A list of Job Families belonging to a specific Job Family Group.",
"items": {
"type": "object",
"required": [
"external_id",
"job_family_name",
"jobs",
"job_count"
],
"properties": {
"external_id": {
"type": "string",
"description": "Unique ID linked to the Job Family, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"job_family_name": {
"type": "string",
"description": "The name of the Job Family.",
"example": "Mobile Development"
},
"job_count": {
"type": "integer",
"description": "The total number of Jobs within this Job Family."
},
"low_data_availability": {
"type": "integer",
"description": "The total number of Jobs with low data availability within this Job Family."
},
"jobs": {
"type": "array",
"description": "A list of Jobs belonging to a Job Family.",
"items": {
"type": "object",
"required": [
"external_id",
"job_name"
],
"properties": {
"external_id": {
"type": "string",
"description": "Unique ID linked to the Job, consisting of alphanumeric characters, hyphens and underscores.",
"example": "a3903505-eb84-42dc-a79f-5d8b1fe897b7"
},
"job_name": {
"type": "string",
"description": "Name of the Job.",
"example": "Front End Developer"
},
"job_description": {
"type": "string",
"description": "Description of the Job.",
"example": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications."
},
"low_data_availability": {
"type": "integer",
"description": "This field is equal to 1 or 0 depending on whether the Job has low data availability."
},
"issues": {
"type": "array",
"description": "A list of issues associated with the Job.",
"items": {
"type": "object",
"required": [
"issue_type"
],
"properties": {
"issue_type": {
"description": "Type of the Job Issue.",
"type": "string",
"enum": [
"missing_or_short_job_description"
],
"example": "missing_or_short_job_description"
}
}
}
},
"changes": {
"type": "array",
"description": "A list of changes associated with the Job.",
"items": {
"type": "object",
"required": [
"external_id",
"change_type",
"change_status"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"change_type": {
"description": "Type of change made to a Job.",
"type": "string",
"enum": [
"add_job_description"
],
"example": "add_job_description"
},
"change_status": {
"description": "Current status of a Job change.",
"type": "string",
"enum": [
"preview",
"generating",
"generating_preview",
"suggested",
"saving",
"saved",
"deleted",
"generate_failed",
"save_failed"
],
"example": "suggested"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/skill_clusters": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Skill Clusters data.",
"description": "Export all Skill Clusters for all Jobs by paginating through the data.\nThe Jobs are returned based on their creation time, with those created first being returned first.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Jobs to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Jobs.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "The type of filter to apply.",
"enum": [
"last_updated",
"last_updated_with_taxonomy_change"
],
"example": "last_updated"
},
"value": {
"type": "string",
"maxLength": 255,
"description": "The value to filter against, IS08601-formatted\ndate(time).\n",
"format": "date-time",
"example": "2022-03-12"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the filter value and the entities value. The following operators are supported per property type:\n * `datetime`: `lt`, `lte`, `gte`, `gt`",
"default": "gte",
"enum": [
"lt",
"lte",
"gte",
"gt"
]
}
}
}
]
}
},
"include": {
"type": "array",
"description": "Expand the results with extra data.",
"items": {
"type": "string",
"enum": [
"skills"
],
"description": "Include:\n * `skills` - Show the Skill breakdown of the Job Skill\nClusters\n"
},
"example": [
"skills"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"type": "object",
"required": [
"external_id",
"skill_clusters"
],
"properties": {
"external_id": {
"type": "string",
"description": "The unique ID of the Job in your system, consisting of alphanumeric characters, hyphens and underscores."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters for the Job.",
"items": {
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"domain_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"description": "ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "Name of the Skill Cluster."
},
"domain_name": {
"type": "string",
"description": "The name of the Domain associated with this Skill Cluster."
},
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain associated with this Skill Cluster. This field is only applicable in a 4-level Taxonomy."
},
"skills": {
"type": "array",
"description": "The Skills of the Skill Cluster that are also in the Skills of the Job.",
"items": {
"type": "object",
"description": "A Skill in the Skill Cluster.",
"required": [
"name",
"skill_id",
"validation_state"
],
"properties": {
"skill_name": {
"type": "string",
"description": "Name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
}
}
}
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skill_clusters": [
{
"skill_cluster_id": "51e605a8-ca08-4ba6-a359-28bad07b38f6",
"skill_cluster_name": "DevOps",
"domain_name": "Computer Science",
"skills": [
{
"skill_name": "Git",
"skill_id": "ed8a3b44-59a0-44a6-a283-6c0e4b303be1",
"skill_types": [
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
]
},
{
"skill_cluster_id": "df96accd-cfa9-414e-96e8-2f6421e9a768",
"skill_cluster_name": "Programming Languages",
"domain_name": "Computer Science",
"skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Family-Specific"
}
]
},
{
"skill_name": "Java",
"skill_id": "9e914d31-9db1-4d2d-8d16-ed8a88539879",
"skill_types": [
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
]
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skill_clusters": [
{
"skill_cluster_id": "32575bc1-5c01-4d6f-89dc-8b4dceccf98a",
"skill_cluster_name": "Financial accounting",
"domain_name": "Finance",
"skills": [
{
"skill_name": "Balance Sheet",
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill_types": [
{
"skill_type": "Job-Specific"
}
]
},
{
"skill_name": "IFRS",
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"skill_types": [
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
]
}
]
}
]
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/skill_profiles": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Skill Profiles.",
"description": "Export all Skill Profiles of all Jobs by paginating through the data.\nThe Jobs are returned based on their creation time, with those created first being returned first.\nThe response includes both governed and suggested Skills, distinguished by their `validation_state`.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Jobs to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Job Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "job_family_id_is_in_list",
"required": [
"filter",
"job_family_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `job_family_id` is not in the passed list.",
"enum": [
"job_family_id_is_in_list"
],
"example": "job_family_id_is_in_list"
},
"job_family_ids": {
"type": "array",
"description": "List of `job_family_id`s of entities.\n",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "job_family_id_is_in_list",
"job_family_ids": [
"5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"61a6e076-d780-11ec-9d64-0242ac120002"
]
}
]
},
"include": {
"type": "array",
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"items": {
"type": "string",
"enum": [
"low_data_availability_flag",
"proficiency_level",
"proficiency_float",
"critical",
"properties",
"skill_source"
]
},
"example": [
"low_data_availability_flag",
"proficiency_level",
"proficiency_float",
"critical"
]
},
"output_skills_sorting": {
"type": "string",
"description": "Sort the Skills in the results alphabetically or by decreasing confidence.",
"enum": [
"alphabetical",
"confidence"
],
"example": "alphabetical",
"default": "alphabetical"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"title": "List",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result is returned. The profile consists of a list of Skills with their Domain names and Skill types.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"domain_name",
"validation_state",
"source_data"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"domain_name": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The Domain name of the Skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"source_data": {
"type": "array",
"description": "The source data for this Skill includes the Job Data objects of the specified Job that contain this Skill, along with the Job Family Data objects of the specified Job's Job Family that include this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
},
"example": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Job-Specific",
"is_common": true
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": false
},
{
"skill": "TensorFlow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill_types": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
},
{
"skill": "Deep Learning",
"skill_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"low_data_availability": false,
"skills": [
{
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Balance Sheet",
"skill_types": [
{
"skill_type": "Job-Specific",
"is_common": true
}
],
"domain_name": "Finance",
"validation_state": "validated",
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
},
{
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"skill": "IFRS",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Finance",
"validation_state": "validated",
"governed_proficiency_level": 2,
"inferred_proficiency_level": 3,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
},
{
"skill_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"skill": "Financial Analysis",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Finance",
"validation_state": "suggested",
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"low_data_availability": false,
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"governed_proficiency_level": 1,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Programming",
"validation_state": "validated",
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"low_data_availability": false,
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/task_profiles": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Task Profile data",
"description": "\n\nExport Task Profiles for all Jobs by paginating through the data. Jobs are\nreturned in the order they were created (oldest first). Jobs without a task\nprofile will be included with an empty `tasks` array. Use the `include`\nparameter to optionally expand tasks with AI impact information and/or their\nsource data. Use `filters` to narrow the set of Jobs returned, including\nfiltering by job family.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Number of Jobs to return per page.",
"example": 10
},
"starting_after": {
"type": "string",
"format": "slug",
"maxLength": 100,
"description": "The external_id of the last Job seen. Used for cursor-based pagination. Omit on the first request.",
"example": "job-id-9"
},
"include": {
"type": "array",
"description": "Additional attributes that will be included in the response body.\n\n- `ai_impact` — includes AI impact level and rationale per task.\n- `source_data` — includes the job profile data entries behind each task.\n- `linked_skills` — includes Skills linked to each task, with Skill ID and name. Use the `external_vendor` query parameter to display Skill names in an external vendor vocabulary.\n- `rejected_tasks` — includes tasks that were rejected via PATCH feedback (excluded by default).\n- `weekly_hours` — includes the estimated number of hours spent on each task per week.\n",
"items": {
"type": "string",
"enum": [
"ai_impact",
"source_data",
"linked_skills",
"rejected_tasks",
"weekly_hours"
]
},
"example": [
"ai_impact",
"source_data"
]
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported Jobs.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "job_family_id_is_in_list",
"required": [
"filter",
"job_family_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter Jobs by Job Family IDs.",
"enum": [
"job_family_id_is_in_list"
],
"example": "job_family_id_is_in_list"
},
"job_family_ids": {
"type": "array",
"description": "List of Job Family external IDs to filter by. Only Jobs belonging to these Job Families will be included.",
"items": {
"type": "string",
"format": "slug",
"maxLength": 100
},
"example": [
"family-1",
"family-2"
]
}
}
}
]
}
}
}
},
"example": {
"limit": 10,
"include": [
"ai_impact",
"source_data"
],
"filters": [
{
"filter": "is_active",
"is_active": true
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "Cursor value for the next page. Only present when has_next is true.",
"type": "string",
"format": "slug",
"maxLength": 100,
"example": "id_4"
},
"records": {
"description": "List of Job task profile records.\nShape depends on `response_format`: each record contains either a flat `tasks` array (`list`) or a nested hierarchy tree (`hierarchy`).\n",
"type": "array",
"items": {
"oneOf": [
{
"description": "Record shape when `response_format=list` (default). The profile consists of a flat list of Tasks assigned to the Job.",
"type": "object",
"required": [
"external_id",
"tasks"
],
"properties": {
"external_id": {
"type": "string",
"description": "Job external_id.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"tasks": {
"type": "array",
"description": "Tasks in the Job's profile (empty if none assigned).",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager via Job feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_data": {
"type": "array",
"description": "Job profile data entries that contributed to this task (only present when include=source_data).",
"items": {
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the job profile data entry.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
},
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"linked_skills": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
},
{
"description": "Record shape when `response_format=hierarchy`. Tasks are grouped into a nested domain → subdomain → cluster → canonical task tree. Tasks without a fully-populated hierarchy are placed in `tasks_outside_hierarchy`.",
"type": "object",
"required": [
"external_id",
"domains",
"tasks_outside_hierarchy"
],
"properties": {
"external_id": {
"type": "string",
"description": "Job external_id.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"domains": {
"type": "array",
"description": "Tasks grouped by domain → subdomain → cluster → canonical task.",
"items": {
"type": "object",
"required": [
"domain_name",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "Name of the task hierarchy domain.",
"example": "Computer Science"
},
"domain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy domain.",
"example": "576132d7-83d2-bcba-78db-e14c073409dd"
},
"subdomains": {
"type": "array",
"items": {
"type": "object",
"required": [
"subdomain_name",
"clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "Name of the task hierarchy subdomain.",
"example": "Software Engineering"
},
"subdomain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy subdomain.",
"example": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab"
},
"clusters": {
"type": "array",
"items": {
"type": "object",
"required": [
"cluster_name",
"canonical_tasks"
],
"properties": {
"cluster_name": {
"type": "string",
"description": "Name of the task hierarchy cluster.",
"example": "Programming Languages"
},
"cluster_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy cluster.",
"example": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1"
},
"canonical_tasks": {
"type": "array",
"items": {
"type": "object",
"required": [
"canonical_task_name",
"tasks"
],
"properties": {
"canonical_task_name": {
"type": "string",
"description": "Name of the canonical task.",
"example": "Standardized Testing"
},
"canonical_task_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the canonical task.",
"example": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
},
"tasks": {
"type": "array",
"description": "Tasks under this canonical task.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager via Job feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_data": {
"type": "array",
"description": "Job profile data entries that contributed to this task (only present when include=source_data).",
"items": {
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the job profile data entry.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"tasks_outside_hierarchy": {
"type": "array",
"description": "Tasks where at least one hierarchy field is null or missing.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager via Job feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_data": {
"type": "array",
"description": "Job profile data entries that contributed to this task (only present when include=source_data).",
"items": {
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the job profile data entry.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"clusters": [
{
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_tasks": [
{
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
]
}
]
}
]
}
],
"tasks_outside_hierarchy": [
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
}
]
}
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"next_starting_after": "id_4",
"records": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
},
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"linked_skills": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": false,
"records": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"clusters": [
{
"cluster_name": "Programming Languages",
"canonical_tasks": [
{
"canonical_task_name": "Standardized Testing",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
]
}
]
}
]
}
],
"tasks_outside_hierarchy": [
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/suggested_skill_profiles": {
"post": {
"deprecated": true,
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Suggested Skill Profiles.",
"description": "**Deprecated:** Use [Export Job Skill Profiles](/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-skill-profiles) instead.\nThe Skill Profile export endpoint returns both governed and suggested Skills, distinguished by their `validation_state`.\n\nExport all suggested Skill Profiles of all Jobs by paginating through the data.\nThe Jobs are returned based on their creation time, with those created first being returned first.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Jobs to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Job suggested Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "job_family_id_is_in_list",
"required": [
"filter",
"job_family_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `job_family_id` is not in the passed list.",
"enum": [
"job_family_id_is_in_list"
],
"example": "job_family_id_is_in_list"
},
"job_family_ids": {
"type": "array",
"description": "List of `job_family_id`s of entities.\n",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "job_family_id_is_in_list",
"job_family_ids": [
"5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
}
]
},
"include": {
"type": "array",
"description": "Expand the results with additional data",
"items": {
"type": "string",
"enum": [
"skill_validation_state",
"properties"
]
},
"example": [
"skill_validation_state"
]
},
"output_skills_sorting": {
"type": "string",
"description": "Sort the Skills in the results alphabetically or by decreasing confidence.",
"enum": [
"alphabetical",
"confidence"
],
"example": "alphabetical",
"default": "alphabetical"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"oneOf": [
{
"title": "ListSkillProfile",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"description": "The unique ID of the Job in your system, consisting of alphanumeric characters, hyphens and underscores."
},
"skills": {
"type": "array",
"description": "List of Skills for the Job.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill",
"skill_type",
"domain_name",
"source_data"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "ID of the Skill."
},
"skill": {
"type": "string",
"description": "Name of the Skill."
},
"skill_type": {
"type": "string",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Core Skill. A Job-Specific Skill is suggested due to the JobData of the Job. A Core Skill is suggested due to the JobFamilyData of its Job Family or due to enough underlying data in neighbouring Jobs.",
"enum": [
"Core",
"Job-Specific"
]
},
"domain_name": {
"type": "string",
"minLength": 1,
"description": "The Domain name of the Skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated"
},
"source_data": {
"type": "array",
"description": "The source data for this Skill. These are the Job Data objects linked to this Job, and the Job Family Data objects linked to this Job's Job Family, that contain this Skill. For core Skills, the source_data may be an empty list when the Skill is common to all Jobs in the Job Family, but there is not direct Job Data or Job Family data linked to this Job that contains this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or a Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
}
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": {
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skills": [
{
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Balance Sheet",
"skill_type": "Core",
"domain_name": "Finance",
"validation_state": "suggested",
"source_data": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"source_data_type": "job_profile_data"
}
]
},
{
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"skill": "IFRS",
"skill_type": "Job-Specific",
"domain_name": "Finance",
"validation_state": "validated",
"source_data": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"source_data_type": "job_profile_data"
}
]
}
]
}
]
},
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested"
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/market_skill_profiles": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job external market Skill Profiles.",
"description": "Export all external market Skill Profiles of all Jobs by paginating through the data.\nThe Jobs are returned based on their creation time, with those created first being returned first.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"properties"
]
}
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Jobs to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Job Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "job_family_id_is_in_list",
"required": [
"filter",
"job_family_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `job_family_id` is not in the passed list.",
"enum": [
"job_family_id_is_in_list"
],
"example": "job_family_id_is_in_list"
},
"job_family_ids": {
"type": "array",
"description": "List of `job_family_id`s of entities.\n",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "job_family_id_is_in_list",
"job_family_ids": [
"5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
}
]
},
"output_skills_sorting": {
"type": "string",
"description": "Sort the Skills in the results alphabetically or by decreasing confidence.",
"enum": [
"alphabetical",
"confidence"
],
"example": "alphabetical",
"default": "alphabetical"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"peer_groups": {
"type": "array",
"description": "The Peer Groups for which the external market Skill Profiles are provided.",
"items": {
"type": "object",
"required": [
"peer_group",
"skills"
],
"properties": {
"peer_group": {
"type": "string",
"minLength": 1,
"description": "The name of the Peer Group."
},
"skills": {
"oneOf": [
{
"title": "List",
"type": "array",
"description": "The Skills contained in this external market Skill Profile.",
"items": {
"description": "Default structure for an individual Skill in market skill profiles.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
},
{
"title": "List external vendor",
"type": "array",
"description": "The Skills contained in this external market Skill Profile.",
"items": {
"description": "Default structure for an individual Skill in the external vendor vocabulary.",
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
},
{
"title": "Hierarchy External Vendor",
"description": "The response format formats the Skills in the external vendor vocabulary in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "111-BBB"
},
{
"skill": "Java",
"skill_id": "111-DDD"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "TensorFlow",
"skill_id": "111-CCC"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
}
]
}
}
}
}
}
}
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "4cbdbabe-5644-4423-8157-520f8a2f429a",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"skills": [
{
"skill": "Product Design",
"skill_id": "6d41b6d7-1c09-4f8a-a9c0-361b4c7a92f5"
},
{
"skill": "Materials Science",
"skill_id": "9eb6aebf-936d-4814-9c6f-8754becc2f53"
},
{
"skill": "Supply Chain Operations",
"skill_id": "7cfe0001-5a22-49dc-9148-077b546de5cd"
}
]
},
{
"peer_group": "Sport Watches Production",
"skills": [
{
"skill": "Embedded Systems",
"skill_id": "0af7ceb8-26fe-4210-a5c4-3c1b69721403"
},
{
"skill": "UX Design",
"skill_id": "98fc5005-abf9-41f5-b156-742654b7eacd"
},
{
"skill": "Algorithm Development",
"skill_id": "e273a7bd-1ee2-4911-979c-33423dc1ac08"
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"listExternalVendorExample": {
"summary": "List external vendor",
"value": {
"has_next": true,
"records": [
{
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"skills": [
{
"skill": "Product Design",
"skill_id": "222-AAA"
},
{
"skill": "Materials Science",
"skill_id": "222-BBB"
},
{
"skill": "Supply Chain Operations",
"skill_id": "222-CCC"
}
]
},
{
"peer_group": "Sport Watches Production",
"skills": [
{
"skill": "Embedded Systems",
"skill_id": "333-AAA"
},
{
"skill": "UX Design",
"skill_id": "333-BBB"
},
{
"skill": "Algorithm Development",
"skill_id": "333-CCC"
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExternalVendorExample": {
"summary": "Hierarchy external vendor",
"value": {
"has_next": true,
"records": [
{
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "111-BBB"
},
{
"skill": "Java",
"skill_id": "111-DDD"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "TensorFlow",
"skill_id": "111-CCC"
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/market_alignment": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Skill market alignment.",
"description": "Export the match scores between a Job and its market Skill Profiles in bulk. More information about the match scores and peer groups can be found in the documentation \nof the relevant [endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-alignment).\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Jobs to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Job Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "job_family_id_is_in_list",
"required": [
"filter",
"job_family_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `job_family_id` is not in the passed list.",
"enum": [
"job_family_id_is_in_list"
],
"example": "job_family_id_is_in_list"
},
"job_family_ids": {
"type": "array",
"description": "List of `job_family_id`s of entities.\n",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "job_family_id_is_in_list",
"job_family_ids": [
"5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Simple",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"title": "Simple",
"description": "A match result between a Job and its market Skill Profiles.",
"type": "object",
"required": [
"job_id",
"alignment_scores"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"alignment_scores": {
"description": "The market alignment scores for the Job, for every peer Skill Profile.",
"type": "array",
"items": {
"type": "object",
"required": [
"peer_group",
"job_to_peer_score",
"peer_to_job_score"
],
"properties": {
"peer_group": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the peer group."
},
"job_to_peer_score": {
"description": "The matching score between the Job and the peer Skill Profile, expressed as a number between 0 and 1. This indicates how well the Job Skill Profile covers the Skill requirements of the peer Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"peer_to_job_score": {
"description": "The matching score between the peer Skill Profile and the Job, expressed as a number between 0 and 1. This indicates how well a peer Skill Profile covers the Skill requirements of the Job Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
}
}
},
"example": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8
}
]
}
}
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"title": "Explained",
"description": "A match result between a Job and its market Skill Profiles.",
"type": "object",
"required": [
"job_id",
"alignment_scores"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"alignment_scores": {
"description": "The market alignment scores for the Job, for every peer Skill Profile.",
"type": "array",
"items": {
"type": "object",
"required": [
"peer_group",
"job_to_peer_score",
"peer_to_job_score",
"job_missing_skills",
"peer_missing_skills",
"overlapping_skills"
],
"properties": {
"peer_group": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the peer group.",
"example": "B2B"
},
"job_to_peer_score": {
"description": "The matching score between the Job and the peer Skill Profile, expressed as a number between 0 and 1. This indicates how well the Job Skill Profile covers the Skill requirements of the peer Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"peer_to_job_score": {
"description": "The matching score between the peer Skill Profile and the Job, expressed as a number between 0 and 1. This indicates how well a peer Skill Profile covers the Skill requirements of the Job Skill Profile.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1
},
"job_missing_skills": {
"description": "The list of Skills that are required by the peer Skill Profile but are missing from the Job Skill Profile.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"peer_missing_skills": {
"description": "The list of Skills that are required by the Job Skill Profile but are missing from the peer Skill Profile.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"overlapping_skills": {
"description": "The list of Skills that are either directly present or are sufficiently adjacent to present Skills in both the Job Skill Profile and the peer Skill Profile.",
"type": "array",
"items": {
"type": "object",
"required": [
"skill_name",
"skill_id",
"job_adjacent_skill_name",
"job_adjacent_skill_id",
"job_adjacency_score",
"peer_adjacent_skill_name",
"peer_adjacent_skill_id",
"peer_adjacency_score"
],
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_adjacent_skill_name": {
"type": "string",
"minLength": 1,
"description": "The name of the adjacent Skill in the Job Skill Profile."
},
"job_adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"description": "The universally unique ID of the adjacent Skill in the Job Skill Profile, 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The adjacency score between the Skill and the adjacent Skill in the Job Skill Profile."
},
"peer_adjacent_skill_name": {
"type": "string",
"minLength": 1,
"description": "The name of the adjacent Skill in the peer Skill Profile."
},
"peer_adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"description": "The universally unique ID of the adjacent Skill in the peer Skill Profile, 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"peer_adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "The adjacency score between the Skill and the adjacent Skill in the peer Skill Profile."
}
}
}
}
}
},
"example": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9,
"job_missing_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
}
],
"peer_missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"overlapping_skills": [
{
"skill_name": "SQL",
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"job_adjacent_skill_name": "PostgreSQL",
"job_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"job_adjacency_score": 0.7,
"peer_adjacent_skill_name": "SQL",
"peer_adjacent_skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"peer_adjacency_score": 1
}
]
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8,
"job_missing_skills": [
{
"skill_name": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
],
"peer_missing_skills": [
{
"skill_name": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
],
"overlapping_skills": [
{
"skill_name": "JavaScript",
"skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacent_skill_name": "JavaScript",
"job_adjacent_skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacency_score": 1,
"peer_adjacent_skill_name": "TypeScript",
"peer_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"peer_adjacency_score": 0.7
}
]
}
]
}
}
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple",
"value": {
"has_next": true,
"records": [
{
"job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
"alignment_scores": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"explainedExample": {
"summary": "Explained",
"value": {
"has_next": true,
"records": [
{
"job_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"alignment_scores": [
{
"peer_group": "B2B",
"job_to_peer_score": 0.85,
"peer_to_job_score": 0.9,
"job_missing_skills": [
{
"skill_name": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
}
],
"peer_missing_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"overlapping_skills": [
{
"skill_name": "SQL",
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"job_adjacent_skill_name": "PostgreSQL",
"job_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"job_adjacency_score": 0.7,
"peer_adjacent_skill_name": "SQL",
"peer_adjacent_skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"peer_adjacency_score": 1
}
]
},
{
"peer_group": "B2C",
"job_to_peer_score": 0.95,
"peer_to_job_score": 0.8,
"job_missing_skills": [
{
"skill_name": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
],
"peer_missing_skills": [
{
"skill_name": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
],
"overlapping_skills": [
{
"skill_name": "JavaScript",
"skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacent_skill_name": "JavaScript",
"job_adjacent_skill_id": "b2f1b6d0-983f-4f6e-a6a2-2b44806307b6",
"job_adjacency_score": 1,
"peer_adjacent_skill_name": "TypeScript",
"peer_adjacent_skill_id": "6d9fcb6e-7dfb-4d5f-9743-6e2c0c58c232",
"peer_adjacency_score": 0.7
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/job_families/skill_profiles": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Family Skill Profiles.",
"description": "Export all Skill Profiles of all Job Families by paginating through the data.\nThe Job Families are returned based on their creation time, with those created first being returned first.\nThe response includes both governed and suggested Skills, distinguished by their `validation_state`.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant. When specified, the query parameter `include=skill_validation_state` will not work, as it is not supported on external vendor Skill Profiles.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Job Families to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job Family to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Job Family Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
}
},
"include": {
"type": "array",
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"items": {
"type": "string",
"enum": [
"proficiency_level",
"proficiency_float",
"critical",
"properties"
]
},
"example": [
"proficiency_level",
"proficiency_float",
"critical"
]
},
"output_skills_sorting": {
"type": "string",
"description": "Sort the Skills in the results alphabetically or by decreasing confidence.",
"enum": [
"alphabetical",
"confidence"
],
"example": "alphabetical",
"default": "alphabetical"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"description": "The default Skill Profile result is returned. The profile consists of a list of Skills with their Domain names and Skill types.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"domain_name",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"domain_name": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The Domain name of the Skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skills": [
{
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Balance Sheet",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Finance",
"validation_state": "validated",
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"governed_proficiency_level": 1,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Programming",
"validation_state": "validated",
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Deep Learning",
"skill_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "suggested",
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
]
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
{
"title": "Hierarchy",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
}
]
}
]
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skills": [
{
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Balance Sheet",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Finance",
"validation_state": "validated",
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"governed_proficiency_level": 1,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Programming",
"validation_state": "validated",
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/job_families/suggested_skill_profiles": {
"post": {
"deprecated": true,
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Family Suggested Skill Profiles.",
"description": "**Deprecated:** Use [Export Job Family Skill Profiles](/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-job-families-skill-profiles) instead.\nThe Skill Profile export endpoint returns both governed and suggested Skills, distinguished by their `validation_state`.\n\nExport all Suggested Skill Profiles of all Job Families by paginating through the data.\nThe Job Families are returned based on their creation time, with those created first being returned first.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Job Families to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Job Family to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Job Family Suggested Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
}
]
}
},
"include": {
"type": "array",
"description": "Expand the results with additional data",
"items": {
"type": "string",
"enum": [
"skill_validation_state",
"properties"
]
},
"example": [
"skill_validation_state"
]
},
"output_skills_sorting": {
"type": "string",
"description": "Sort the Skills in the results alphabetically or by decreasing confidence.",
"enum": [
"alphabetical",
"confidence"
],
"example": "alphabetical",
"default": "alphabetical"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list containing the requested data for each entity, limited by the `limit` parameter.",
"type": "array",
"items": {
"oneOf": [
{
"title": "ListSkillProfile",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"description": "The unique ID of the Job Family in your system, consisting of alphanumeric characters, hyphens and underscores."
},
"skills": {
"type": "array",
"description": "List of Skills for the Job Family.",
"items": {
"type": "object",
"required": [
"skill_id",
"skill",
"skill_type",
"domain_name",
"source_data"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "ID of the Skill."
},
"skill": {
"type": "string",
"description": "Name of the Skill."
},
"skill_type": {
"type": "string",
"description": "A Core Skill indicates that it's suggested due to the JobFamilyData of its Job Family or due to sufficient JobData in neighbouring Jobs.",
"enum": [
"Core"
]
},
"domain_name": {
"type": "string",
"minLength": 1,
"description": "The Domain name of the Skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated"
},
"source_data": {
"type": "array",
"description": "The source data for this Skill. This consists of the Job Family Data objects linked to this Job Family, as well as the Job Data objects associated with the underlying Jobs of this Job Family that contain this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or a Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
}
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skills": [
{
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Balance Sheet",
"skill_type": "Core",
"domain_name": "Finance",
"validation_state": "suggested",
"source_data": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"source_data_type": "job_family_profile_data"
}
]
},
{
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"skill": "IFRS",
"skill_type": "Core",
"domain_name": "Finance",
"validation_state": "suggested",
"source_data": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"source_data_type": "job_family_profile_data"
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested"
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/suggestions": {
"post": {
"tags": [
"JobArchitectureExport"
],
"summary": "Export Job Architecture Suggestions",
"description": "Export suggestions by paginating through the data.\n\nUse the `category` query parameter to choose between skill suggestions (default) and task suggestions.\n\n**Skill suggestions** (`category=skills`) represent AI-generated recommendations for changes to job skill profiles, such as:\n- Adding a new skill to a job (`add_job_skill`)\n- Removing an existing skill from a job (`remove_job_skill`)\n- Setting a proficiency level for a skill (`set_job_skill_proficiency`)\n- Setting the criticality flag for a skill (`set_job_skill_criticality`)\n\n**Task suggestions** (`category=tasks`) represent AI-generated recommendations for adding tasks to jobs:\n- Adding a new task to a job (`add_job_task`)\n\nEach suggestion can be in one of three states:\n- `suggested`: The suggestion has not been reviewed yet\n- `accepted`: The suggestion has been accepted and applied\n- `rejected`: The suggestion has been rejected\n\nUse the `response_format` parameter to choose between:\n- `list`: Returns a flat list of suggestions (paginated by suggestion)\n- `grouped`: Returns suggestions grouped by job (paginated by job)\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "category",
"required": false,
"description": "The type of suggestions to export or interact with. If not specified, the default category (`skills`) will be used.",
"schema": {
"type": "string",
"default": "skills",
"enum": [
"skills",
"tasks"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "The number of items to show on a single page.\n- For `list` format: number of suggestions per page\n- For `grouped` format: number of jobs per page\n",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The ID to continue paginating from.\n- For `list` format: the `suggestion_id` from the previous page\n- For `grouped` format: the `job_id` from the previous page\n",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"response_format": {
"type": "string",
"enum": [
"list",
"grouped"
],
"default": "list",
"description": "The format of the response:\n- `list`: Returns a flat list of suggestions\n- `grouped`: Returns suggestions grouped by job\n",
"example": "list"
},
"filters": {
"type": "array",
"description": "A set of filters to apply on the exported suggestions.",
"items": {
"anyOf": [
{
"type": "object",
"title": "state_is_in_list",
"required": [
"filter",
"states"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter suggestions by their state (suggested, accepted, or rejected).",
"enum": [
"state_is_in_list"
],
"example": "state_is_in_list"
},
"states": {
"type": "array",
"description": "List of states to include. Valid values are: `suggested`, `accepted`, `rejected`.\n",
"maxItems": 3,
"minItems": 1,
"items": {
"type": "string",
"enum": [
"suggested",
"accepted",
"rejected"
]
},
"example": [
"suggested"
]
}
}
},
{
"type": "object",
"title": "job_family_id_is_in_list",
"required": [
"filter",
"job_family_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `job_family_id` is not in the passed list.",
"enum": [
"job_family_id_is_in_list"
],
"example": "job_family_id_is_in_list"
},
"job_family_ids": {
"type": "array",
"description": "List of `job_family_id`s of entities.\n",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "state_is_in_list",
"states": [
"suggested"
]
},
{
"filter": "job_family_id_is_in_list",
"job_family_ids": [
"5cbdbdbe-5f44-4423-8157-520f8a2f429a"
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"title": "ExportSuggestionsResponse",
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "The suggestions data. Format depends on `response_format` and `category`:\n- `list`: Array of suggestion objects\n- `grouped`: Array of objects with `job_id` and `suggestions` array\n\nWhen `category=skills`, records contain skill suggestion objects.\nWhen `category=tasks`, records contain task suggestion objects.\n",
"type": "array",
"items": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"description": "A job architecture suggestion for adding, removing, or modifying a skill on a job.",
"required": [
"suggestion_id",
"suggestion_type",
"state",
"data"
],
"properties": {
"suggestion_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the suggestion.",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"job_id": {
"type": "string",
"description": "The external ID of the job this suggestion belongs to.",
"example": "job-001"
},
"skill_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the skill this suggestion relates to.",
"example": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb"
},
"skill": {
"type": "string",
"description": "The name of the skill.",
"example": "Python"
},
"domain_name": {
"type": "string",
"description": "The domain name the skill belongs to.",
"example": "Programming"
},
"suggestion_type": {
"description": "Type of job architecture suggestion.",
"type": "string",
"enum": [
"add_job_skill",
"remove_job_skill",
"set_job_skill_proficiency",
"set_job_skill_criticality"
],
"example": "add_job_skill"
},
"state": {
"description": "Current state of a job architecture suggestion.",
"type": "string",
"enum": [
"suggested",
"accepted",
"rejected"
],
"example": "suggested"
},
"data": {
"type": "object",
"description": "Additional data for the suggestion. Contents depend on the suggestion type:\n- `set_job_skill_proficiency`: Contains `proficiency_level` (1-5)\n- `set_job_skill_criticality`: Contains `critical` (boolean)\n- `add_job_skill` / `remove_job_skill`: Empty object\n",
"properties": {
"proficiency_level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Suggested proficiency level for the skill (1-5).",
"example": 3
},
"critical": {
"type": "boolean",
"description": "Whether the skill is suggested as critical.",
"example": true
}
}
}
}
},
{
"title": "Skills (grouped)",
"type": "object",
"description": "Job suggestions grouped by job.",
"required": [
"job_id",
"suggestions"
],
"properties": {
"job_id": {
"type": "string",
"description": "The external ID of the job.",
"example": "job-001"
},
"suggestions": {
"type": "array",
"description": "List of suggestions for this job.",
"items": {
"title": "Skills",
"type": "object",
"description": "A job architecture suggestion for adding, removing, or modifying a skill on a job.",
"required": [
"suggestion_id",
"suggestion_type",
"state",
"data"
],
"properties": {
"suggestion_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the suggestion.",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"job_id": {
"type": "string",
"description": "The external ID of the job this suggestion belongs to.",
"example": "job-001"
},
"skill_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the skill this suggestion relates to.",
"example": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb"
},
"skill": {
"type": "string",
"description": "The name of the skill.",
"example": "Python"
},
"domain_name": {
"type": "string",
"description": "The domain name the skill belongs to.",
"example": "Programming"
},
"suggestion_type": {
"description": "Type of job architecture suggestion.",
"type": "string",
"enum": [
"add_job_skill",
"remove_job_skill",
"set_job_skill_proficiency",
"set_job_skill_criticality"
],
"example": "add_job_skill"
},
"state": {
"description": "Current state of a job architecture suggestion.",
"type": "string",
"enum": [
"suggested",
"accepted",
"rejected"
],
"example": "suggested"
},
"data": {
"type": "object",
"description": "Additional data for the suggestion. Contents depend on the suggestion type:\n- `set_job_skill_proficiency`: Contains `proficiency_level` (1-5)\n- `set_job_skill_criticality`: Contains `critical` (boolean)\n- `add_job_skill` / `remove_job_skill`: Empty object\n",
"properties": {
"proficiency_level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Suggested proficiency level for the skill (1-5).",
"example": 3
},
"critical": {
"type": "boolean",
"description": "Whether the skill is suggested as critical.",
"example": true
}
}
}
}
}
}
}
},
{
"title": "Tasks",
"type": "object",
"description": "A task suggestion for adding a task to a job.",
"required": [
"suggestion_id",
"suggestion_type",
"state",
"data",
"task_id",
"job_id",
"task",
"domain_name"
],
"properties": {
"suggestion_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the suggestion.",
"example": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c"
},
"job_id": {
"type": "string",
"description": "The external ID of the job this suggestion belongs to.",
"example": "b2f8e4a1-7c3d-4e9f-a6b5-8d2c1e4f7a9b"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "The human-readable name of the task.",
"example": "Write unit tests for backend services"
},
"domain_name": {
"type": "string",
"description": "The domain name the task belongs to. Defaults to \"Other\" if no domain is assigned.",
"example": "Engineering"
},
"suggestion_type": {
"description": "Type of task suggestion.",
"type": "string",
"enum": [
"add_job_task"
],
"example": "add_job_task"
},
"state": {
"description": "Current state of a job architecture suggestion.",
"type": "string",
"enum": [
"suggested",
"accepted",
"rejected"
],
"example": "suggested"
},
"data": {
"type": "object",
"description": "Additional data for the suggestion.",
"required": [
"weekly_hours"
],
"properties": {
"weekly_hours": {
"type": "integer",
"description": "The suggested number of weekly hours for this task.",
"example": 4
}
}
}
}
},
{
"title": "Tasks (grouped)",
"type": "object",
"description": "Task suggestions grouped by job.",
"required": [
"job_id",
"suggestions"
],
"properties": {
"job_id": {
"type": "string",
"description": "The external ID of the job.",
"example": "b2f8e4a1-7c3d-4e9f-a6b5-8d2c1e4f7a9b"
},
"suggestions": {
"type": "array",
"description": "List of task suggestions for this job.",
"items": {
"title": "Tasks",
"type": "object",
"description": "A task suggestion for adding a task to a job.",
"required": [
"suggestion_id",
"suggestion_type",
"state",
"data",
"task_id",
"job_id",
"task",
"domain_name"
],
"properties": {
"suggestion_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the suggestion.",
"example": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c"
},
"job_id": {
"type": "string",
"description": "The external ID of the job this suggestion belongs to.",
"example": "b2f8e4a1-7c3d-4e9f-a6b5-8d2c1e4f7a9b"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "The human-readable name of the task.",
"example": "Write unit tests for backend services"
},
"domain_name": {
"type": "string",
"description": "The domain name the task belongs to. Defaults to \"Other\" if no domain is assigned.",
"example": "Engineering"
},
"suggestion_type": {
"description": "Type of task suggestion.",
"type": "string",
"enum": [
"add_job_task"
],
"example": "add_job_task"
},
"state": {
"description": "Current state of a job architecture suggestion.",
"type": "string",
"enum": [
"suggested",
"accepted",
"rejected"
],
"example": "suggested"
},
"data": {
"type": "object",
"description": "Additional data for the suggestion.",
"required": [
"weekly_hours"
],
"properties": {
"weekly_hours": {
"type": "integer",
"description": "The suggested number of weekly hours for this task.",
"example": 4
}
}
}
}
}
}
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"maxLength": 100,
"type": "string",
"example": "660e8400-e29b-41d4-a716-446655440001"
}
}
},
"examples": {
"listExample": {
"summary": "List format response (skills)",
"value": {
"has_next": true,
"records": [
{
"suggestion_id": "550e8400-e29b-41d4-a716-446655440000",
"job_id": "job-001",
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Python",
"domain_name": "Programming",
"suggestion_type": "add_job_skill",
"state": "suggested",
"data": {}
},
{
"suggestion_id": "660e8400-e29b-41d4-a716-446655440001",
"job_id": "job-001",
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"skill": "Machine Learning",
"domain_name": "Data Science",
"suggestion_type": "set_job_skill_proficiency",
"state": "suggested",
"data": {
"proficiency_level": 3
}
}
],
"next_starting_after": "660e8400-e29b-41d4-a716-446655440001"
}
},
"groupedExample": {
"summary": "Grouped format response (skills)",
"value": {
"has_next": true,
"records": [
{
"job_id": "job-001",
"suggestions": [
{
"suggestion_id": "550e8400-e29b-41d4-a716-446655440000",
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb",
"skill": "Python",
"domain_name": "Programming",
"suggestion_type": "add_job_skill",
"state": "suggested",
"data": {}
},
{
"suggestion_id": "660e8400-e29b-41d4-a716-446655440001",
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069",
"skill": "Machine Learning",
"domain_name": "Data Science",
"suggestion_type": "set_job_skill_proficiency",
"state": "suggested",
"data": {
"proficiency_level": 3
}
}
]
},
{
"job_id": "job-002",
"suggestions": [
{
"suggestion_id": "770e8400-e29b-41d4-a716-446655440002",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill": "JavaScript",
"domain_name": "Programming",
"suggestion_type": "remove_job_skill",
"state": "suggested",
"data": {}
}
]
}
],
"next_starting_after": "job-002"
}
},
"taskListExample": {
"summary": "List format response (tasks)",
"value": {
"has_next": true,
"records": [
{
"suggestion_id": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c",
"job_id": "b2f8e4a1-7c3d-4e9f-a6b5-8d2c1e4f7a9b",
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task": "Write unit tests for backend services",
"domain_name": "Engineering",
"suggestion_type": "add_job_task",
"state": "suggested",
"data": {
"weekly_hours": 4
}
},
{
"suggestion_id": "02977d8b-4c5e-8f9a-0b2d-3e6f7a8b9c0d",
"job_id": "b2f8e4a1-7c3d-4e9f-a6b5-8d2c1e4f7a9b",
"task_id": "b7d08d86-e744-1807-4a56-a08f854e9b2e",
"task": "Review pull requests for the analytics team",
"domain_name": "Engineering",
"suggestion_type": "add_job_task",
"state": "suggested",
"data": {
"weekly_hours": 3
}
}
],
"next_starting_after": "02977d8b-4c5e-8f9a-0b2d-3e6f7a8b9c0d"
}
},
"taskGroupedExample": {
"summary": "Grouped format response (tasks)",
"value": {
"has_next": true,
"records": [
{
"job_id": "b2f8e4a1-7c3d-4e9f-a6b5-8d2c1e4f7a9b",
"suggestions": [
{
"suggestion_id": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c",
"task_id": "56dcdb53-264e-f380-50bf-5179e2d082af",
"task": "Write unit tests for backend services",
"domain_name": "Engineering",
"suggestion_type": "add_job_task",
"state": "suggested",
"data": {
"weekly_hours": 4
}
}
]
},
{
"job_id": "c3a9f5b2-8d4e-5f0a-b7c6-9e3d2f5a8b0c",
"suggestions": [
{
"suggestion_id": "03a88e9c-5d6f-9a0b-1c3e-4f7a8b9c0d1e",
"task_id": "b2992147-3fa3-fc35-1ad8-54d1c89cf157",
"task": "Conduct candidate interviews for engineering roles",
"domain_name": "People Management",
"suggestion_type": "add_job_task",
"state": "suggested",
"data": {
"weekly_hours": 2
}
}
]
}
],
"next_starting_after": "c3a9f5b2-8d4e-5f0a-b7c6-9e3d2f5a8b0c"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/courses/skill_profiles": {
"post": {
"tags": [
"CoursesExportSkillProfiles"
],
"summary": "Export Course Skill Profiles.",
"description": "Export all Skill Profiles of all Courses by paginating through the data. The Courses are returned based on their creation time, with those created first being returned first.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Course Skill Profiles to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Course to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Course Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list with for each entity the requested data, limited by `limit`.",
"type": "array",
"items": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result returned. The profile consists of a list of Skills with scores, with each score representing the importance of the Skill at hand.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de"
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"domains"
],
"properties": {
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"type": "string",
"maxLength": 100,
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skills": [
{
"skill_name": "Git",
"skill_id": "ed8a3b44-59a0-44a6-a283-6c0e4b303be1"
},
{
"skill_name": "Jenkins",
"skill_id": "eebcf485-9045-4669-a6f7-6e7faa465ff9"
},
{
"skill_name": "Kubernetes",
"skill_id": "94835c7e-4135-40d7-aea6-165b33d01589"
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skills": [
{
"skill_name": "Balance Sheet",
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb"
},
{
"skill_name": "IFRS",
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069"
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
}
]
}
]
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/vacancies/skill_profiles": {
"post": {
"tags": [
"VacanciesExportSkillProfiles"
],
"summary": "Export Vacancy Skill Profiles.",
"description": "Export all Skill Profiles of all Vacancies by paginating through the data. The Vacancies are returned based on their creation time, with those created first being returned first.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The number of Vacancy Skill Profiles to show on a single page.",
"example": 10
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Vacancy to continue looking from.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "array",
"description": "A set of filters used to apply on the exported Vacancy Skill Profiles.",
"items": {
"anyOf": [
{
"type": "object",
"title": "is_active",
"required": [
"filter",
"is_active"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include entities with the `active` attribute set to `true` or `false`. If the filter is not set, all entities will be included.",
"enum": [
"is_active"
],
"example": "is_active"
},
"is_active": {
"type": "boolean",
"description": "Set to `true` to only include entities with the `active` attribute set to `true`. Set to `false` to only include entities with the `active` attribute set to `false`.",
"example": true
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"has_next",
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"records": {
"description": "A list with for each entity the requested data, limited by `limit`.",
"type": "array",
"items": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result returned. The profile consists of a list of Skills with scores, with each score representing the importance of the Skill at hand.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8"
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill": "Tensorflow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de"
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"domains"
],
"properties": {
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
}
}
}
}
}
}
]
}
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"type": "string",
"maxLength": 100,
"example": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skills": [
{
"skill_name": "Git",
"skill_id": "ed8a3b44-59a0-44a6-a283-6c0e4b303be1"
},
{
"skill_name": "Jenkins",
"skill_id": "eebcf485-9045-4669-a6f7-6e7faa465ff9"
},
{
"skill_name": "Kubernetes",
"skill_id": "94835c7e-4135-40d7-aea6-165b33d01589"
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skills": [
{
"skill_name": "Balance Sheet",
"skill_id": "8313fe8a-f39e-4a35-8c82-93b46c3de9bb"
},
{
"skill_name": "IFRS",
"skill_id": "bdb5ee3f-8ba0-4c40-92b2-0277431ae069"
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"has_next": true,
"records": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
}
]
}
]
}
]
}
]
}
],
"next_starting_after": "61a6e076-d780-11ec-9d64-0242ac120002"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/skills": {
"post": {
"tags": [
"TaxonomyExport"
],
"summary": "Export Skill info",
"description": "\n\nExport the information for all Skills in the system. Results are paginated by default with a fixed limit of 50,000. This limit is required due to the large dataset size. Setting a lower limit would not improve performance and is therefore not supported.\n",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "The display language used for Skill names and descriptions. Altering the vocabulary language does **not** change Skill attributes; 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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional Skill info attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"properties",
"custom_properties",
"default_skill_name",
"default_skill_description",
"inference_enabled",
"business_relevant",
"output_language"
]
},
"example": [
"properties"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"default": 50000,
"description": "The number of Skills to show on a single page.",
"example": 200
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The universally unique ID of the Skill to continue looking from. This consists of alphanumeric characters, hyphens and underscores.",
"example": "4cbdbabe-5644-4423-8157-520f8a2f429a"
},
"filters": {
"type": "object",
"description": "List of filters to be applied on the Skills",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skill_source",
"required": [
"filter",
"skill_source"
],
"properties": {
"filter": {
"type": "string",
"description": "Only include Skills with the `skill_source` attribute set to the passed value. If the filter is not set, all Skills will be included.",
"enum": [
"skill_source"
],
"example": "skill_source"
},
"skill_source": {
"type": "string",
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"enum": [
"custom",
"vocabulary"
],
"example": "vocabulary"
}
}
},
{
"type": "object",
"title": "skill_id_is_in_list",
"required": [
"filter",
"skill_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all Skills for which the `skill_id` is not in the passed list.",
"enum": [
"skill_id_is_in_list"
],
"example": "skill_id_is_in_list"
},
"skill_ids": {
"type": "array",
"description": "List of `skill_id`s of Skills.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
}
]
},
"example": [
{
"filter": "skill_source",
"skill_source": "vocabulary"
},
{
"filter": "skill_id_is_in_list",
"skill_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
}
]
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"has_next"
],
"properties": {
"records": {
"description": "A list containing for every Skill in the system the available data, including descriptions and their location in the Taxonomy.",
"type": "array",
"items": {
"oneOf": [
{
"title": "No Taxonomy or 3-level Taxonomy",
"description": "Default structure for Skill.",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description",
"skill_source",
"techwolf_domain",
"taxonomy_skill_cluster_id",
"taxonomy_skill_cluster_name",
"taxonomy_domain_id",
"taxonomy_domain_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. If a custom name is provided, it will be returned; otherwise, the default name in the system is returned.",
"example": "Python"
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
},
"inference_enabled": {
"type": "boolean",
"description": "Whether the Skill can be inferred. For Skills in the vocabulary, this is always true. Only present when requested via the `include` query parameter.",
"example": true
},
"default_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "The default name of the Skill available in the system. This name may differ from the actual name if the Skill's name was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language"
},
"default_skill_description": {
"type": "string",
"minLength": 1,
"nullable": true,
"description": "The default description of the Skill available in the system. This description may differ from the actual description if the Skill's description was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python Programming Language\" requires the ability to write code in the Python programming language."
},
"techwolf_domain": {
"type": "string",
"example": "Software Development",
"description": "The TechWolf Domain of the Skill."
},
"taxonomy_domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"taxonomy_domain_name": {
"type": "string",
"example": "Computer Science",
"description": "The Taxonomy Domain of the Skill."
},
"taxonomy_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"taxonomy_skill_cluster_name": {
"type": "string",
"example": "Programming Languages",
"description": "The Taxonomy Skill Cluster of the Skill."
},
"output_language": {
"type": "string",
"example": "en_uk",
"description": "The language the Skill's information was resolved from. Matches the requested `vocab_language` only when the Skill has information available in that language; any other value means a fallback language was used. Only present when `include=output_language` is specified."
},
"business_relevant": {
"type": "boolean",
"example": true,
"description": "Whether the Skill is marked as business relevant. Only present when `include=business_relevant` is specified."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
},
{
"title": "4-level Taxonomy",
"description": "Default structure for Skill.",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description",
"skill_source",
"techwolf_domain",
"taxonomy_skill_cluster_id",
"taxonomy_skill_cluster_name",
"taxonomy_subdomain_id",
"taxonomy_subdomain_name",
"taxonomy_domain_id",
"taxonomy_domain_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. If a custom name is provided, it will be returned; otherwise, the default name in the system is returned.",
"example": "Python"
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
},
"inference_enabled": {
"type": "boolean",
"description": "Whether the Skill can be inferred. For Skills in the vocabulary, this is always true. Only present when requested via the `include` query parameter.",
"example": true
},
"default_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "The default name of the Skill available in the system. This name may differ from the actual name if the Skill's name was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language"
},
"default_skill_description": {
"type": "string",
"minLength": 1,
"nullable": true,
"description": "The default description of the Skill available in the system. This description may differ from the actual description if the Skill's description was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python Programming Language\" requires the ability to write code in the Python programming language."
},
"techwolf_domain": {
"type": "string",
"example": "Software Development",
"description": "The TechWolf Domain of the Skill."
},
"taxonomy_domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"taxonomy_domain_name": {
"type": "string",
"example": "Computer Science",
"description": "The Taxonomy Domain of the Skill."
},
"taxonomy_subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"taxonomy_subdomain_name": {
"type": "string",
"example": "Programming",
"description": "The Taxonomy Subdomain of the Skill."
},
"taxonomy_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"taxonomy_skill_cluster_name": {
"type": "string",
"example": "Programming Languages",
"description": "The Taxonomy Skill Cluster of the Skill."
},
"output_language": {
"type": "string",
"example": "en_uk",
"description": "The language the Skill's information was resolved from. Matches the requested `vocab_language` only when the Skill has information available in that language; any other value means a fallback language was used. Only present when `include=output_language` is specified."
},
"business_relevant": {
"type": "boolean",
"example": true,
"description": "Whether the Skill is marked as business relevant. Only present when `include=business_relevant` is specified."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
]
}
},
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"type": "string",
"maxLength": 100,
"example": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e"
}
}
},
"examples": {
"NoTaxonomyExample": {
"summary": "No Taxonomy",
"value": {
"records": [
{
"skill_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"skill_name": "Java Programming Language",
"skill_description": "Java is a high-level programming language with an intuitive syntax and a versatile standard library.",
"skill_source": "vocabulary",
"inference_enabled": true,
"default_skill_name": "Java Programming Language",
"default_skill_description": "Java is a high-level programming language with an intuitive syntax and a versatile standard library.",
"techwolf_domain": "Software Development",
"taxonomy_domain_id": null,
"taxonomy_domain_name": null,
"taxonomy_skill_cluster_id": null,
"taxonomy_skill_cluster_name": null
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python Programming",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.",
"skill_source": "vocabulary",
"inference_enabled": true,
"default_skill_name": "Python Programming",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.",
"techwolf_domain": "Software Development",
"taxonomy_domain_id": null,
"taxonomy_domain_name": null,
"taxonomy_skill_cluster_id": null,
"taxonomy_skill_cluster_name": null
}
],
"has_next": true,
"next_starting_after": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e"
}
},
"3levelExample": {
"summary": "3-level Taxonomy",
"value": {
"records": [
{
"skill_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"skill_name": "Java Programming Language",
"skill_description": "Java is a high-level programming language with an intuitive syntax and a versatile standard library.",
"skill_source": "vocabulary",
"inference_enabled": true,
"default_skill_name": "Java Programming Language",
"default_skill_description": "Java is a high-level programming language with an intuitive syntax and a versatile standard library.",
"techwolf_domain": "Software Development",
"taxonomy_domain_id": null,
"taxonomy_domain_name": null,
"taxonomy_skill_cluster_id": null,
"taxonomy_skill_cluster_name": null
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python Programming",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.",
"skill_source": "vocabulary",
"inference_enabled": true,
"default_skill_name": "Python Programming",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.",
"techwolf_domain": "Software Development",
"taxonomy_domain_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"taxonomy_domain_name": "Computer Science",
"taxonomy_skill_cluster_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"taxonomy_skill_cluster_name": "Programming Languages"
}
],
"has_next": true,
"next_starting_after": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e"
}
},
"4levelExample": {
"summary": "4-level Taxonomy",
"value": {
"records": [
{
"skill_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"skill_name": "Java Programming Language",
"skill_description": "Java is a high-level programming language with an intuitive syntax and a versatile standard library.",
"skill_source": "vocabulary",
"inference_enabled": true,
"default_skill_name": "Java Programming Language",
"default_skill_description": "Java is a high-level programming language with an intuitive syntax and a versatile standard library.",
"techwolf_domain": "Software Development",
"taxonomy_domain_id": null,
"taxonomy_domain_name": null,
"taxonomy_subdomain_id": null,
"taxonomy_subdomain_name": null,
"taxonomy_skill_cluster_id": null,
"taxonomy_skill_cluster_name": null
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python Programming",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.",
"skill_source": "vocabulary",
"inference_enabled": true,
"default_skill_name": "Python Programming",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.",
"techwolf_domain": "Software Development",
"taxonomy_domain_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"taxonomy_domain_name": "Computer Science",
"taxonomy_subdomain_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"taxonomy_subdomain_name": "Programming",
"taxonomy_skill_cluster_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"taxonomy_skill_cluster_name": "Programming Languages"
}
],
"has_next": true,
"next_starting_after": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families": {
"get": {
"tags": [
"JobFamilyCRUD"
],
"summary": "List Job Families",
"description": "Get a list of all Job Families available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Job Family objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Job Families",
"description": "Subset of Job Families starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Job Family.",
"type": "object",
"title": "job_family_content",
"required": [
"external_id",
"job_family_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_family_name": {
"type": "string",
"example": "Software Engineer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family."
},
"job_family_group": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family Group."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job Family will not be used in matching if active is `false`. This is useful when a Job Family is being phased out."
}
}
},
{
"type": "object"
},
{
"required": [
"external_id",
"job_family_name"
]
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"active": true,
"job_family_name": "Software Engineer",
"job_family_group": "IT & Engineering"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"active": true,
"job_family_name": "Data Scientist",
"job_family_group": "IT & Engineering"
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"active": true,
"job_family_name": "Data Engineer",
"job_family_group": "IT & Engineering"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"JobFamilyCRUD"
],
"summary": "Create Job Family",
"description": "Submit new Job Family information to initialise their Job Family inside the Skill Engine API.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Job Family.",
"type": "object",
"title": "job_family_content",
"required": [
"external_id",
"job_family_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_family_name": {
"type": "string",
"example": "Software Engineer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family."
},
"job_family_group": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family Group."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job Family will not be used in matching if active is `false`. This is useful when a Job Family is being phased out."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}": {
"get": {
"tags": [
"JobFamilyCRUD"
],
"summary": "Get Job Family",
"description": "Get the Job Family information stored inside the system.",
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "The unique Job Family ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Job Family.",
"type": "object",
"title": "job_family_content",
"required": [
"external_id",
"job_family_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_family_name": {
"type": "string",
"example": "Software Engineer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family."
},
"job_family_group": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family Group."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job Family will not be used in matching if active is `false`. This is useful when a Job Family is being phased out."
}
}
},
{
"title": "AttributeInclude",
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
}
],
"example": [
{
"property_name": "creation_date",
"property_value": "2020-03-07"
},
{
"property_name": "language",
"property_value": "de"
}
]
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobFamilyCRUD"
],
"summary": "Update Job Family",
"description": "Submit the most up-to-date Job Family information. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is.",
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "The unique Job Family ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating Job Family Data.",
"type": "object",
"properties": {
"job_family_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software Engineer",
"description": "Name of the Job Family."
},
"job_family_group": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job Family Group."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job Family will not be used in matching if active is `false`. This is useful when a Job Family is being phased out."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"JobFamilyCRUD"
],
"summary": "Delete Job Family",
"description": "Delete the Job Family information stored inside the system. By deleting the Job Family, all Job Family Profile Data is also deleted, together with every Job which is linked to this Job Family.",
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "The unique Job Family ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}/skill_profile": {
"get": {
"tags": [
"JobFamilyProfile"
],
"summary": "Get the Skill Profile for a Job Family",
"description": "Get an export of the Job Family Skill Profile to leverage it for user interaction. The response includes both governed and suggested Skills, distinguished by their `validation_state`.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant. When specified, the query parameter `include=skill_validation_state` will not work, as it is not supported on external vendor Skill Profiles.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "proficiency_level&include=critical",
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"proficiency_level",
"proficiency_float",
"critical",
"properties"
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result is returned. The profile consists of a list of Skills with their Domain names and Skill types.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"domain_name",
"validation_state",
"source_data"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"domain_name": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The Domain name of the Skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"source_data": {
"type": "array",
"description": "The source data for this Skill includes the Job Data objects of all Jobs within the Job Family that contain this Skill, along with the Job Family Data objects of the Job Family that include this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
},
"example": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Deep Learning",
"skill_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
}
]
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Deep Learning",
"skill_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobFamilyProfile"
],
"summary": "Partially update a Job Family Skill Profile with feedback",
"description": "Provide feedback about an existing Job Family Skill Profile to update it inside\nthe system. When the `feedback_format` query parameter is `skills`,\nthe body of the feedback message overwrites, adds or updates Skills in the original profile.\n",
"parameters": [
{
"in": "query",
"name": "feedback_format",
"required": false,
"description": "The format in which feedback for the Skill Profile is given.",
"schema": {
"type": "string",
"example": "skills",
"enum": [
"skills",
"external_vendor_skills"
],
"default": "skills"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Either `skill` or `skill_id` must be provided, but not both.",
"items": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present. Cannot be `false` if the Skill is not present in the Skill Profile of the entity."
},
"proficiency_level": {
"description": "The required proficiency level for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"proficiency_float": {
"description": "The required proficiency level (passed as a float) for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
},
"critical": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the Skill is critical for the entity. Setting this to `null` will remove the critical flag from the Skill. You can only set this for a Skill that is validated (`has_skill` should be `true`)."
}
}
}
]
},
"example": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"has_skill": true
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"has_skill": true,
"proficiency_level": 2
},
{
"skill_id": "a05c0764-3cde-9200-b6a4-dds7639987ff",
"has_skill": true,
"proficiency_float": 0.4,
"critical": null
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"has_skill": false
}
]
}
}
},
{
"title": "External Vendor Skills",
"type": "object",
"properties": {
"source_vendor": {
"allOf": [
{
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
],
"description": "The external vendor's vocabulary in which feedback is provided. The vendor must be activated on the tenant for this to work."
},
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "workday"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Both the `skill` and the `skill_id` must be provided.",
"items": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill",
"skill_id",
"has_skill"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning (ML)",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present. Cannot be `false` if the Skill is not present in the Skill Profile of the entity."
},
"proficiency_level": {
"description": "The required proficiency level for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"proficiency_float": {
"description": "The required proficiency level (passed as a float) for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
},
"critical": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the Skill is critical for the entity. Setting this to `null` will remove the critical flag from the Skill. You can only set this for a Skill that is validated (`has_skill` should be `true`)."
}
}
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "111-AAA",
"has_skill": true,
"proficiency_level": 3
},
{
"skill": "Python",
"skill_id": "111-BBB",
"has_skill": true,
"proficiency_float": null,
"critical": null
},
{
"skill": "Tensorflow",
"skill_id": "111-CCC",
"has_skill": false
}
]
}
}
}
]
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}/suggested_skill_profile": {
"get": {
"deprecated": true,
"tags": [
"JobFamilyProfile"
],
"summary": "Get the suggested Skill Profile for a Job Family",
"description": "**Deprecated:** Use [Get the Skill Profile for a Job Family]() instead. The Skill Profile endpoint returns both governed and suggested Skills, distinguished by their `validation_state`.\n\nGet an export of the Job Family Skill Profile to leverage it for user interaction. The suggested Job Family Skill Profile automatically updates with changes to the Job Family Profile Data or Job Profile Data for any of its underlying Jobs.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "skill_validation_state",
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skill_validation_state",
"properties"
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "The default Skill Profile result returned. The profile consists of a list of skills with their domain names and skill types.",
"type": "object",
"title": "ListSkillProfile",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The skills contained in this profile.",
"items": {
"description": "Default structure for an individual skill.",
"type": "object",
"required": [
"skill",
"skill_id",
"skill_type",
"domain_name",
"source_data"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_type": {
"type": "string",
"example": "Core",
"description": "This field indicates that this is a skill present in the Job Family.",
"enum": [
"Core"
]
},
"domain_name": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The domain name of the skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated"
},
"source_data": {
"type": "array",
"description": "The source data for this Skill includes the Job Data objects of all Jobs within the Job Family that contain this Skill, along with the Job Family Data objects of the Job Family that include this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
},
"example": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_type": "Core",
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_type": "Core",
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
{
"skill": "TensorFlow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill_type": "Core",
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
}
]
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_type": "Core",
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_type": "Core",
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
{
"skill": "TensorFlow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill_type": "Core",
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
}
]
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs": {
"get": {
"tags": [
"JobCRUD"
],
"summary": "List Jobs",
"description": "Get a list of all Jobs available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
},
{
"in": "query",
"name": "job_family",
"schema": {
"type": "string",
"example": "c3903505-eb84-42dc-a79f-5d8b1fe897b7"
},
"description": "This parameter can be used to only include Jobs in the specified `job_family`. If `job_family=\"null\"`, only Jobs without a Job Family are included. If the parameter is not set, all entities will be included."
},
{
"in": "query",
"name": "low_data_availability",
"schema": {
"type": "boolean",
"example": true
},
"description": "This parameter can be used to only include entities for which sufficient data is available (`low_data_availability=false`) or is not available (`low_data_availability=true`) for qualitative Skill inference. If the parameter is not set, all entities will be included."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"job_description"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Job objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Jobs",
"description": "Subset of Jobs starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Job.",
"type": "object",
"title": "job_content",
"required": [
"external_id",
"job_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_family_id": {
"type": "string",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"minLength": 1,
"maxLength": 100,
"description": "ID of the Job Family."
},
"job_name": {
"type": "string",
"example": "Front End Developer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job will not be used in matching if active is `false`. This is useful when a Job is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
}
}
},
{
"type": "object"
},
{
"required": [
"external_id",
"job_name"
]
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-5fgqsef7b834c",
"active": true,
"job_name": "Front End Developer",
"job_family_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"low_data_availability": false,
"job_description": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications."
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"active": true,
"job_name": "Backend Developer",
"job_family_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"low_data_availability": false,
"job_description": "The Backend Developer is responsible for implementing the server-side logic of a web application."
},
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"active": true,
"job_name": "Data Scientist",
"job_family_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"low_data_availability": true,
"job_description": "The Data Scientist is responsible for analyzing data and using it to make decisions."
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"JobCRUD"
],
"summary": "Create Job",
"description": "Submit new Job information to initialise this inside the Skill Engine API. If a Job has a Job Family, the Job Skill Profile will be generated automatically, incorporating all Skills validated for the specified Job Family.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Job.",
"type": "object",
"title": "job_content",
"required": [
"external_id",
"job_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_family_id": {
"type": "string",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"minLength": 1,
"maxLength": 100,
"description": "ID of the Job Family."
},
"job_name": {
"type": "string",
"example": "Front End Developer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job will not be used in matching if active is `false`. This is useful when a Job is being phased out."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
{
"title": "Entity Limit",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "Creation has failed because you've reached the entity limit 100. You need to delete other entities to be able to create more."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}": {
"get": {
"tags": [
"JobCRUD"
],
"summary": "Get Job",
"description": "Get a Job by its external ID. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "The unique Job ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"job_description"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "Default structure for Job.",
"type": "object",
"title": "job_content",
"required": [
"external_id",
"job_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_family_id": {
"type": "string",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"minLength": 1,
"maxLength": 100,
"description": "ID of the Job Family."
},
"job_name": {
"type": "string",
"example": "Front End Developer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job will not be used in matching if active is `false`. This is useful when a Job is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
}
}
},
{
"title": "AttributeInclude",
"type": "object",
"required": [
"last_updated"
],
"properties": {
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
}
],
"example": [
{
"property_name": "creation_date",
"property_value": "2020-03-07"
},
{
"property_name": "language",
"property_value": "de"
}
]
},
"job_description": {
"type": "string",
"description": "Primary job description of the Job. When a Job has more than one job description, this is the one set as primary. Change it with `job_description_id` on Update Job.",
"example": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications."
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobCRUD"
],
"summary": "Update Job",
"description": "Update a Job by its external ID. If you change the Job Family, it will result in the loss of all Skills validated for the previous Job Family and the addition of all Skills validated for the new Job Family. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "The unique Job ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating Job Data.",
"type": "object",
"properties": {
"job_family_id": {
"type": "string",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"minLength": 1,
"maxLength": 100,
"description": "ID of the Job Family."
},
"job_name": {
"type": "string",
"example": "Front End Developer",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Job."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Job will not be used in matching if active is `false`. This is useful when a Job is being phased out."
},
"job_description_id": {
"type": "string",
"example": "3f1c2a9e-7b4d-4e2a-9c61-0d8e5b7a4f12",
"description": "External ID of the Job Profile Data with data type `job_description` to use as the primary job description of this Job. The Profile Data must belong to this Job. The first job description added to a Job becomes its primary job description. Adding more job descriptions does not change it; set this field to switch."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"JobCRUD"
],
"summary": "Delete Job",
"description": "Delete a Job by its external ID.\n Delete the Job information stored inside the system. By deleting the Job, all Job Profile Data is also deleted.\n Recalculates the Job Family Skill Profile if the Job Family is specified for the Job.",
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "The unique Job ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/skill_profile": {
"get": {
"tags": [
"JobProfile"
],
"summary": "Get the Skill Profile for a Job",
"description": "Get an export of the Job Skill Profile to leverage it for user interaction. The response includes both governed and suggested Skills, distinguished by their `validation_state`.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "proficiency_level&include=critical",
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"low_data_availability_flag",
"proficiency_level",
"proficiency_float",
"critical",
"properties",
"skill_source"
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The default Skill Profile result is returned. The profile consists of a list of Skills with their Domain names and Skill types.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile.",
"items": {
"description": "Default structure for an individual Skill.",
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"domain_name",
"validation_state",
"source_data"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"domain_name": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The Domain name of the Skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"source_data": {
"type": "array",
"description": "The source data for this Skill includes the Job Data objects of the specified Job that contain this Skill, along with the Job Family Data objects of the specified Job's Job Family that include this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
},
"example": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Job-Specific",
"is_common": true
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": false
},
{
"skill": "TensorFlow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill_types": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
},
{
"skill": "Deep Learning",
"skill_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"low_data_availability": false,
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": false
},
{
"skill": "TensorFlow",
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"skill_types": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
],
"domain_name": "Data Science",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
},
{
"skill": "Deep Learning",
"skill_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": true
}
]
}
},
"listExternalVendorExample": {
"summary": "List external vendor",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"low_data_availability": false,
"skills": [
{
"skill": "Machine Learning",
"skill_id": "111-AAA",
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "Python",
"skill_id": "111-BBB",
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "TensorFlow",
"skill_id": "111-CCC",
"governed_proficiency_level": 1,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": null,
"governed_critical": false,
"inferred_critical": null
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
},
"hierarchyExternalVendorxample": {
"summary": "Hierarchy External Vendor",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "111-BBB"
},
{
"skill": "Java",
"skill_id": "111-DDD"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "111-CCC"
},
{
"skill": "C#",
"skill_id": "111-AAA"
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobProfile"
],
"summary": "Partially update a Job Skill Profile with feedback",
"description": "Provide feedback about an existing Job Skill Profile to update it inside\nthe system. When the `feedback_format` query parameter is `skills`,\nthe body of the feedback message will overwrite, add or update Skills in the original profile.\nThis endpoint allows you to validate skills and add/remove properties such as proficiency levels and criticality.\n",
"parameters": [
{
"in": "query",
"name": "feedback_format",
"required": false,
"description": "The format in which feedback for the Skill Profile is given.",
"schema": {
"type": "string",
"example": "skills",
"enum": [
"skills",
"external_vendor_skills"
],
"default": "skills"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "oracle"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Either `skill` or `skill_id` must be provided, but not both.",
"items": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present. Cannot be `false` if the Skill is not present in the Skill Profile of the entity."
},
"proficiency_level": {
"description": "The required proficiency level for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"proficiency_float": {
"description": "The required proficiency level (passed as a float) for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
},
"critical": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the Skill is critical for the entity. Setting this to `null` will remove the critical flag from the Skill. You can only set this for a Skill that is validated (`has_skill` should be `true`)."
}
}
}
]
},
"example": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"has_skill": true
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"has_skill": true,
"proficiency_level": 2
},
{
"skill_id": "a05c0764-3cde-9200-b6a4-dds7639987ff",
"has_skill": true,
"proficiency_float": 0.4,
"critical": null
},
{
"skill_id": "e03c1859-3bae-4700-b2c5-ede2937038de",
"has_skill": false
}
]
}
}
},
{
"title": "External Vendor Skills",
"type": "object",
"properties": {
"source_vendor": {
"allOf": [
{
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
],
"description": "The external vendor's vocabulary in which feedback is provided. The vendor must be activated on the tenant for this to work."
},
"source": {
"type": "string",
"description": "The source of the Skill Profile update.",
"example": "workday"
},
"skills": {
"type": "array",
"description": "The Skills contained in this profile. Both the `skill` and the `skill_id` must be provided.",
"items": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill",
"skill_id",
"has_skill"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning (ML)",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present. Cannot be `false` if the Skill is not present in the Skill Profile of the entity."
},
"proficiency_level": {
"description": "The required proficiency level for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"proficiency_float": {
"description": "The required proficiency level (passed as a float) for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
},
"critical": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the Skill is critical for the entity. Setting this to `null` will remove the critical flag from the Skill. You can only set this for a Skill that is validated (`has_skill` should be `true`)."
}
}
}
]
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "111-AAA",
"has_skill": true,
"proficiency_level": 3
},
{
"skill": "Python",
"skill_id": "111-BBB",
"has_skill": true,
"proficiency_float": null,
"critical": null
},
{
"skill": "Tensorflow",
"skill_id": "111-CCC",
"has_skill": false
}
]
}
}
}
]
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/task_profile": {
"get": {
"tags": [
"JobTaskProfile"
],
"summary": "Get the Task Profile for a Job",
"description": "\n\nRetrieve the Task Profile associated with a Job. The response contains a\nlist of tasks assigned to the Job. Use the `include` query parameter to\noptionally expand each task with AI impact information and/or the source\ndata (job profile data entries) that contributed to the task being assigned.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"name": "job_external_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The external identifier of the Job.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ai_impact",
"source_data",
"linked_skills",
"rejected_tasks",
"weekly_hours"
]
}
},
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.\n\n- `ai_impact` — includes AI impact level and rationale per task.\n- `source_data` — includes the job profile data entries behind each task.\n- `linked_skills` — includes Skills linked to each task, with Skill ID and name. Use the `external_vendor` query parameter to display Skill names in an external vendor vocabulary.\n- `rejected_tasks` — includes tasks that were rejected via PATCH feedback (excluded by default).\n- `weekly_hours` — includes the estimated number of hours spent on each task per week.\n",
"example": [
"ai_impact",
"source_data"
]
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "The format of the response profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "List",
"description": "The default Task Profile result is returned. The profile consists of a flat list of Tasks assigned to the Job.",
"type": "object",
"required": [
"external_id",
"tasks"
],
"properties": {
"external_id": {
"type": "string",
"description": "The Job's external_id.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"tasks": {
"type": "array",
"description": "List of tasks in the Job's profile.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager via Job feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_data": {
"type": "array",
"description": "Job profile data entries that contributed to this task (only present when include=source_data).",
"items": {
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the job profile data entry.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
},
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"linked_skills": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
},
{
"title": "Hierarchy",
"description": "The Task Profile result is returned in a hierarchical structure grouped by domain → subdomain → cluster → canonical task. Tasks without a fully-populated hierarchy are placed in `tasks_outside_hierarchy`.",
"type": "object",
"required": [
"external_id",
"domains",
"tasks_outside_hierarchy"
],
"properties": {
"external_id": {
"type": "string",
"description": "The Job's external_id.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"domains": {
"type": "array",
"description": "Tasks grouped by domain → subdomain → cluster → canonical task.",
"items": {
"type": "object",
"required": [
"domain_name",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "Name of the task hierarchy domain.",
"example": "Computer Science"
},
"domain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy domain.",
"example": "576132d7-83d2-bcba-78db-e14c073409dd"
},
"subdomains": {
"type": "array",
"items": {
"type": "object",
"required": [
"subdomain_name",
"clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "Name of the task hierarchy subdomain.",
"example": "Software Engineering"
},
"subdomain_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy subdomain.",
"example": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab"
},
"clusters": {
"type": "array",
"items": {
"type": "object",
"required": [
"cluster_name",
"canonical_tasks"
],
"properties": {
"cluster_name": {
"type": "string",
"description": "Name of the task hierarchy cluster.",
"example": "Programming Languages"
},
"cluster_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the task hierarchy cluster.",
"example": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1"
},
"canonical_tasks": {
"type": "array",
"items": {
"type": "object",
"required": [
"canonical_task_name",
"tasks"
],
"properties": {
"canonical_task_name": {
"type": "string",
"description": "Name of the canonical task.",
"example": "Standardized Testing"
},
"canonical_task_id": {
"type": "string",
"nullable": true,
"description": "Stable id of the canonical task.",
"example": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3"
},
"tasks": {
"type": "array",
"description": "Tasks under this canonical task.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager via Job feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_data": {
"type": "array",
"description": "Job profile data entries that contributed to this task (only present when include=source_data).",
"items": {
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the job profile data entry.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"tasks_outside_hierarchy": {
"type": "array",
"description": "Tasks where at least one hierarchy field is null or missing.",
"items": {
"type": "object",
"required": [
"task_id",
"task",
"validation_state"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of a Task.",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"task": {
"type": "string",
"description": "Name/description of the task.",
"example": "Conduct machine learning experiments for the Weather Application"
},
"validation_state": {
"type": "string",
"enum": [
"suggested",
"validated",
"rejected"
],
"description": "This field indicates whether this Task is already validated by a manager via Job feedback or still in the suggested state.\n",
"example": "suggested"
},
"ai_impact": {
"description": "AI impact information (only present when include=ai_impact).",
"type": "object",
"required": [
"level",
"rationale"
],
"properties": {
"level": {
"type": "string",
"description": "The AI impact level of the task, expressed as a Human Agency Scale (HAS) level. HAS is a five-level scale\nintroduced by Stanford's Future of Work with AI Agents research (https://futureofwork.saltlab.stanford.edu/)\nto quantify the degree of human involvement required for completing an occupational task and ensuring its quality.\nIt complements automation-focused frameworks by centering human agency, ranging from full automation to tasks\nwhere human involvement is essential. Levels are ordered from most automatable to least automatable:\n\n`H1` = No Human Involvement — task can be fully automated by AI with no human input required.\n`H2` = Human Involvement at Key Points — AI handles most of the task; humans intervene at critical decision points.\n`H3` = Equal Partnership — humans and AI contribute roughly equally; neither can complete the task alone at the desired quality.\n`H4` = Human Involvement at Majority of the Time — humans drive the task; AI plays a supporting or assistive role.\n`H5` = Human Involvement Essential — the task fundamentally requires human judgment, creativity, or interpersonal skill; AI has minimal meaningful contribution.\n",
"enum": [
"H1",
"H2",
"H3",
"H4",
"H5"
],
"example": "H2"
},
"rationale": {
"type": "string",
"description": "Explanation of the AI impact level for this task.",
"example": "Portions can be automated via LLM test generation"
}
}
},
"weekly_hours": {
"type": "integer",
"minimum": 1,
"maximum": 40,
"description": "Estimated number of hours spent on this task per week (only present when include=weekly_hours).",
"example": 5
},
"linked_skills": {
"type": "array",
"description": "Skills linked to this task (only present when include=linked_skills).\nSkills not found at request time are filtered out of the response.\n",
"items": {
"type": "object",
"required": [
"skill_id",
"skill"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the Skill.",
"example": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
"skill": {
"type": "string",
"description": "Name of the Skill in the requested vocabulary language.",
"example": "Python"
}
}
}
},
"source_data": {
"type": "array",
"description": "Job profile data entries that contributed to this task (only present when include=source_data).",
"items": {
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"description": "External ID of the job profile data entry.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"clusters": [
{
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_tasks": [
{
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
]
}
]
}
]
}
],
"tasks_outside_hierarchy": [
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"linked_skills": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill": "Python"
},
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
},
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"linked_skills": [
{
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"skill": "Machine Learning"
}
],
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"domain_id": "576132d7-83d2-bcba-78db-e14c073409dd",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"subdomain_id": "ebf24b7d-a4a2-ba09-bb39-d8bc569608ab",
"clusters": [
{
"cluster_name": "Programming Languages",
"cluster_id": "f8df9c90-9686-4f9e-06ca-cb52b63ffef1",
"canonical_tasks": [
{
"canonical_task_name": "Standardized Testing",
"canonical_task_id": "2213cfe4-d3dd-f568-b7e9-be8c0089f9f3",
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"task": "Conduct machine learning experiments on customer datasets",
"validation_state": "validated",
"weekly_hours": 5,
"ai_impact": {
"level": "H1",
"rationale": "Highly automatable with AI-powered experiment tooling"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
]
}
]
}
]
}
],
"tasks_outside_hierarchy": [
{
"task_id": "7446d003-425e-8e8c-c723-0a3790b38841",
"task": "Review model outputs against ground-truth labels",
"validation_state": "suggested",
"ai_impact": {
"level": "H3",
"rationale": "Requires human judgment to evaluate model quality"
},
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobTaskProfile"
],
"summary": "Provide feedback on tasks in a Job's Task Profile",
"description": "\n\nProvide feedback on one or more tasks in a Job's Task Profile.\n\n**Note:** This endpoint is experimental and may change in future versions.\n",
"parameters": [
{
"name": "job_external_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The external identifier of the Job.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tasks"
],
"properties": {
"tasks": {
"type": "array",
"description": "List of task feedback items.",
"items": {
"type": "object",
"required": [
"task_id",
"has_task"
],
"properties": {
"task_id": {
"description": "Unique identifier of the task to provide feedback on.",
"type": "string",
"format": "uuid",
"example": "56dcdb53-264e-f380-50bf-5179e2d082af"
},
"has_task": {
"type": "boolean",
"description": "Whether the task applies to this entity. Set to `true` to mark the task\nas `validated`, or `false` to mark it as `rejected`.\n\nOnly tasks currently in the `suggested` or `validated` state may be rejected\n(i.e., have `has_task` set to `false`).\n",
"example": true
}
}
}
},
"source": {
"type": "string",
"description": "Optional identifier of the source of this feedback.",
"example": "workday"
}
}
},
"example": {
"tasks": [
{
"task_id": "d1072baf-6f9b-bdb3-fb26-f790c10d4803",
"has_task": true
},
{
"task_id": "cf13c829-9ffa-b577-7046-0f5df5f1f8eb",
"has_task": false
}
],
"source": "workday"
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/suggested_skill_profile": {
"get": {
"deprecated": true,
"tags": [
"JobProfile"
],
"summary": "Get the suggested Skill Profile for a Job",
"description": "**Deprecated:** Use [Get the Skill Profile for a Job](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile) instead. The Skill Profile endpoint returns both governed and suggested Skills, distinguished by their `validation_state`.\n\nGet an export of the Job Skill Profile to leverage it for user interaction. The suggested Job Skill Profile automatically updates with changes to the Job Profile Data.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "skill_validation_state&include=critical",
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skill_validation_state",
"critical",
"properties"
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "ListSkillProfile",
"description": "The default Skill Profile result returned. The profile consists of a list of skills with their domain names and skill types.",
"type": "object",
"required": [
"external_id",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skills": {
"type": "array",
"description": "The skills contained in this profile.",
"items": {
"description": "Default structure for an individual skill.",
"type": "object",
"required": [
"skill",
"skill_id",
"skill_type",
"domain_name",
"source_data"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether the Skill is specific for this Job, or typical for the Job Family of this Job. The latter is called a Core skill, the former a Job-Specific skill.",
"enum": [
"Core",
"Job-Specific"
]
},
"domain_name": {
"type": "string",
"minLength": 1,
"example": "Data Science",
"description": "The domain name of the skill."
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated"
},
"source_data": {
"type": "array",
"description": "The source data for this Skill includes the Job Data objects of the specified Job that contain this Skill, along with the Job Family Data objects of the specified Job's Job Family that include this Skill.",
"items": {
"type": "object",
"required": [
"external_id",
"source_data_type"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"source_data_type": {
"type": "string",
"description": "The type of source data. This can be Job Data or Job Family Data.",
"enum": [
"job_profile_data",
"job_family_profile_data"
]
}
}
},
"example": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_family_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
]
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the suggested Skill is considered critical for the entity. If there is no information about the criticality of the Skill, all criticalities will equal false. In cases where criticality is inferred, the inference is based on available data such as Job Profile Data and Job Family Profile Data."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
},
"example": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_type": "Job-Specific",
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"critical": true
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_type": "Core",
"domain_name": "Programming",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
},
{
"external_id": "12a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_family_profile_data"
}
],
"critical": false
}
]
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of Skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Family-Specific",
"description": "This field indicates whether a Skill is a Family-Specific Skill.",
"enum": [
"Family-Specific"
]
}
},
"example": [
{
"skill_type": "Family-Specific"
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id",
"skill_types",
"validation_state"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_types": {
"type": "array",
"description": "A list of skill types.",
"items": {
"description": "A Skill type.",
"type": "object",
"required": [
"skill_type"
],
"properties": {
"skill_type": {
"type": "string",
"example": "Job-Specific",
"description": "This field indicates whether a Skill is a Job-Specific Skill or a Family-Specific Skill.",
"enum": [
"Family-Specific",
"Job-Specific"
]
},
"is_common": {
"type": "boolean",
"example": true,
"description": "This field indicates whether a Skill is common between all Jobs in a Job Family. The `is_common` field only appears when `skill_type` is Job-Specific and when it is true."
}
},
"example": [
{
"skill_type": "Family-Specific"
},
{
"skill_type": "Job-Specific",
"is_common": true
}
]
}
},
"validation_state": {
"type": "string",
"minLength": 1,
"example": "validated",
"enum": [
"validated",
"suggested"
],
"description": "The validation state of the Skill. \"validated\" indicates that the Skill was explicitly validated using Job feedback. \"suggested\" indicates that the Skill has not yet been validated."
},
"governed_proficiency_level": {
"description": "The governed proficiency level for this Skill, as set through explicit feedback. It cannot be greater than the maximum proficiency level (default levels are 1-5). If the proficiency level is not set, the default proficiency level is returned. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 3
},
"inferred_proficiency_level": {
"description": "The inferred proficiency level for this Skill, as determined by the AI model. It cannot be greater than the maximum proficiency level (default levels are 1-5). If no inferred proficiency level is available, `null` is returned.",
"type": "integer",
"format": "int32",
"minimum": 1,
"nullable": true,
"example": 2
},
"governed_proficiency_float": {
"description": "The governed proficiency level for this Skill as a float, as set through explicit feedback. If the proficiency level is explicitly set to `null`, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.5
},
"inferred_proficiency_float": {
"description": "The inferred proficiency level for this Skill as a float, as determined by the AI model. If no inferred proficiency level is available, `null` is returned.",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true,
"example": 0.4
},
"governed_critical": {
"description": "Indicates whether the Skill has been marked as critical through explicit feedback. If there is no governed information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": true
},
"inferred_critical": {
"description": "Indicates whether the Skill has been inferred as critical by the AI model. If there is no inferred information about the criticality of the Skill, `null` is returned.",
"type": "boolean",
"nullable": true,
"example": null
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "validated",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 2,
"inferred_proficiency_level": null,
"governed_proficiency_float": 0.4,
"inferred_proficiency_float": null,
"governed_critical": true,
"inferred_critical": null
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": 3,
"governed_proficiency_float": null,
"inferred_proficiency_float": 0.6,
"governed_critical": null,
"inferred_critical": false
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Family-Specific"
}
],
"governed_proficiency_level": null,
"inferred_proficiency_level": null,
"governed_proficiency_float": null,
"inferred_proficiency_float": null,
"governed_critical": null,
"inferred_critical": null
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested",
"skill_types": [
{
"skill_type": "Job-Specific"
}
],
"governed_proficiency_level": 1,
"inferred_proficiency_level": 2,
"governed_proficiency_float": 0.2,
"inferred_proficiency_float": 0.4,
"governed_critical": null,
"inferred_critical": true
}
]
}
}
]
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skills": [
{
"skill": "Machine Learning",
"skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",
"skill_type": "Job-Specific",
"domain_name": "Data Science",
"validation_state": "suggested",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_profile_data"
}
],
"critical": true
},
{
"skill": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_type": "Core",
"domain_name": "Programming",
"validation_state": "validated",
"source_data": [
{
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"source_data_type": "job_profile_data"
},
{
"external_id": "12a6e076-d780-11ec-9d64-0242ac120002",
"source_data_type": "job_family_profile_data"
}
],
"critical": false
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59",
"validation_state": "suggested"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64",
"validation_state": "suggested"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c",
"validation_state": "suggested"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3",
"validation_state": "suggested"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/market_skill_profiles": {
"get": {
"tags": [
"JobProfile"
],
"summary": "Get the external market Skill Profiles of a Job.",
"description": "Get a list of external market Skill Profiles for a Job, based on the peer groups defined in the tenant. For every peer group, the Skill Profile is a combination of Profiles found in external market data from the companies in that peer group.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "response_format",
"required": false,
"description": "Defines the format of the returned Skill Profile.",
"schema": {
"type": "string",
"example": "list",
"enum": [
"list",
"hierarchy"
],
"default": "list"
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"properties"
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A list of external market Skill Profiles for the Job, one per peer group.",
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"peer_groups": {
"type": "array",
"description": "The peer groups for which the external market Skill Profiles are provided.",
"items": {
"type": "object",
"required": [
"peer_group",
"skills"
],
"properties": {
"peer_group": {
"type": "string",
"minLength": 1,
"description": "The name of the peer group."
},
"skills": {
"oneOf": [
{
"title": "List",
"type": "array",
"description": "The Skills contained in this external market Skill Profile.",
"items": {
"description": "Default structure for an individual Skill in market skill profiles.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
},
{
"title": "List external vendor",
"type": "array",
"description": "The Skills contained in this external market Skill Profile.",
"items": {
"description": "Default structure for an individual Skill in the external vendor vocabulary.",
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
},
{
"title": "Hierarchy",
"description": "The response format formats the Skills in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
},
{
"title": "Hierarchy External Vendor",
"description": "The response format formats the Skills in the external vendor vocabulary in a hierarchical structure. When a Taxonomy is availabe it contains Domains, Skill Clusters and Skills. If it is a 4-level Taxonomy, there is a Subdomain layer between Domains and Skill Clusters. If no Taxonomy is available, the Skills are grouped under their default Techwolf Domain.",
"required": [
"external_id",
"domains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domains": {
"type": "array",
"description": "Domains of the Skills in the Skill Profile. If no Taxonomy is avaiable, these are the Techwolf Domains.",
"items": {
"oneOf": [
{
"type": "object",
"title": "4 level Taxonomy",
"required": [
"domain_name",
"external_id",
"subdomains"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"subdomains": {
"type": "array",
"description": "List of Subdomains under the Domain.",
"items": {
"type": "object",
"required": [
"subdomain_name",
"external_id",
"skill_clusters"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Subdomain."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Subdomain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "3 level Taxonomy",
"required": [
"domain_name",
"external_id",
"skill_clusters"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Domain. This is only present when a Taxonomy is available."
},
"skill_clusters": {
"type": "array",
"description": "List of Skill Clusters under the Domain.",
"items": {
"type": "object",
"required": [
"skill_cluster_name",
"external_id",
"skills"
],
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"external_id": {
"type": "string",
"description": "The unique identifier of the Skill Cluster."
},
"skills": {
"type": "array",
"description": "List of Skills under the Skill Cluster.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
}
}
},
{
"type": "object",
"title": "No Taxonomy",
"required": [
"domain_name",
"skills"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"skills": {
"type": "array",
"description": "List of Skills directly associated with the Techwolf Domain.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
}
]
}
},
"skills_outside_taxonomy": {
"type": "array",
"description": "List of Skills that are outside of the Taxonomy. This field is only present when a Taxonomy is available.",
"items": {
"type": "object",
"required": [
"skill",
"skill_id"
],
"description": "Default structure for an individual Skill.",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
},
"example": {
"external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "111-BBB"
},
{
"skill": "Java",
"skill_id": "111-DDD"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "TensorFlow",
"skill_id": "111-CCC"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
}
]
}
}
}
}
}
},
"examples": {
"listExample": {
"summary": "List",
"value": {
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"skills": [
{
"skill": "Product Design",
"skill_id": "6d41b6d7-1c09-4f8a-a9c0-361b4c7a92f5"
},
{
"skill": "Materials Science",
"skill_id": "9eb6aebf-936d-4814-9c6f-8754becc2f53"
},
{
"skill": "Supply Chain Operations",
"skill_id": "7cfe0001-5a22-49dc-9148-077b546de5cd"
}
]
},
{
"peer_group": "Sport Watches Production",
"skills": [
{
"skill": "Embedded Systems",
"skill_id": "0af7ceb8-26fe-4210-a5c4-3c1b69721403"
},
{
"skill": "UX Design",
"skill_id": "98fc5005-abf9-41f5-b156-742654b7eacd"
},
{
"skill": "Algorithm Development",
"skill_id": "e273a7bd-1ee2-4911-979c-33423dc1ac08"
}
]
}
]
}
},
"listExternalVendorExample": {
"summary": "List External Vendor",
"value": {
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"skills": [
{
"skill": "Product Design",
"skill_id": "222-AAA"
},
{
"skill": "Materials Science",
"skill_id": "222-BBB"
},
{
"skill": "Supply Chain Operations",
"skill_id": "222-CCC"
}
]
},
{
"peer_group": "Sport Watches Production",
"skills": [
{
"skill": "Embedded Systems",
"skill_id": "333-AAA"
},
{
"skill": "UX Design",
"skill_id": "333-BBB"
},
{
"skill": "Algorithm Development",
"skill_id": "333-CCC"
}
]
}
]
}
},
"hierarchyExample": {
"summary": "Hierarchy",
"value": {
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "4dba81ae-9a4d-4863-8157-520f8a2f4c59"
},
{
"skill": "Java",
"skill_id": "15aa59ae-9a4d-4863-8157-520f8a2f4e64"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "C++",
"skill_id": "8a7a4f7b-b8ef-4f82-bb8e-7469f876cf5c"
},
{
"skill": "C#",
"skill_id": "72adf84b-24a8-41d6-a4b4-e6f53c473cb3"
}
]
}
]
}
},
"hierarchyExternalVendorExample": {
"summary": "Hierarchy",
"value": {
"external_id": "09de5e58-5161-4ad1-a256-6d01a025914b",
"peer_groups": [
{
"peer_group": "Athletic Sportswear Manufacturing",
"domains": [
{
"domain_name": "Computer Science",
"external_id": "d8b6e1a3-3b0f-4a0f-bec9-52f8452d4e6c",
"subdomains": [
{
"subdomain_name": "Software Engineering",
"external_id": "cb62f1b7-d6e2-4f8c-b55b-3a25d4861d32",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"external_id": "f074ea9e-5431-4e8d-992e-2abe21868b45",
"skills": [
{
"skill": "Python",
"skill_id": "111-BBB"
},
{
"skill": "Java",
"skill_id": "111-DDD"
}
]
}
]
}
]
}
],
"skills_outside_taxonomy": [
{
"skill": "TensorFlow",
"skill_id": "111-CCC"
}
]
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}/profile_data": {
"get": {
"tags": [
"Job Family Profile Data"
],
"summary": "List Job Family Profile Data",
"description": "Get a list of all Job Family Profile Data available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "The unique Job Family ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Job Family Profile Data objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Job Family Profile Data",
"description": "Subset of Job Family Profile Data starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Job Family Profile Data.",
"type": "object",
"required": [
"external_id",
"data_type",
"timestamp",
"source",
"data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"data_type": {
"description": "Type of the Job Family Profile Data.",
"type": "string",
"enum": [
"job_family_description",
"skill_profile_feedback"
],
"example": "job_family_description"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Job Family Profile is considered to have obtained the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source of the Job Family Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Family Profile Data. The content should align with the `data_type`.",
"oneOf": [
{
"description": "Default structure for Job Family Description content.",
"type": "object",
"title": "job_family_description_content",
"required": [
"job_family_description"
],
"properties": {
"job_family_description": {
"type": "string",
"example": "Software engineers are responsible for designing, developing, and testing software. They are involved in the entire software development process, from the initial specification of requirements to the final release of the software.",
"minLength": 1,
"description": "Textual description of the Job Family."
}
}
},
{
"description": "Default structure for Job Family Description file content.",
"type": "object",
"title": "job_family_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"title": "skill_profile_feedback",
"description": "Default structure for Job Family Profile Feedback Data.",
"type": "object",
"required": [
"external_vendor",
"feedback_format",
"skills"
],
"properties": {
"external_vendor": {
"description": "Name of the (external) vendor in which the Job Family Profile feedback is provided. If the `feedback_format` is `external_skills`, the value should be an external vendor (`workday`), otherwise it should be `techwolf`.",
"type": "string"
},
"feedback_format": {
"type": "string",
"enum": [
"skills",
"external_vendor_skills"
]
},
"skills": {
"description": "The Skills contained in the Job Family Profile. The content should align with the `feedback_format`.",
"oneOf": [
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "Feedback Skill List",
"items": {
"title": "skills_feedback",
"description": "Default structure for Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
},
"example": [
{
"external_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Java",
"description": "Java programming language",
"has_skill": true
},
{
"external_id": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Python",
"description": "Python programming language",
"has_skill": false
}
]
},
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "External Vendor Feedback Skill List",
"items": {
"title": "external_vendor_skills_feedback",
"description": "Default structure for External Vendor Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"techwolf_skill",
"techwolf_skill_id",
"external_skill_name",
"external_skill_id",
"has_skill"
],
"properties": {
"techwolf_skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"techwolf_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"external_skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"external_skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
}
}
]
}
}
}
]
}
}
},
{
"type": "object"
},
{
"required": [
"external_id",
"data_type",
"timestamp",
"source",
"data"
]
}
]
},
"example": [
{
"external_id": "5cb55dbe-5444-1233-8157-520f8a2f429a",
"data_type": "job_family_description",
"timestamp": "2018-11-07T00:25:00.073876",
"source": "Workday",
"data": {
"job_family_description": "Software engineers are responsible for designing, developing, and testing software. They are involved in the entire software development process, from the initial specification of requirements to the final release of the software."
}
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"data_type": "job_family_description",
"timestamp": "2019-09-07T08:21:10.793021",
"source": "Company-archive",
"data": {
"job_family_description": "Software engineers are responsible for writing and testing software. They design and develop software applications and systems."
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Job Family Profile Data"
],
"summary": "Create Job Family Profile Data for a Job Family",
"description": "Submit new Job Family Profile Data information to initialise the Job Family inside the Skill Engine API.\n\n**Note:** It may take some time for these changes to be reflected in the Job Family's final Skill Profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "The unique Job Family ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Job Family Profile Data.",
"type": "object",
"required": [
"external_id",
"data_type",
"source",
"data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"data_type": {
"description": "Type of the Job Family Profile Data.",
"type": "string",
"enum": [
"job_family_description"
],
"example": "job_family_description"
},
"source": {
"description": "The source of the Job Family Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Family Profile Data. The content should align with the ``data_type``.",
"oneOf": [
{
"description": "Default structure for Job Family Description content.",
"type": "object",
"title": "job_family_description_content",
"required": [
"job_family_description"
],
"properties": {
"job_family_description": {
"type": "string",
"example": "Software engineers are responsible for designing, developing, and testing software. They are involved in the entire software development process, from the initial specification of requirements to the final release of the software.",
"minLength": 1,
"description": "Textual description of the Job Family."
}
}
},
{
"description": "Default structure for Job Family Description file content.",
"type": "object",
"title": "job_family_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created Job Family Profile Data.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}": {
"get": {
"tags": [
"Job Family Profile Data"
],
"summary": "Get Job Family Profile Data",
"description": "Get a single Job Family Profile Data item for a Job Family.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "Unique ID linked to a Job Family, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_family_profile_data_external_id",
"required": true,
"description": "Unique ID linked to a Job Family Profile Data, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure for Job Family Profile Data.",
"type": "object",
"required": [
"external_id",
"data_type",
"timestamp",
"source",
"data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"data_type": {
"description": "Type of the Job Family Profile Data.",
"type": "string",
"enum": [
"job_family_description",
"skill_profile_feedback"
],
"example": "job_family_description"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Job Family Profile is considered to have obtained the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source of the Job Family Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Family Profile Data. The content should align with the `data_type`.",
"oneOf": [
{
"description": "Default structure for Job Family Description content.",
"type": "object",
"title": "job_family_description_content",
"required": [
"job_family_description"
],
"properties": {
"job_family_description": {
"type": "string",
"example": "Software engineers are responsible for designing, developing, and testing software. They are involved in the entire software development process, from the initial specification of requirements to the final release of the software.",
"minLength": 1,
"description": "Textual description of the Job Family."
}
}
},
{
"description": "Default structure for Job Family Description file content.",
"type": "object",
"title": "job_family_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"title": "skill_profile_feedback",
"description": "Default structure for Job Family Profile Feedback Data.",
"type": "object",
"required": [
"external_vendor",
"feedback_format",
"skills"
],
"properties": {
"external_vendor": {
"description": "Name of the (external) vendor in which the Job Family Profile feedback is provided. If the `feedback_format` is `external_skills`, the value should be an external vendor (`workday`), otherwise it should be `techwolf`.",
"type": "string"
},
"feedback_format": {
"type": "string",
"enum": [
"skills",
"external_vendor_skills"
]
},
"skills": {
"description": "The Skills contained in the Job Family Profile. The content should align with the `feedback_format`.",
"oneOf": [
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "Feedback Skill List",
"items": {
"title": "skills_feedback",
"description": "Default structure for Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
},
"example": [
{
"external_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Java",
"description": "Java programming language",
"has_skill": true
},
{
"external_id": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Python",
"description": "Python programming language",
"has_skill": false
}
]
},
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "External Vendor Feedback Skill List",
"items": {
"title": "external_vendor_skills_feedback",
"description": "Default structure for External Vendor Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"techwolf_skill",
"techwolf_skill_id",
"external_skill_name",
"external_skill_id",
"has_skill"
],
"properties": {
"techwolf_skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"techwolf_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"external_skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"external_skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
}
}
]
}
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"Job Family Profile Data"
],
"summary": "Update Job Family Profile Data",
"description": "Update Profile Data for a Job Family.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "Unique ID linked to a Job Family, consisting of alphanumeric characters, hyphens and underscores.\n\n**Note:** It may take some time for these changes to be reflected in the Job Family's final Skill Profile, since they are processed asynchronously.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_family_profile_data_external_id",
"required": true,
"description": "Unique ID linked to Job Family Profile Data, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Update structure of Job Family Profile Data.",
"type": "object",
"properties": {
"source": {
"description": "The source of the Job Family Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Family Profile Data. The content should align with the original `data_type` assigned to this Profile Data.",
"oneOf": [
{
"description": "Default structure for Job Family Description content.",
"type": "object",
"title": "job_family_description_content",
"required": [
"job_family_description"
],
"properties": {
"job_family_description": {
"type": "string",
"example": "Software engineers are responsible for designing, developing, and testing software. They are involved in the entire software development process, from the initial specification of requirements to the final release of the software.",
"minLength": 1,
"description": "Textual description of the Job Family."
}
}
},
{
"description": "Default structure for Job Family Description file content.",
"type": "object",
"title": "job_family_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"Job Family Profile Data"
],
"summary": "Delete Job Family Profile Data for a Job Family",
"description": "Remove Job Family Profile Data from the system. This step deletes all information linked exclusively to this Job Family Profile Data. It is not possible to delete Skill Profile Feedback via this endpoint, use the Job Family Profile Data Patch endpoint instead.\n\n**Note:** It may take some time for these changes to be reflected in the Job Family's final Skill Profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_family_external_id",
"required": true,
"description": "Unique ID linked to a Job Family, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_family_profile_data_external_id",
"required": true,
"description": "Unique ID linked to a Job Family Profile Data instance, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
"example": {
"code": "Bad Request",
"message": "You cannot delete a Skill Profile Feedback instance via this endpoint."
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/profile_data": {
"get": {
"tags": [
"Job Profile Data"
],
"summary": "List Job Profile Data",
"description": "Get a list of all Job Profile Data available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "The unique Job ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Job Profile Data objects stored inside the system.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Job Profile Data",
"description": "Subset of Job Profile Data starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Job Profile Data.",
"type": "object",
"required": [
"external_id",
"data_type",
"timestamp",
"source",
"data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"data_type": {
"description": "Type of the Job Profile Data.",
"type": "string",
"enum": [
"job_description",
"job_title",
"vacancy",
"skill_notes",
"skill_profile_feedback"
],
"example": "job_description"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Job Profile is considered to have the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source of the Job Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Profile Data. The content should align with the `data_type`.",
"oneOf": [
{
"description": "Default structure for Job Description content.",
"type": "object",
"title": "job_description_content",
"required": [
"job_description"
],
"properties": {
"job_description": {
"type": "string",
"example": "Backend developers have experience in writing code for the backend of a web application. They are responsible for the server-side logic of a web application.",
"minLength": 1,
"description": "Textual description of the Job."
}
}
},
{
"description": "Default structure for Job Description file content.",
"type": "object",
"title": "job_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Job Title content.",
"type": "object",
"title": "job_title_content",
"required": [
"job_title"
],
"properties": {
"job_title": {
"type": "string",
"example": "Django Backend developer.",
"minLength": 1,
"maxLength": 255,
"description": "Textual description of the Job Title."
}
}
},
{
"description": "Default structure for Vacancy content.",
"type": "object",
"title": "vacancy_content",
"required": [
"vacancy_id"
],
"properties": {
"vacancy_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique Vacancy ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Vacancy in your system from where data will be used."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"title": "skill_profile_feedback",
"description": "Default structure for Job Profile Feedback Data.",
"type": "object",
"required": [
"external_vendor",
"feedback_format",
"skills"
],
"properties": {
"external_vendor": {
"description": "Name of the (external) vendor in which the Job Family Profile feedback is provided. If the `feedback_format` is `external_skills`, the value should be an external vendor (`workday`), otherwise it should be `techwolf`.",
"type": "string"
},
"feedback_format": {
"type": "string",
"enum": [
"skills",
"external_vendor_skills"
]
},
"skills": {
"description": "The Skills contained in the Job Profile. The content should align with the `feedback_format`.",
"oneOf": [
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "Feedback Skill List",
"items": {
"title": "skills_feedback",
"description": "Default structure for Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
},
"example": [
{
"external_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Java",
"description": "Java programming language",
"has_skill": true
},
{
"external_id": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Python",
"description": "Python programming language",
"has_skill": false
}
]
},
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "External Vendor Feedback Skill List",
"items": {
"title": "external_vendor_skills_feedback",
"description": "Default structure for External Vendor Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"techwolf_skill",
"techwolf_skill_id",
"external_skill_name",
"external_skill_id",
"has_skill"
],
"properties": {
"techwolf_skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"techwolf_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"external_skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"external_skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
}
}
]
}
}
}
]
}
}
}
]
},
"example": [
{
"external_id": "5cb554be-5494-1233-8157-525f8a2f429a",
"data_type": "job_description",
"timestamp": "2018-11-07T00:25:00.073876",
"source": "Workday",
"data": {
"job_description": "Backend developers have experience in writing code for the backend of a web application. They are responsible for the server-side logic of a web application."
}
},
{
"external_id": "62d2c713-ab77-415e-b5fb-2f968ed9c1db",
"data_type": "job_title",
"timestamp": "2019-09-07T08:21:10.793021",
"source": "Company-archive",
"data": {
"job_title": "Django Backend developer."
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Job Profile Data"
],
"summary": "Create Job Profile Data for a Job",
"description": "Submit new Job Profile Data information to initialise the Job inside the Skill Engine API.\n\n**Note:** It may take some time for these changes to be reflected in the Job's final Skill Profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "The unique Job ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Job Profile Data.",
"type": "object",
"required": [
"external_id",
"data_type",
"source",
"data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"data_type": {
"description": "Type of the Job Profile Data.",
"type": "string",
"enum": [
"job_description",
"job_title",
"vacancy",
"skill_notes"
],
"example": "job_description"
},
"source": {
"description": "The source of the Job Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Profile Data. The content should align with the `data_type`.",
"oneOf": [
{
"description": "Default structure for Job Description content.",
"type": "object",
"title": "job_description_content",
"required": [
"job_description"
],
"properties": {
"job_description": {
"type": "string",
"example": "Backend developers have experience in writing code for the backend of a web application. They are responsible for the server-side logic of a web application.",
"minLength": 1,
"description": "Textual description of the Job."
}
}
},
{
"description": "Default structure for Job Description file content.",
"type": "object",
"title": "job_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Job Title content.",
"type": "object",
"title": "job_title_content",
"required": [
"job_title"
],
"properties": {
"job_title": {
"type": "string",
"example": "Django Backend developer.",
"minLength": 1,
"maxLength": 255,
"description": "Textual description of the Job Title."
}
}
},
{
"description": "Default structure for Vacancy content.",
"type": "object",
"title": "vacancy_content",
"required": [
"vacancy_id"
],
"properties": {
"vacancy_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique Vacancy ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Vacancy in your system from where data will be used."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of the created Job Profile Data.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}": {
"get": {
"tags": [
"Job Profile Data"
],
"summary": "Get Job Profile Data",
"description": "Get a single Job Profile Data item for a Job.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique ID linked to a Job, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_profile_data_external_id",
"required": true,
"description": "Unique ID linked to a Job Profile Data, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure for Job Profile Data.",
"type": "object",
"required": [
"external_id",
"data_type",
"timestamp",
"source",
"data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"data_type": {
"description": "Type of the Job Profile Data.",
"type": "string",
"enum": [
"job_description",
"job_title",
"vacancy",
"skill_notes",
"skill_profile_feedback"
],
"example": "job_description"
},
"timestamp": {
"description": "The completion date (in IS08601 format) of the Skill Event. From this point on, the Job Profile is considered to have the Skills of this Event.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"source": {
"description": "The source of the Job Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Profile Data. The content should align with the `data_type`.",
"oneOf": [
{
"description": "Default structure for Job Description content.",
"type": "object",
"title": "job_description_content",
"required": [
"job_description"
],
"properties": {
"job_description": {
"type": "string",
"example": "Backend developers have experience in writing code for the backend of a web application. They are responsible for the server-side logic of a web application.",
"minLength": 1,
"description": "Textual description of the Job."
}
}
},
{
"description": "Default structure for Job Description file content.",
"type": "object",
"title": "job_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Job Title content.",
"type": "object",
"title": "job_title_content",
"required": [
"job_title"
],
"properties": {
"job_title": {
"type": "string",
"example": "Django Backend developer.",
"minLength": 1,
"maxLength": 255,
"description": "Textual description of the Job Title."
}
}
},
{
"description": "Default structure for Vacancy content.",
"type": "object",
"title": "vacancy_content",
"required": [
"vacancy_id"
],
"properties": {
"vacancy_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique Vacancy ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Vacancy in your system from where data will be used."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
},
{
"title": "skill_profile_feedback",
"description": "Default structure for Job Profile Feedback Data.",
"type": "object",
"required": [
"external_vendor",
"feedback_format",
"skills"
],
"properties": {
"external_vendor": {
"description": "Name of the (external) vendor in which the Job Family Profile feedback is provided. If the `feedback_format` is `external_skills`, the value should be an external vendor (`workday`), otherwise it should be `techwolf`.",
"type": "string"
},
"feedback_format": {
"type": "string",
"enum": [
"skills",
"external_vendor_skills"
]
},
"skills": {
"description": "The Skills contained in the Job Profile. The content should align with the `feedback_format`.",
"oneOf": [
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "Feedback Skill List",
"items": {
"title": "skills_feedback",
"description": "Default structure for Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
},
"example": [
{
"external_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Java",
"description": "Java programming language",
"has_skill": true
},
{
"external_id": "9b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4b1e",
"name": "Python",
"description": "Python programming language",
"has_skill": false
}
]
},
{
"type": "array",
"description": "The Skills contained in the profile.",
"title": "External Vendor Feedback Skill List",
"items": {
"title": "external_vendor_skills_feedback",
"description": "Default structure for External Vendor Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"techwolf_skill",
"techwolf_skill_id",
"external_skill_name",
"external_skill_id",
"has_skill"
],
"properties": {
"techwolf_skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"techwolf_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"external_skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"external_skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
}
}
]
}
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"Job Profile Data"
],
"summary": "Update Job Profile Data",
"description": "Update Profile Data for a Job.\n\n**Note:** It may take some time for these changes to be reflected in the Job's final Skill Profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique ID linked to a Job, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_profile_data_external_id",
"required": true,
"description": "Unique ID linked to Profile Data, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "query",
"name": "language",
"required": true,
"schema": {
"type": "string",
"enum": [
"auto",
"nl",
"fr",
"en",
"de"
],
"example": "en"
},
"description": "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."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Update structure of Job Profile Data",
"type": "object",
"properties": {
"source": {
"description": "The source of the Job Profile Data.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Workday"
},
"data": {
"description": "The content of the Job Profile Data. The content should align with the original `data_type` assigned to this Profile Data.",
"oneOf": [
{
"description": "Default structure for Job Description content.",
"type": "object",
"title": "job_description_content",
"required": [
"job_description"
],
"properties": {
"job_description": {
"type": "string",
"example": "Backend developers have experience in writing code for the backend of a web application. They are responsible for the server-side logic of a web application.",
"minLength": 1,
"description": "Textual description of the Job."
}
}
},
{
"description": "Default structure for Job Description file content.",
"type": "object",
"title": "job_description_file_content",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
},
{
"description": "Default structure for Job Title content.",
"type": "object",
"title": "job_title_content",
"required": [
"job_title"
],
"properties": {
"job_title": {
"type": "string",
"example": "Django Backend developer.",
"minLength": 1,
"maxLength": 255,
"description": "Textual description of the Job Title."
}
}
},
{
"description": "Default structure for Vacancy content.",
"type": "object",
"title": "vacancy_content",
"required": [
"vacancy_id"
],
"properties": {
"vacancy_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique Vacancy ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Vacancy in your system from where data will be used."
}
}
},
{
"description": "Default structure for Skill notes content.",
"type": "object",
"title": "skill_notes",
"required": [
"description"
],
"properties": {
"description": {
"type": "string",
"minLength": 1,
"description": "A basic textual description of the event, containing Skills."
}
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"Job Profile Data"
],
"summary": "Delete Job Profile Data for a Job",
"description": "Remove Job Profile Data from the system. This step deletes all information linked exclusively to this Job Profile Data. It is not possible to delete Skill Profile Feedback via this endpoint, use the Job Profile Data Patch endpoint instead.\n\n**Note:** It may take some time for these changes to be reflected in the Job's final Skill Profile, since they are processed asynchronously.",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "path",
"name": "job_external_id",
"required": true,
"description": "Unique ID linked to a Job, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"in": "path",
"name": "job_profile_data_external_id",
"required": true,
"description": "Unique ID linked to a Job Profile Data instance, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
},
"example": {
"code": "Bad Request",
"message": "You cannot delete a Skill Profile Feedback instance via this endpoint."
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/issues": {
"get": {
"tags": [
"JobIssues"
],
"summary": "List Job Issues",
"description": "Get a list of the data issues identified for each Job.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"name": "job_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "This parameter can be added multiple times to include more Jobs."
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of identified Job data issues.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Job issues",
"description": "Subset of Job issues starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Job Issue.",
"type": "object",
"required": [
"issue_type",
"data",
"explanation"
],
"properties": {
"issue_type": {
"description": "Type of the Job Issue.",
"type": "string",
"enum": [
"missing_or_short_job_description"
],
"example": "missing_or_short_job_description"
},
"data": {
"description": "The clarifying data of the Job Issue. The data should align with the `issue_type`.",
"oneOf": [
{
"description": "Default structure for \"missing or short Job Description\" issue data.",
"type": "object",
"title": "missing_or_short_job_description_data",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
},
{
"type": "object"
},
{
"required": [
"issue_type",
"data",
"explanation"
]
}
]
},
"example": [
{
"issue_type": "missing_or_short_job_description",
"data": {
"job_id": "5cbdbdbe-5f44-4423-8157-5fgqsef7b834c"
},
"explanation": "Job description is missing or too short."
},
{
"issue_type": "missing_or_short_job_description",
"data": {
"job_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db"
},
"explanation": "Job description is missing or too short."
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/issues/summary": {
"get": {
"tags": [
"JobIssues"
],
"summary": "Job Issue Summary",
"description": "Get a list of Job issue types with the number of issues per type.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"summary"
],
"properties": {
"summary": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue_type",
"count"
],
"properties": {
"issue_type": {
"description": "Type of the Job Issue.",
"type": "string",
"enum": [
"missing_or_short_job_description"
],
"example": "missing_or_short_job_description"
},
"count": {
"description": "The number of issues of the given `issue_type`.",
"type": "integer",
"minimum": 0,
"example": 2
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/changes": {
"get": {
"tags": [
"JobChanges"
],
"summary": "List Job Architecture Changes",
"description": "Get a list of Job architecture changes with optional filtering by Job IDs.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"name": "job_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "Filter the changes by Job External IDs. This parameter can be added multiple times to include more Jobs."
}
},
{
"name": "include",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"context"
]
}
},
"description": "Additional data to include in the response. Use 'context' to include context information for each change.",
"example": [
"context"
]
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Job architecture changes.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Job changes",
"description": "Subset of Job changes starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"type": "object",
"required": [
"external_id",
"change_type",
"change_status",
"change_data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"change_type": {
"description": "Type of change made to a Job.",
"type": "string",
"enum": [
"add_job_description"
],
"example": "add_job_description"
},
"change_status": {
"description": "Current status of a Job change.",
"type": "string",
"enum": [
"preview",
"generating",
"generating_preview",
"suggested",
"saving",
"saved",
"deleted",
"generate_failed",
"save_failed"
],
"example": "suggested"
},
"change_data": {
"type": "object",
"description": "The actual change data",
"oneOf": [
{
"type": "object",
"required": [
"job_id",
"job_description"
],
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_description": {
"type": "string",
"description": "The new Job description"
},
"job_description_id": {
"description": "The profile data ID of the Job description. This field is only present for changes with status `saved`.",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
],
"example": {
"job_id": "job_external_id_1",
"job_description": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications..."
}
},
"context": {
"description": "Context information for the change (included when include=context parameter is used)",
"type": "object",
"properties": {
"instructions": {
"type": "string",
"nullable": true,
"description": "Extra instructions when generating the Job description",
"example": "Please use inclusive language and highlight remote work opportunities"
},
"reference_job_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "Array of reference Job UUIDs to use for generating the Job description",
"example": [
"5cbdbdbe-5f44-4423-8157-5fgqsef7b834c",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
},
"sections_to_include": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of sections to include in the Job description",
"example": [
"Summary",
"Responsibilities"
]
},
"use_internal_job_data": {
"type": "boolean",
"description": "Whether to use internal Job data for the Job description",
"example": true
}
}
}
}
},
"example": [
{
"external_id": "6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"change_type": "add_job_description",
"change_status": "suggested",
"change_data": {
"job_id": "72d2c013-ab77-410e-b5fb-2f96eed9c1db",
"job_description": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications..."
},
"context": {
"instructions": "Please update the Job description to be more inclusive and highlight remote work opportunities",
"reference_job_ids": [
"5cbdbdbe-5f44-4423-8157-5fgqsef7b834c"
],
"sections_to_include": [
"Summary",
"Responsibilities",
"Qualifications"
],
"use_internal_job_data": true
}
},
{
"external_id": "22d2c013-ab77-410e-b5fb-2f96eed9c1db",
"change_type": "add_job_description",
"change_status": "saved",
"change_data": {
"job_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"job_description": "The Customer Service Representative is responsible for providing exceptional support to customers by addressing inquiries, resolving complaints, and ensuring overall customer satisfaction...",
"job_description_id": "123e4567-e89b-12d3-a456-426614174000"
},
"context": {
"instructions": null,
"reference_job_ids": [
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
],
"sections_to_include": [
"Summary",
"Responsibilities"
],
"use_internal_job_data": false
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"JobChanges"
],
"summary": "Bulk generate Job changes",
"description": "Start a batch generation of Job changes for specified Jobs.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"change_type",
"context",
"job_ids"
],
"properties": {
"change_type": {
"description": "Type of change made to a Job.",
"type": "string",
"enum": [
"add_job_description"
],
"example": "add_job_description"
},
"context": {
"type": "object",
"description": "Additional context information for Job changes",
"properties": {
"instructions": {
"type": "string",
"nullable": true,
"description": "Extra instructions when generating the Job description",
"example": "Please use inclusive language and highlight remote work opportunities"
},
"reference_job_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "Array of reference Job UUIDs to use for generating the Job description",
"example": [
"5cbdbdbe-5f44-4423-8157-5fgqsef7b834c",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
},
"sections_to_include": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of sections to include in the Job description",
"example": [
"Summary",
"Responsibilities"
]
},
"use_internal_job_data": {
"type": "boolean",
"description": "Whether to use internal Job data for the Job description",
"example": true
}
}
},
"job_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "List of Job external IDs to create changes for"
}
}
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"batch_id"
],
"properties": {
"batch_id": {
"type": "string",
"description": "Unique identifier for the batch of created Job changes",
"example": "01JZ54E33R9F4154Z8WCTYVSHT"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobChanges"
],
"summary": "Bulk Update Job Architecture Changes",
"description": "Update multiple Job architecture changes at once by providing a list of change IDs and the new status.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"change_status",
"change_ids"
],
"properties": {
"change_status": {
"type": "string",
"description": "The new status to apply to all specified changes",
"enum": [
"saved",
"deleted"
],
"example": "saved"
},
"change_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of change external IDs to update. Each change to update needs to be in the \"suggested\" state.",
"example": [
"6129e3f1-663f-44ea-aa3f-2ce1077b834c",
"22d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
}
}
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/changes/preview": {
"post": {
"tags": [
"JobChanges"
],
"summary": "Generate preview Job change",
"description": "Generate a preview Job change for a specific Job.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"change_type",
"context",
"job_id"
],
"properties": {
"change_type": {
"description": "Type of change made to a Job.",
"type": "string",
"enum": [
"add_job_description"
],
"example": "add_job_description"
},
"context": {
"type": "object",
"description": "Additional context information for Job changes",
"properties": {
"instructions": {
"type": "string",
"nullable": true,
"description": "Extra instructions when generating the Job description",
"example": "Please use inclusive language and highlight remote work opportunities"
},
"reference_job_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "Array of reference Job UUIDs to use for generating the Job description",
"example": [
"5cbdbdbe-5f44-4423-8157-5fgqsef7b834c",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
},
"sections_to_include": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of sections to include in the Job description",
"example": [
"Summary",
"Responsibilities"
]
},
"use_internal_job_data": {
"type": "boolean",
"description": "Whether to use internal Job data for the Job description",
"example": true
}
}
},
"job_id": {
"description": "Job external ID to preview change for",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"change_id"
],
"properties": {
"change_id": {
"type": "string",
"description": "Unique identifier for the previewed Job change",
"example": "01JZ54K5YVCXWCT2J3B7EJCSZD"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/changes/summary": {
"get": {
"tags": [
"JobChanges"
],
"summary": "Get Job Architecture Changes Summary",
"description": "Get a summary overview of Job architecture changes, including counts and statistics.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"summary": {
"type": "array",
"items": {
"type": "object",
"properties": {
"change_type": {
"description": "Type of change made to a Job.",
"type": "string",
"enum": [
"add_job_description"
],
"example": "add_job_description"
},
"count": {
"type": "integer",
"description": "Total number of changes",
"minimum": 0,
"example": 90
},
"count_per_status": {
"type": "object",
"properties": {
"preview": {
"type": "integer",
"description": "Number of preview changes",
"minimum": 0,
"example": 10
},
"generating": {
"type": "integer",
"description": "Number of generating changes",
"minimum": 0,
"example": 10
},
"generating_preview": {
"type": "integer",
"description": "Number of generating preview changes",
"minimum": 0,
"example": 10
},
"suggested": {
"type": "integer",
"description": "Number of suggested changes",
"minimum": 0,
"example": 10
},
"saving": {
"type": "integer",
"description": "Number of saving changes",
"minimum": 0,
"example": 10
},
"saved": {
"type": "integer",
"description": "Number of saved changes",
"minimum": 0,
"example": 10
},
"deleted": {
"type": "integer",
"description": "Number of deleted changes",
"minimum": 0,
"example": 10
},
"generate_failed": {
"type": "integer",
"description": "Number of generate failed changes",
"minimum": 0,
"example": 10
},
"save_failed": {
"type": "integer",
"description": "Number of save failed changes",
"minimum": 0,
"example": 10
}
}
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/changes/{change_id}": {
"get": {
"tags": [
"JobChanges"
],
"summary": "Get Job Architecture Change Details",
"description": "Get detailed information about a specific Job architecture change.",
"parameters": [
{
"name": "change_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
},
{
"name": "include",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"context"
]
}
},
"description": "Additional data to include in the response. Use 'context' to include context information for the change.",
"example": [
"context"
]
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"external_id",
"change_type",
"change_status",
"change_data"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"change_type": {
"description": "Type of change made to a Job.",
"type": "string",
"enum": [
"add_job_description"
],
"example": "add_job_description"
},
"change_status": {
"description": "Current status of a Job change.",
"type": "string",
"enum": [
"preview",
"generating",
"generating_preview",
"suggested",
"saving",
"saved",
"deleted",
"generate_failed",
"save_failed"
],
"example": "suggested"
},
"change_data": {
"type": "object",
"description": "The actual change data",
"oneOf": [
{
"type": "object",
"required": [
"job_id",
"job_description"
],
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"job_description": {
"type": "string",
"description": "The new Job description"
},
"job_description_id": {
"description": "The profile data ID of the Job description. This field is only present for changes with status `saved`.",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
],
"example": {
"job_id": "job_external_id_1",
"job_description": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications..."
}
},
"context": {
"description": "Context information for the change (included when include=context parameter is used)",
"type": "object",
"properties": {
"instructions": {
"type": "string",
"nullable": true,
"description": "Extra instructions when generating the Job description",
"example": "Please use inclusive language and highlight remote work opportunities"
},
"reference_job_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"description": "Array of reference Job UUIDs to use for generating the Job description",
"example": [
"5cbdbdbe-5f44-4423-8157-5fgqsef7b834c",
"62d2c013-ab77-410e-b5fb-2f96eed9c1db"
]
},
"sections_to_include": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of sections to include in the Job description",
"example": [
"Summary",
"Responsibilities"
]
},
"use_internal_job_data": {
"type": "boolean",
"description": "Whether to use internal Job data for the Job description",
"example": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"JobChanges"
],
"summary": "Update Job Architecture Change",
"description": "Update a specific Job architecture change with new data.",
"parameters": [
{
"name": "change_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"change_data": {
"type": "object",
"description": "Updated change data",
"oneOf": [
{
"type": "object",
"properties": {
"job_description": {
"type": "string",
"description": "The new Job description"
}
}
}
],
"example": {
"job_description": "The Front-End Developer is responsible for implementing visual elements that users interact with on the company's web applications..."
}
}
}
}
}
}
},
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/suggestions/interactions": {
"post": {
"tags": [
"JobSuggestions"
],
"summary": "Bulk Accept or Reject Job Architecture Suggestions",
"description": "Accept or reject multiple suggestions in a single request.\n\nUse the `category` query parameter to choose between skill suggestions (default) and task suggestions.\n\n**Skill suggestions** (`category=skills`):\n\nWhen a skill suggestion is accepted, the corresponding change is applied to the job's governed skill profile:\n- `add_job_skill`: Adds the skill to the job's skill profile with `validation_state: validated`\n- `remove_job_skill`: Marks the skill as rejected on the job's skill profile\n- `set_job_skill_proficiency`: Updates the skill's proficiency level\n- `set_job_skill_criticality`: Updates the skill's critical flag\n\n**Task suggestions** (`category=tasks`):\n\nWhen a task suggestion is accepted, the task is added to the job's task profile:\n- `add_job_task`: Adds the task to the job's task profile\n\nThe `data.weekly_hours` field is required for all task suggestion interactions.\n\n**Side Effects (skill suggestions only):**\n- Accepting a `set_job_skill_proficiency` or `set_job_skill_criticality` suggestion will automatically\n accept the corresponding `add_job_skill` suggestion for the same skill if it exists.\n\n**Overriding Values (skill suggestions only):**\n- When accepting a `set_job_skill_proficiency` suggestion, you can optionally provide a different\n `proficiency_level` in the `data` field to override the suggested value.\n- When accepting a `set_job_skill_criticality` suggestion, you can optionally provide a different\n `critical` value in the `data` field to override the suggested value.\n",
"security": [
{
"application": [
"write"
]
}
],
"parameters": [
{
"in": "query",
"name": "category",
"required": false,
"description": "The type of suggestions to export or interact with. If not specified, the default category (`skills`) will be used.",
"schema": {
"type": "string",
"default": "skills",
"enum": [
"skills",
"tasks"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Skills",
"type": "object",
"description": "Request body for bulk accepting or rejecting job architecture suggestions.",
"required": [
"interactions"
],
"properties": {
"interactions": {
"type": "array",
"description": "List of suggestion interactions to process.",
"minItems": 1,
"items": {
"type": "object",
"description": "A single suggestion interaction item for accepting or rejecting a suggestion.",
"required": [
"suggestion_id",
"state"
],
"properties": {
"suggestion_id": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the suggestion to interact with.",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"state": {
"description": "State to set when interacting with a suggestion.",
"type": "string",
"enum": [
"accepted",
"rejected"
],
"example": "accepted"
},
"data": {
"type": "object",
"description": "Optional data to override suggestion values when accepting.\n- `proficiency_level`: Override the proficiency level (1-5)\n- `critical`: Override the critical flag (boolean)\n",
"properties": {
"proficiency_level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Override the proficiency level when accepting a proficiency suggestion.",
"example": 3
},
"critical": {
"type": "boolean",
"description": "Override the critical flag when accepting a criticality suggestion.",
"example": true
}
}
}
}
},
"example": [
{
"suggestion_id": "550e8400-e29b-41d4-a716-446655440000",
"state": "accepted"
},
{
"suggestion_id": "660e8400-e29b-41d4-a716-446655440001",
"state": "rejected"
},
{
"suggestion_id": "770e8400-e29b-41d4-a716-446655440002",
"state": "accepted",
"data": {
"proficiency_level": 3
}
}
]
}
}
},
{
"title": "Tasks",
"type": "object",
"description": "Request body for bulk accepting or rejecting task suggestions.",
"required": [
"interactions"
],
"properties": {
"interactions": {
"type": "array",
"description": "List of task suggestion interactions to process.",
"minItems": 1,
"items": {
"type": "object",
"description": "A single task suggestion interaction item for accepting or rejecting a task suggestion.",
"required": [
"suggestion_id",
"state",
"data"
],
"properties": {
"suggestion_id": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the task suggestion to interact with.",
"example": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c"
},
"state": {
"description": "State to set when interacting with a suggestion.",
"type": "string",
"enum": [
"accepted",
"rejected"
],
"example": "accepted"
},
"data": {
"type": "object",
"description": "Required data for the task suggestion interaction.",
"required": [
"weekly_hours"
],
"properties": {
"weekly_hours": {
"type": "integer",
"description": "The number of weekly hours for this task.",
"example": 4
}
}
}
}
},
"example": [
{
"suggestion_id": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c",
"state": "accepted",
"data": {
"weekly_hours": 4
}
},
{
"suggestion_id": "02977d8b-4c5e-8f9a-0b2d-3e6f7a8b9c0d",
"state": "rejected",
"data": {
"weekly_hours": 2
}
}
]
}
}
}
]
},
"examples": {
"basicAcceptReject": {
"summary": "Basic accept and reject (skills)",
"value": {
"interactions": [
{
"suggestion_id": "550e8400-e29b-41d4-a716-446655440000",
"state": "accepted"
},
{
"suggestion_id": "660e8400-e29b-41d4-a716-446655440001",
"state": "rejected"
}
]
}
},
"withOverride": {
"summary": "Accept with proficiency override (skills)",
"value": {
"interactions": [
{
"suggestion_id": "770e8400-e29b-41d4-a716-446655440002",
"state": "accepted",
"data": {
"proficiency_level": 4
}
}
]
}
},
"taskInteraction": {
"summary": "Accept and reject task suggestions",
"value": {
"interactions": [
{
"suggestion_id": "01966c7a-3b4d-7e8f-9a1c-2d5e6f7a8b9c",
"state": "accepted",
"data": {
"weekly_hours": 4
}
},
{
"suggestion_id": "02977d8b-4c5e-8f9a-0b2d-3e6f7a8b9c0d",
"state": "rejected",
"data": {
"weekly_hours": 2
}
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content - All interactions were processed successfully."
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/jobs/metrics/adoption_metrics": {
"post": {
"tags": [
"JobMetrics"
],
"summary": "Get Job adoption metrics",
"description": "Get adoption metrics across a collection of Job objects stored in the system, aggregated over their Skills and your Taxonomy.",
"security": [
{
"application": [
"read"
]
}
],
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to use for the returned metrics. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "List of adoption metric queries. Each query corresponds with adoption metrics aggregated across the requested collection of objects.",
"required": [
"queries"
],
"properties": {
"queries": {
"type": "array",
"items": {
"type": "object",
"required": [
"query_id",
"filters"
],
"properties": {
"query_id": {
"type": "string",
"description": "A unique ID linked to the adoption metric query.",
"example": "query-id"
},
"filters": {
"type": "array",
"description": "Filters to be applied on the entities for which adoption metrics need to be aggregated. If left empty, the adoption metrics are aggregated across all entities stored in the system.",
"items": {
"anyOf": [
{
"allOf": [
{
"type": "object",
"required": [
"filter",
"attribute_name",
"operator",
"attribute_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter on all entities for which attribute `attribute_name` is equal to `attribute_value`. Possible values for `attribute_name` are stated below.",
"enum": [
"attribute"
],
"example": "attribute"
},
"attribute_name": {
"type": "string",
"description": "Name of the attribute on which the filter is applied."
},
"operator": {
"type": "string",
"description": "The type of operator to apply on the attribute `attribute_name`.",
"enum": [
"eq"
]
},
"attribute_value": {
"type": "string",
"description": "Value of the attribute `attribute_name`",
"example": "abc-123"
}
}
},
{
"type": "object",
"title": "attribute_equal",
"properties": {
"attribute_name": {
"enum": [
"job_family",
"job_family_group"
]
}
}
}
]
},
{
"allOf": [
{
"type": "object",
"required": [
"filter",
"attribute_name",
"operator"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter on all entities for which attribute `attribute_name` is empty. Possible values for `attribute_name` are stated below.",
"enum": [
"attribute"
],
"example": "attribute"
},
"attribute_name": {
"type": "string",
"description": "Name of the attribute on which the filter is applied."
},
"operator": {
"type": "string",
"description": "The type of operator to apply on the attribute `attribute_name`.",
"enum": [
"is_empty"
]
}
}
},
{
"type": "object",
"title": "attribute_is_empty",
"properties": {
"attribute_name": {
"enum": [
"job_family",
"job_family_group"
]
}
}
}
]
}
]
},
"minItems": 0,
"maxItems": 1
}
}
}
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Response structure for Job Architecture Metrics. Metrics are expressed in the structure of your Taxonomy. When a Skill is not represented in the Taxonomy, it will be included in the \"Skills outside of the Taxonomy\" Domain.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"results"
],
"properties": {
"results": {
"title": "Job Architecture Results",
"description": "A list of metrics related to the requested collection of Jobs.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "job_architecture_metrics",
"required": [
"query_id",
"metrics"
],
"properties": {
"query_id": {
"type": "string",
"description": "The unique ID of the query."
},
"metrics": {
"title": "Metrics",
"description": "Aggregated statistics for the requested collection of Jobs, broken down by Domains, Skill Clusters, and Skills.",
"type": "object",
"required": [
"domains",
"sum_job_skill_count",
"unique_job_count",
"unique_skill_count",
"skills_outside_taxonomy",
"total_job_skill_count"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains within the requested collection of Jobs.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"domain_name",
"external_id",
"skill_clusters",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The external ID of the Domain."
},
"skill_clusters": {
"title": "Skill Clusters",
"description": "A list of Skill Clusters within the Domain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"skills",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"external_id": {
"type": "string",
"description": "The external ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"skills": {
"title": "Skills",
"description": "A list of Skills within the Skill Cluster.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_job_count"
],
"properties": {
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs possessing this Skill."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
}
]
}
},
"skills_outside_taxonomy": {
"description": "A list of Skills not present in the Taxonomy.",
"required": [
"skills",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"skills": {
"title": "Skills",
"description": "A list of skills that are not present in the Taxonomy.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_job_count"
],
"properties": {
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs possessing this Skill."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
},
"total_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one. Skills that occur in multiple Skill Clusters are only counted once."
}
}
}
}
}
]
}
}
},
"example": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_job_count": 1
}
],
"sum_job_skill_count": 1,
"unique_skill_count": 1,
"unique_job_count": 1
}
],
"sum_job_skill_count": 1,
"unique_skill_count": 1,
"unique_job_count": 1
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-2",
"skill_name": "Software Debugging",
"unique_job_count": 15
}
],
"sum_job_skill_count": 15,
"unique_skill_count": 1,
"unique_job_count": 15
},
"sum_job_skill_count": 16,
"unique_skill_count": 2,
"unique_job_count": 16,
"total_job_skill_count": 16
}
}
]
}
},
{
"description": "Response structure for Job Architecture Metrics. Metrics are expressed in the structure of your Taxonomy. When a Skill is not represented in the Taxonomy, it will be included in the \"Skills outside of the Taxonomy\" Domain.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"results"
],
"properties": {
"results": {
"title": "Job Architecture Results",
"description": "A list of metrics related to the requested collection of Jobs.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "job_architecture_metrics",
"required": [
"query_id",
"metrics"
],
"properties": {
"query_id": {
"type": "string",
"description": "The unique ID of the query."
},
"metrics": {
"title": "Metrics",
"description": "Aggregated statistics for the requested collection of Jobs, broken down by Domains, Subdomains, Skill Clusters, and Skills.",
"type": "object",
"required": [
"domains",
"sum_job_skill_count",
"unique_job_count",
"unique_skill_count",
"skills_outside_taxonomy",
"total_job_skill_count"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains within the requested collection of Jobs.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"domain_name",
"external_id",
"subdomains",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain."
},
"external_id": {
"type": "string",
"description": "The external ID of the Domain."
},
"subdomains": {
"title": "Subdomains",
"description": "A list of Subdomains within the Domain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "subdomain_content",
"required": [
"subdomain_name",
"external_id",
"skill_clusters",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"subdomain_name": {
"type": "string",
"description": "The name of the Subdomain."
},
"external_id": {
"type": "string",
"description": "The external ID of the Subdomain."
},
"skill_clusters": {
"title": "Skill Clusters",
"description": "A list of Skill Clusters within the Subdomain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"skills",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"external_id": {
"type": "string",
"description": "The external ID of the Skill Cluster."
},
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster."
},
"skills": {
"title": "Skills",
"description": "A list of Skills within the Skill Cluster.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_job_count"
],
"properties": {
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs possessing this Skill."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
}
]
}
},
"skills_outside_taxonomy": {
"description": "A list of Skills not present in the Taxonomy.",
"required": [
"skills",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count"
],
"properties": {
"skills": {
"title": "Skills",
"description": "A list of skills that are not present in the Taxonomy.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_job_count"
],
"properties": {
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs possessing this Skill."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one."
},
"unique_skill_count": {
"type": "integer",
"description": "The total number of unique Skills of all Jobs within this Taxonomy level."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
},
"total_job_skill_count": {
"type": "integer",
"description": "Total number of times Jobs possess Skills within this Taxonomy level, counting each Skill even if a Job has more than one. Skills that occur in multiple Skill Clusters are only counted once."
}
}
}
}
}
]
}
}
},
"example": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"subdomains": [
{
"subdomain_name": "Software Development",
"external_id": "subdomain-001",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_job_count": 15
}
],
"sum_job_skill_count": 15,
"unique_skill_count": 1,
"unique_job_count": 15
}
],
"sum_job_skill_count": 15,
"unique_skill_count": 1,
"unique_job_count": 15
},
{
"subdomain_name": "Data Management",
"external_id": "subdomain-002",
"skill_clusters": [
{
"external_id": "xyz-cluster",
"skill_cluster_name": "Data Engineering",
"skills": [
{
"skill_id": "xyz-skill-2",
"skill_name": "ETL Development",
"unique_job_count": 20
}
],
"sum_job_skill_count": 20,
"unique_skill_count": 1,
"unique_job_count": 20
}
],
"sum_job_skill_count": 20,
"unique_skill_count": 1,
"unique_job_count": 20
}
],
"sum_job_skill_count": 35,
"unique_skill_count": 2,
"unique_job_count": 35
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-3",
"skill_name": "Software Debugging",
"unique_job_count": 5
}
],
"sum_job_skill_count": 5,
"unique_skill_count": 1,
"unique_job_count": 5
},
"sum_job_skill_count": 40,
"unique_skill_count": 3,
"unique_job_count": 35,
"total_job_skill_count": 40
}
}
]
}
},
{
"description": "Response structure for Job Architecture Metrics when no Taxonomy is present. Metrics are grouped by Domains based on TechWolf Domain names, and Skills are directly nested under these Domains.",
"type": "object",
"title": "No Taxonomy",
"required": [
"results"
],
"properties": {
"results": {
"title": "Job Architecture Results",
"description": "A list of metrics related to the requested collection of Jobs, grouped by Domains based on TechWolf classifications.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "job_architecture_metrics",
"required": [
"query_id",
"metrics"
],
"properties": {
"query_id": {
"type": "string",
"description": "The unique ID of the query."
},
"metrics": {
"title": "Metrics",
"description": "Aggregated statistics for the requested collection of Jobs, grouped by TechWolf Domains, with Skills directly underneath each Domain.",
"type": "object",
"required": [
"domains",
"sum_job_skill_count",
"unique_skill_count",
"unique_job_count",
"total_job_skill_count"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains, using TechWolf classifications, within the requested collection of Jobs.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"domain_name",
"skills",
"unique_skill_count",
"sum_job_skill_count",
"unique_job_count"
],
"properties": {
"domain_name": {
"type": "string",
"description": "The name of the Domain, based on TechWolf classification."
},
"skills": {
"title": "Skills",
"description": "A list of Skills directly under the Domain.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"type": "object",
"required": [
"skill_id",
"skill_name",
"unique_job_count",
"unique_job_count"
],
"properties": {
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs possessing this Skill."
}
}
}
]
}
},
"unique_skill_count": {
"type": "integer",
"description": "The count of unique Skills in the Domain."
},
"sum_job_skill_count": {
"type": "integer",
"description": "The total Employee skill count in the Domain."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
}
}
}
]
}
},
"sum_job_skill_count": {
"type": "integer",
"description": "Total Employee skill count across all Domains."
},
"unique_skill_count": {
"type": "integer",
"description": "Total count of unique Skills across all Domains."
},
"unique_job_count": {
"type": "integer",
"description": "Number of distinct Jobs with at least one Skill in this Taxonomy level."
},
"total_job_skill_count": {
"type": "integer",
"description": "Total Job Skill count across all Domains. Skills that occur in multiple Skill Clusters are only counted once."
}
}
}
}
}
]
}
}
},
"example": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "TechWolf Domain",
"skills": [
{
"skill_id": "skill_1",
"skill_name": "Skill 1",
"unique_job_count": 1
},
{
"skill_id": "skill_3",
"skill_name": "Skill 3",
"unique_job_count": 10
}
],
"unique_skill_count": 2,
"sum_job_skill_count": 11,
"unique_job_count": 11
},
{
"domain_name": "TechWolf Domain 2",
"skills": [
{
"skill_id": "skill_4",
"skill_name": "Skill 4",
"unique_job_count": 50
}
],
"unique_skill_count": 1,
"sum_job_skill_count": 50,
"unique_job_count": 50
}
],
"sum_job_skill_count": 61,
"unique_skill_count": 3,
"unique_job_count": 61,
"total_job_skill_count": 61
}
}
]
}
}
]
},
"examples": {
"3levelTaxonomyExample": {
"summary": "3 Level Taxonomy",
"value": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_job_count": 1
}
],
"sum_job_skill_count": 1,
"unique_skill_count": 1,
"unique_job_count": 1
}
],
"sum_job_skill_count": 1,
"unique_skill_count": 1,
"unique_job_count": 1
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-2",
"skill_name": "Software Debugging",
"unique_job_count": 15
}
],
"sum_job_skill_count": 15,
"unique_skill_count": 1,
"unique_job_count": 15
},
"sum_job_skill_count": 16,
"unique_skill_count": 2,
"unique_job_count": 16,
"total_job_skill_count": 16
}
}
]
}
},
"4levelTaxonomyExample": {
"summary": "4 Level Taxonomy",
"value": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "IT",
"external_id": "abdcde-domain",
"subdomains": [
{
"subdomain_name": "Software Development",
"external_id": "subdomain-001",
"skill_clusters": [
{
"external_id": "abdcde-cluster",
"skill_cluster_name": "Software Engineering",
"skills": [
{
"skill_id": "abcde-skill-1",
"skill_name": "Automated Testing",
"unique_job_count": 15
}
],
"sum_job_skill_count": 15,
"unique_skill_count": 1,
"unique_job_count": 15
}
],
"sum_job_skill_count": 15,
"unique_skill_count": 1,
"unique_job_count": 15
},
{
"subdomain_name": "Data Management",
"external_id": "subdomain-002",
"skill_clusters": [
{
"external_id": "xyz-cluster",
"skill_cluster_name": "Data Engineering",
"skills": [
{
"skill_id": "xyz-skill-2",
"skill_name": "ETL Development",
"unique_job_count": 20
}
],
"sum_job_skill_count": 20,
"unique_skill_count": 1,
"unique_job_count": 20
}
],
"sum_job_skill_count": 20,
"unique_skill_count": 1,
"unique_job_count": 20
}
],
"sum_job_skill_count": 35,
"unique_skill_count": 2,
"unique_job_count": 35
}
],
"skills_outside_taxonomy": {
"skills": [
{
"skill_id": "abcde-skill-3",
"skill_name": "Software Debugging",
"unique_job_count": 5
}
],
"sum_job_skill_count": 5,
"unique_skill_count": 1,
"unique_job_count": 5
},
"sum_job_skill_count": 40,
"unique_skill_count": 3,
"unique_job_count": 35,
"total_job_skill_count": 40
}
}
]
}
},
"noTaxonomyExample": {
"summary": "No Taxonomy",
"value": {
"results": [
{
"query_id": "query-123-abc",
"metrics": {
"domains": [
{
"domain_name": "TechWolf Domain",
"skills": [
{
"skill_id": "skill_1",
"skill_name": "Skill 1",
"unique_job_count": 1
},
{
"skill_id": "skill_3",
"skill_name": "Skill 3",
"unique_job_count": 10
}
],
"unique_skill_count": 2,
"sum_job_skill_count": 11,
"unique_job_count": 11
},
{
"domain_name": "TechWolf Domain 2",
"skills": [
{
"skill_id": "skill_4",
"skill_name": "Skill 4",
"unique_job_count": 50
}
],
"unique_skill_count": 1,
"sum_job_skill_count": 50,
"unique_job_count": 50
}
],
"sum_job_skill_count": 61,
"unique_skill_count": 3,
"unique_job_count": 61,
"total_job_skill_count": 61
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/peer_groups": {
"get": {
"tags": [
"PeerGroups"
],
"summary": "List Peer Groups",
"description": "Get a list of all the actived peer groups and the companies within them.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of peer groups activated for this tenant.",
"type": "integer",
"minimum": 0,
"example": 3
},
"results": {
"title": "Peer groups",
"description": "The list of peer groups activated for this tenant.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for a peer group.",
"type": "object",
"title": "peer_group_content",
"required": [
"name",
"companies"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the peer group."
},
"companies": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of the company names that are in this peer group."
}
}
},
{
"type": "object"
},
{
"required": [
"name",
"companies"
]
}
]
},
"example": [
{
"name": "B2B",
"companies": [
"TechWolf",
"Umbrella Corporation",
"Cyberdyne Systems"
]
},
{
"name": "B2C",
"companies": [
"Royal Charter Energy"
]
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/domains": {
"get": {
"tags": [
"TaxonomyDomains"
],
"summary": "List Domains",
"description": "Get a list of all Domains available in the system.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Domain entities stored in the system.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Domains",
"description": "Subset of Domains starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Domain.",
"type": "object",
"title": "domain_content",
"required": [
"external_id",
"domain_name",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"domain_name": "IT & Engineering",
"last_updated": "2023-05-22T13:22:39.179747"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"domain_name": "Human Resources",
"last_updated": "2023-05-22T13:22:41.165448"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"TaxonomyDomains"
],
"summary": "Create Domain",
"description": "Create a new Domain in the system.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for Domain.",
"type": "object",
"title": "domain_content",
"required": [
"external_id",
"domain_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/domains/{domain_external_id}": {
"get": {
"tags": [
"TaxonomyDomains"
],
"summary": "Get Domain",
"description": "Get Domain information stored in the system.",
"parameters": [
{
"in": "path",
"name": "domain_external_id",
"required": true,
"description": "The unique Domain ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "custom_properties",
"description": "Additional Domain attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
}
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure for Domain.",
"type": "object",
"title": "domain_content",
"required": [
"external_id",
"domain_name",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"example": "IT & Engineering",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"TaxonomyDomains"
],
"summary": "Update Domain",
"description": "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.",
"parameters": [
{
"in": "path",
"name": "domain_external_id",
"required": true,
"description": "The unique Domain ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating a Domain.",
"type": "object",
"properties": {
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "IT - HR",
"description": "Name of the Domain."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"TaxonomyDomains"
],
"summary": "Delete Domain",
"description": "Delete Domain information stored inside the system. By deleting a Domain, all Skill Clusters linked to this Domain are also deleted.",
"parameters": [
{
"in": "path",
"name": "domain_external_id",
"required": true,
"description": "The unique Domain ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/subdomains": {
"get": {
"tags": [
"TaxonomySubdomains"
],
"summary": "List Subdomains",
"description": "Get a list of all Subdomains available in the system.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
},
"example": [
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Subdomain Entities stored in the system.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Subdomains",
"description": "Subset of Subdomains starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Subdomain.",
"type": "object",
"title": "subdomain_content",
"required": [
"external_id",
"subdomain_name",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
},
"example": [
{
"external_id": "bc3a5bc9-5f44-4423-8157-520f8a2f429a",
"subdomain_name": "Research",
"last_updated": "2023-05-22T13:22:39.179747"
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"subdomain_name": "Customer Work",
"last_updated": "2023-05-22T13:22:41.165448"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"TaxonomySubdomains"
],
"summary": "Create Subdomain",
"description": "Create a new Subdomain in the system that is linked to a Domain.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for a Subdomain.",
"type": "object",
"title": "subdomain_content",
"required": [
"external_id",
"domain_id",
"subdomain_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID of a Domain to which this Subdomain is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"example": "Research",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/subdomains/{subdomain_external_id}": {
"get": {
"tags": [
"TaxonomySubdomains"
],
"summary": "Get Subdomain",
"description": "Get the Subdomain information stored in the system.",
"parameters": [
{
"in": "path",
"name": "subdomain_external_id",
"required": true,
"description": "The unique Subdomain ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "custom_properties",
"description": "Additional Subdomain attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
}
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure for Subdomain.",
"type": "object",
"title": "subdomain_content",
"required": [
"external_id",
"domain_id",
"subdomain_name",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID of a Domain to which this Subdomain is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"TaxonomySubdomains"
],
"summary": "Update Subdomain",
"description": "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.",
"parameters": [
{
"in": "path",
"name": "subdomain_external_id",
"required": true,
"description": "The unique Subdomain ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for updating a Subdomain.",
"type": "object",
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b9734761-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID of a Domain to which this Subdomain is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"example": "Research",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"TaxonomySubdomains"
],
"summary": "Delete Subdomain",
"description": "Delete Subdomain information stored inside the system.",
"parameters": [
{
"in": "path",
"name": "subdomain_external_id",
"required": true,
"description": "The unique Subdomain ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skill_clusters": {
"get": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "List Skill Clusters",
"description": "Get a list of all Skill Clusters available in the system.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `last_updated` field and `external_id`."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional Skill Cluster info attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skill_cluster_description",
"custom_properties"
]
},
"example": [
"skill_cluster_description",
"custom_properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Skill Cluster entities stored in the system.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Skill Clusters",
"description": "Subset of Skill Clusters starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Skill Cluster.",
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
}
]
},
"example": [
{
"external_id": "bc3a5bc9-5f44-4423-8157-520f8a2f429a",
"skill_cluster_name": "Programming Languages",
"last_updated": "2023-05-22T13:22:39.179747",
"skill_cluster_description": "Knowledge of programming languages and their use in software development."
},
{
"external_id": "62d2c013-ab77-410e-b5fb-2f96eed9c1db",
"skill_cluster_name": "Database Management",
"last_updated": "2023-05-22T13:22:41.165448",
"skill_cluster_description": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle."
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "Create Skill Cluster",
"description": "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.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure for a Skill Cluster.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"external_id",
"domain_id",
"skill_cluster_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a84574fd5-eb84-42dc-a79f-595965eacb564",
"description": "The unique ID of a Domain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"example": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.\n",
"default": "",
"description": "Description of the Skill Cluster. The default is an empty string. Placeholder values such as \"-\" or \"No description\", or a description that exactly matches the Skill Cluster name, are automatically converted to an empty string.\n"
}
}
},
{
"description": "Default structure for a Skill Cluster.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"external_id",
"subdomain_id",
"skill_cluster_name"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b84868455-eb84-42dc-a79f-594bef4784",
"description": "The unique ID of a Subdomain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"example": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.\n",
"default": "",
"description": "Description of the Skill Cluster. The default is an empty string. Placeholder values such as \"-\" or \"No description\", or a description that exactly matches the Skill Cluster name, are automatically converted to an empty string.\n"
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "Bad Request",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skill_clusters/{skill_cluster_external_id}": {
"get": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "Get Skill Cluster",
"description": "Get the Skill Cluster information stored in the system.",
"parameters": [
{
"in": "path",
"name": "skill_cluster_external_id",
"required": true,
"description": "The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include",
"required": false,
"example": "custom_properties",
"description": "Additional Skill Cluster attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties"
]
}
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure for Skill Cluster.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"external_id",
"domain_id",
"skill_cluster_name",
"skill_cluster_description",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"description": "The unique ID of a Domain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"example": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.",
"description": "Description of the Skill Cluster."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
},
{
"description": "Default structure for Skill Cluster.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"external_id",
"subdomain_id",
"skill_cluster_name",
"skill_cluster_description",
"last_updated"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b84868455-eb84-42dc-a79f-594bef4784",
"description": "The unique ID of a Subdomain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"example": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.",
"description": "Description of the Skill Cluster."
},
"last_updated": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last update to this entity.",
"example": "2021-01-21T17:32:28Z"
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "Update Skill Cluster",
"description": "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.",
"parameters": [
{
"in": "path",
"name": "skill_cluster_external_id",
"required": true,
"description": "The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure for updating a Skill Cluster.",
"type": "object",
"title": "3-level Taxonomy",
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID of a Domain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"default": "",
"example": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.",
"description": "Description of the Skill Cluster. Any changes with placeholder values such as \"-\" or \"No description\", or a description that is identical to the Skill Cluster name, will be automatically saved as an empty string (the default)."
}
}
},
{
"description": "Default structure for updating a Skill Cluster.",
"type": "object",
"title": "4-level Taxonomy",
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b84868455-eb84-42dc-a79f-594bef4784",
"description": "The unique ID of a Subdomain to which this Skill Cluster is linked, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"example": "Database Management",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"default": "",
"example": "Knowledge of actions a business takes to manipulate and control data to meet necessary conditions throughout the entire data lifecycle.",
"description": "Description of the Skill Cluster. Any changes with placeholder values such as \"-\" or \"No description\", or a description that is identical to the Skill Cluster name, will be automatically saved as an empty string (the default)."
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "Delete Skill Cluster",
"description": "Delete Skill Cluster information stored inside the system.",
"parameters": [
{
"in": "path",
"name": "skill_cluster_external_id",
"required": true,
"description": "The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skill_clusters/{skill_cluster_external_id}/skills": {
"get": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "List Skills",
"description": "Get a list of all Skills linked to a Skill Cluster.",
"parameters": [
{
"in": "path",
"name": "skill_cluster_external_id",
"required": true,
"description": "The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `skill_id` field."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional Skill info attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skill_description",
"properties"
]
},
"example": [
"skill_description",
"properties"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"count": {
"description": "Total number of Skills linked to a Skill Cluster.",
"type": "integer",
"minimum": 0,
"example": 2
},
"results": {
"title": "Skills",
"description": "Subset of Skills starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for Skill.",
"type": "object",
"title": "skill_content",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"example": "Python",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
]
},
"example": [
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"properties": {
"sap_status": {
"value": "active"
}
}
},
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"properties": {
"sap_status": {
"value": "active"
}
}
},
{
"skill_id": "9844641-2d55-4dde-a71c-d684a26105849",
"skill_name": "Job Architecture Matching",
"skill_description": "Job Architecture Matching is the ability to match jobs to a job architecture.",
"properties": {
"sap_status": {
"value": "inactive"
}
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}": {
"put": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "Add Skill",
"description": "Add a Skill to a Skill Cluster.",
"parameters": [
{
"in": "path",
"name": "skill_cluster_external_id",
"schema": {
"type": "string"
},
"required": true,
"description": "The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores."
},
{
"in": "path",
"name": "skill_id",
"schema": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"required": true
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which the input Skills exist. This will only work for vendors that are activated on your tenant. If not passed, the input Skills have to be in the TechWolf vocabulary.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"TaxonomySkillClusters"
],
"summary": "Remove Skill",
"description": "Remove a Skill from a Skill Cluster.",
"parameters": [
{
"in": "path",
"name": "skill_cluster_external_id",
"required": true,
"description": "The unique Skill Cluster ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "skill_id",
"schema": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"required": true
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which the input Skills exist. This will only work for vendors that are activated on your tenant. If not passed, the input Skills have to be in the TechWolf vocabulary.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skills": {
"get": {
"tags": [
"TaxonomySkills"
],
"summary": "List Skills",
"description": "Get the Skill information stored inside the system for multiple Skills.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of entities returned, ordered by the `skill_id` field."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional Skill info attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skill_description",
"custom_properties",
"properties",
"inference_enabled"
]
},
"example": [
"skill_description"
]
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"results",
"count"
],
"properties": {
"results": {
"title": "Skills",
"description": "Subset of Skills starting from `offset` up to `offset + limit`.",
"type": "array",
"items": {
"required": [
"skill_id",
"skill_name",
"default_skill_name",
"skill_source",
"domain_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. If a custom name is provided, it will be returned; otherwise, the default name in the system is returned.",
"example": "Python"
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"default_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "The default name of the Skill available in the system. This name may differ from the actual name if the Skill's name was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language"
},
"default_skill_description": {
"type": "string",
"minLength": 1,
"nullable": true,
"description": "The default description of the Skill available in the system. This description may differ from the actual description if the Skill's description was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python Programming Language\" requires the ability to write code in the Python programming language."
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
},
"inference_enabled": {
"type": "boolean",
"description": "Whether the Skill can be inferred. For Skills in the vocabulary, this is always true. Only present when requested via the `include` query parameter.",
"example": true
},
"domain_name": {
"type": "string",
"description": "The Domain name of the Skill."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
},
"example": [
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"default_skill_name": "SQL",
"default_skill_description": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary",
"inference_enabled": true,
"domain_name": "Information Technology",
"properties": {
"sap_status": {
"value": "active"
}
}
},
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "Six Sigma",
"skill_description": "Six Sigma is a set of techniques and tools for process improvement. It was introduced by American engineer Bill Smith while working at Motorola in 1986.",
"default_skill_name": "Six Sigma",
"default_skill_description": "Six Sigma is a set of techniques and tools for process improvement. It was introduced by American engineer Bill Smith while working at Motorola in 1986.",
"skill_source": "vocabulary",
"inference_enabled": true,
"domain_name": "",
"properties": {
"sap_status": {
"value": "inactive"
}
}
}
]
},
"count": {
"description": "Total number of Skill entities stored in the system.",
"type": "integer",
"minimum": 0,
"example": 2
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"TaxonomySkills"
],
"summary": "Create Skill",
"description": "Create a new Skill in the system. This endpoint requires write_skills scope access. The new Skill will be flagged as `custom`.",
"security": [
{
"application": [
"write_skills"
]
}
],
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which the input Skills exist. This will only work for vendors that are activated on your tenant. If not passed, the input Skills have to be in the TechWolf vocabulary.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for a Skill.",
"type": "object",
"title": "skill_data",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"example": "SQL",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. This should be provided in the default language (`en_uk`). To add translations, use the [Update Skill]() endpoint."
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. This should be provided in the default language (`en_uk`). To add translations, use the [Update Skill]() endpoint.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Organisational Unit Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown organisational_unit for this resource. This Organisational Unit does not exist yet."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skills/languages": {
"get": {
"tags": [
"TaxonomySkills"
],
"summary": "List available Skill languages",
"description": "Get the list of languages available for Skills in the tenant's vocabulary. The available languages depend on the vocabulary version associated with the specified external vendor.",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"languages"
],
"properties": {
"languages": {
"type": "array",
"description": "The list of language codes available for Skills in the tenant's vocabulary. Each language code follows the internal format (e.g. `en_uk`, `nl`, `fr`).",
"items": {
"type": "string",
"minLength": 1,
"example": "en_uk"
},
"example": [
"en_uk",
"nl",
"fr"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/skills/{skill_id}": {
"get": {
"tags": [
"TaxonomySkills"
],
"summary": "Get Skill",
"description": "Get the Skill information stored in the vocabulary. This can be for either a Skill in the TechWolf vocabulary or a Skill in an external vendor's vocabulary. For TechWolf Skills, meta information such as Skill adoption can also be requested.",
"parameters": [
{
"in": "path",
"name": "skill_id",
"schema": {
"oneOf": [
{
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
{
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"required": true
},
{
"in": "query",
"name": "include",
"required": false,
"example": "custom_properties",
"description": "Additional Skill attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"custom_properties",
"adoption",
"properties",
"inference_enabled"
]
}
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "domain_namespace",
"required": false,
"example": "taxonomy",
"schema": {
"type": "string",
"default": "techwolf",
"enum": [
"techwolf",
"taxonomy",
"adaptive"
]
},
"description": "The Domain namespace determines the Domains the Skills will be mapped to. Using `techwolf` will map them to the default TechWolf domains. Using `taxonomy` will map them to the custom Domains defined in your Taxonomy. Using `adaptive` will map the Skills to the Domains in the custom Taxonomy if there is one present, otherwise it will fall back to the default Techwolf Domains."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to get the Skill from. This only works for vendors that are activated on your tenant. The `adoption` and `custom_properties` included values are not supported for external vendors. External Skill Descriptions will be returned if your tenant is on the latest version of that external vendor.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "skill_name",
"required": false,
"description": "The external vendor's name of the Skill you want to get. Only works when the `external_vendor` query parameter is specified.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure for a Skill.",
"type": "object",
"title": "TechWolf Skill",
"required": [
"skill_id",
"skill_name",
"skill_description",
"default_skill_name",
"default_skill_description",
"skill_source",
"domain_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"example": "Python",
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. If a custom name is provided, it will be returned; otherwise, the default name in the system is returned."
},
"skill_description": {
"example": "Python is a high-level programming language with an intuitive syntax and a versatile standard library.The Skill \\\"Python\\\" requires the ability to write code in the Python programming language.",
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned."
},
"default_skill_name": {
"example": "Python Programming Language",
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "The default name of the Skill available in the system. This name may differ from the actual name if the Skill's name was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`."
},
"default_skill_description": {
"example": "Python Programming Language is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python Programming Language\" requires the ability to write code in the Python programming language.",
"type": "string",
"minLength": 1,
"nullable": true,
"description": "The default description of the Skill available in the system. This description may differ from the actual description if the Skill's description was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`."
},
"skill_source": {
"example": "vocabulary",
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary."
},
"inference_enabled": {
"type": "boolean",
"description": "Whether the Skill can be inferred. For Skills in the vocabulary, this is always true. Only present when requested via the `include` query parameter.",
"example": true
},
"domain_name": {
"type": "string",
"minLength": 1,
"description": "The Domain name of the Skill."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
},
"skill_adoption": {
"type": "object",
"properties": {
"employees": {
"type": "integer",
"description": "The amount of Employees that have this Skill in their profile.",
"minimum": 0,
"example": 35
},
"jobs": {
"type": "integer",
"description": "The amount of Jobs that have this Skill in their governed profile.",
"minimum": 0,
"example": 24
}
}
}
},
"example": {
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"default_skill_name": "SQL",
"default_skill_description": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary",
"inference_enabled": true,
"domain_name": "Information Technology",
"properties": {
"sap_status": {
"value": "active"
}
}
}
},
"example": {
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"default_skill_name": "SQL",
"default_skill_description": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary",
"domain_name": "Information Technology",
"properties": {
"sap_status": {
"value": "active"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "No Skill Clusters available."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"TaxonomySkills"
],
"summary": "Delete Skill",
"description": "Delete the Skill identified by the `skill_id` from the vocabulary. This operation cannot be undone. This step deletes all information linked exclusively to this Skill. By deleting a Skill, you delete it from all Skill Clusters and Skill Profiles containing it. This endpoint requires write_skills scope access. Please note that it is only possible to delete Skills flagged as `custom`.",
"parameters": [
{
"in": "path",
"name": "skill_id",
"schema": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"required": true
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary the custom Skill you want to delete belongs to. This only works for vendors that are activated on your tenant. Defaults to the TechWolf vocabulary if not specified.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"write_skills"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"TaxonomySkills"
],
"summary": "Update Skill",
"description": "Update the Skill information stored in the vocabulary. To add or update translations, set the `vocab_language` query parameter to the desired language. This can be for either a TechWolf Skill, a Skill in an external vendor's vocabulary, or a custom Skill. To revert to the default name or description provided by TechWolf, set the `skill_name` or `skill_description` field to null. It is not possible to revert the name or description of a custom Skill in the default (en_uk) language.",
"parameters": [
{
"in": "path",
"name": "skill_id",
"schema": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"required": true
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which the input Skills exist. This will only work for vendors that are activated on your tenant. If not passed, the input Skills have to be in the TechWolf vocabulary.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "The language to update the Skill name or description in. If not specified, the default language (`en_uk`) will be used. The `en` language is an alias for `en_uk`.",
"schema": {
"type": "string",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl"
]
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"title": "Update Skill description",
"properties": {
"skill_name": {
"nullable": true,
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. Setting the Skill name to null will reset it to the default name provided by TechWolf. Please note that updating the name of a Skill within one Skill Cluster will apply that change across all other Skill Clusters containing the same Skill.",
"example": "SQL"
},
"skill_description": {
"nullable": true,
"type": "string",
"description": "Description of the Skill. Setting the Skill description to null will reset it to the default description provided by TechWolf. Please note that updating the description of a Skill within one Skill Cluster will apply that change across all other Skill Clusters containing the same Skill.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
},
"examples": {
"example1": {
"summary": "Update Skill Name andDescription",
"value": {
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries.",
"properties": {
"sap_status": {
"value": "active"
}
}
}
},
"example2": {
"summary": "Reset Skill Name and Description",
"value": {
"skill_name": null,
"skill_description": null
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/export": {
"get": {
"tags": [
"TaxonomyExport"
],
"summary": "Get Taxonomy export",
"description": "Get an export of the entire Taxonomy.",
"parameters": [
{
"in": "query",
"name": "include",
"required": false,
"description": "Additional attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skill_description",
"skill_cluster_description",
"properties",
"inference_enabled"
]
},
"example": [
"skill_description",
"skill_cluster_description"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure for Domain.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"domains"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains within the Taxonomy.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"external_id",
"domain_name",
"skill_clusters"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
},
"skill_clusters": {
"title": "Skill Clusters",
"description": "A list of all Skill Clusters within the Domain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
},
"skills": {
"title": "Skills",
"description": "A list of all Skills within the Skill Cluster.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_content",
"required": [
"skill_id",
"skill_name",
"default_skill_name",
"skill_source"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. If a custom name is provided, it will be returned; otherwise, the default name in the system is returned.",
"example": "Python"
},
"default_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "The default name of the Skill available in the system. This name may differ from the actual name if the Skill's name was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language"
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"default_skill_description": {
"type": "string",
"minLength": 1,
"nullable": true,
"description": "The default description of the Skill available in the system. This description may differ from the actual description if the Skill's description was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python Programming Language\" requires the ability to write code in the Python programming language."
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
},
"inference_enabled": {
"type": "boolean",
"description": "Whether the Skill can be inferred. For Skills in the vocabulary, this is always true. Only present when requested via the `include` query parameter.",
"example": true
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
]
}
}
}
}
]
}
}
}
}
]
}
}
},
"example": {
"domains": [
{
"external_id": "48329b6e-6770-4f95-88a1-79dcc38b1c08",
"domain_name": "Human Resources",
"skill_clusters": [
{
"external_id": "c8e866ac-c1e5-4386-8911-d17320c54db9",
"skill_cluster_name": "Recruiting",
"skill_cluster_description": "Recruiting is the process of attracting, screening, and selecting qualified people for a job. Recruiting requires the ability to identify and attract potential candidates to an organization.",
"skills": [
{
"skill_id": "8037b52e-841c-471c-9c16-ffb0e9c6c490",
"skill_name": "Screening Resumes",
"default_skill_name": "Screening Resumes",
"skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"default_skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"skill_source": "vocabulary"
},
{
"skill_id": "aa0195dc-3784-4c20-9d3c-5a6373ffd179",
"skill_name": "Student Recruiting",
"default_skill_name": "Student Recruiting",
"skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"default_skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"skill_source": "vocabulary"
},
{
"skill_id": "77a43cdb-51d6-44f0-8f0e-d155f0bd0088",
"skill_name": "Writing",
"default_skill_name": "Writing",
"skill_description": "",
"default_skill_description": "",
"skill_source": "vocabulary"
}
]
}
]
},
{
"external_id": "9c022f76-a649-4d08-a52f-ec3f9ad8ba42",
"domain_name": "IT",
"skill_clusters": [
{
"external_id": "2e7c8774-3416-4033-b640-8a255f70df2c",
"skill_cluster_name": "Programming Languages",
"skill_cluster_description": "Knowledge of programming languages and their use in software development.",
"skills": [
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"default_skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"default_skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"default_skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
},
{
"external_id": "564aadce-b2c7-4c4e-a87a-63263963db21",
"skill_cluster_name": "Debug Software",
"skill_cluster_description": "Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system. Debugging requires the ability to identify and fix issues within a software system.",
"skills": [
{
"skill_id": "267d511f-26d4-4c84-b2ae-eae89627deba",
"skill_name": "Unit Testing",
"default_skill_name": "Unit Testing",
"skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"default_skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"default_skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
}
]
}
]
}
},
{
"description": "Default structure for Domain.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"domains"
],
"properties": {
"domains": {
"title": "Domains",
"description": "A list of all Domains within the Taxonomy.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "domain_content",
"required": [
"external_id",
"domain_name",
"subdomains"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
},
"subdomains": {
"title": "Subdomains",
"description": "A list of all Subdomains within the Domain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "subdomain_content",
"required": [
"external_id",
"subdomain_name",
"skill_clusters"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
},
"skill_clusters": {
"title": "Skill Clusters",
"description": "A list of all Skill Clusters within the Subdomain.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_cluster_content",
"required": [
"external_id",
"skill_cluster_name",
"skills"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
},
"skills": {
"title": "Skills",
"description": "A list of all Skills within the Skill Cluster.",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"title": "skill_content",
"required": [
"skill_id",
"skill_name",
"default_skill_name",
"skill_source"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill. If a custom name is provided, it will be returned; otherwise, the default name in the system is returned.",
"example": "Python"
},
"default_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "The default name of the Skill available in the system. This name may differ from the actual name if the Skill's name was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language"
},
"skill_description": {
"type": "string",
"minLength": 1,
"description": "Description of the Skill. If a custom description is provided, it will be returned; otherwise, the default description from TechWolf is returned.",
"example": "SQL is a standard database query language. The Skill \"SQL\" requires the ability to write and execute SQL queries."
},
"default_skill_description": {
"type": "string",
"minLength": 1,
"nullable": true,
"description": "The default description of the Skill available in the system. This description may differ from the actual description if the Skill's description was updated in the requested language. For Skills with `skill_source=custom`, this field will be `null`.",
"example": "Python Programming Language is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python Programming Language\" requires the ability to write code in the Python programming language."
},
"skill_source": {
"type": "string",
"enum": [
"custom",
"vocabulary"
],
"description": "The source of the Skill. Defines whether the Skill is a custom Skill or a Skill from the default vocabulary.",
"example": "vocabulary"
},
"inference_enabled": {
"type": "boolean",
"description": "Whether the Skill can be inferred. For Skills in the vocabulary, this is always true. Only present when requested via the `include` query parameter.",
"example": true
},
"properties": {
"type": "object",
"nullable": true,
"description": "Skill Properties give additional information about the Skill. These properties are the same over all occurrences of the Skill.",
"properties": {
"sap_status": {
"type": "object",
"description": "Status of the Skill in the SAP Attribute Library.",
"properties": {
"value": {
"type": "string",
"description": "Value of the Skill property.",
"enum": [
"active",
"inactive"
]
}
},
"required": [
"value"
]
}
},
"example": {
"sap_status": {
"value": "active"
}
}
}
}
}
]
}
}
}
}
]
}
}
}
}
]
}
}
}
}
]
}
}
},
"example": {
"domains": [
{
"external_id": "845684ba4-6770-4f95-88a1-79dcc38b1c08",
"domain_name": "Skill Based Organisation",
"subdomains": [
{
"external_id": "48329b6e-6770-4f95-88a1-79dcc38b1c08",
"subdomain_name": "Human Resources",
"skill_clusters": [
{
"external_id": "c8e866ac-c1e5-4386-8911-d17320c54db9",
"skill_cluster_name": "Recruiting",
"skill_cluster_description": "Recruiting is the process of attracting, screening, and selecting qualified people for a job. Recruiting requires the ability to identify and attract potential candidates to an organization.",
"skills": [
{
"skill_id": "8037b52e-841c-471c-9c16-ffb0e9c6c490",
"skill_name": "Screening Resumes",
"default_skill_name": "Screening Resumes",
"skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"default_skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"skill_source": "vocabulary"
},
{
"skill_id": "aa0195dc-3784-4c20-9d3c-5a6373ffd179",
"skill_name": "Student Recruiting",
"default_skill_name": "Student Recruiting",
"skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"default_skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"skill_source": "vocabulary"
},
{
"skill_id": "77a43cdb-51d6-44f0-8f0e-d155f0bd0088",
"skill_name": "Writing",
"default_skill_name": "Writing",
"skill_description": "",
"default_skill_description": "",
"skill_source": "vocabulary"
}
]
}
]
},
{
"external_id": "9c022f76-a649-4d08-a52f-ec3f9ad8ba42",
"subdomain_name": "IT",
"skill_clusters": [
{
"external_id": "2e7c8774-3416-4033-b640-8a255f70df2c",
"skill_cluster_name": "Programming Languages",
"skill_cluster_description": "Knowledge of programming languages and their use in software development.",
"skills": [
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"default_skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"default_skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"default_skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
},
{
"external_id": "564aadce-b2c7-4c4e-a87a-63263963db21",
"skill_cluster_name": "Debug Software",
"skill_cluster_description": "Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system. Debugging requires the ability to identify and fix issues within a software system.",
"skills": [
{
"skill_id": "267d511f-26d4-4c84-b2ae-eae89627deba",
"skill_name": "Unit Testing",
"default_skill_name": "Unit Testing",
"skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"default_skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"default_skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
}
]
}
]
}
]
}
}
]
},
"examples": {
"3levelExample": {
"summary": "3-level Taxonomy",
"value": {
"domains": [
{
"external_id": "48329b6e-6770-4f95-88a1-79dcc38b1c08",
"domain_name": "Human Resources",
"skill_clusters": [
{
"external_id": "c8e866ac-c1e5-4386-8911-d17320c54db9",
"skill_cluster_name": "Recruiting",
"skill_cluster_description": "Recruiting is the process of attracting, screening, and selecting qualified people for a job. Recruiting requires the ability to identify and attract potential candidates to an organization.",
"skills": [
{
"skill_id": "8037b52e-841c-471c-9c16-ffb0e9c6c490",
"skill_name": "Screening Resumes",
"skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"default_skill_name": "Screening Resumes",
"default_skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"skill_source": "vocabulary"
},
{
"skill_id": "aa0195dc-3784-4c20-9d3c-5a6373ffd179",
"skill_name": "Student Recruiting",
"skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"default_skill_name": "Student Recruiting",
"default_skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"skill_source": "vocabulary"
},
{
"skill_id": "77a43cdb-51d6-44f0-8f0e-d155f0bd0088",
"skill_name": "Writing",
"skill_description": "",
"default_skill_name": "Writing",
"default_skill_description": "",
"skill_source": "vocabulary"
}
]
}
]
},
{
"external_id": "9c022f76-a649-4d08-a52f-ec3f9ad8ba42",
"domain_name": "IT",
"skill_clusters": [
{
"external_id": "2e7c8774-3416-4033-b640-8a255f70df2c",
"skill_cluster_name": "Programming Languages",
"skill_cluster_description": "Knowledge of programming languages and their use in software development.",
"skills": [
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"default_skill_name": "SQL",
"default_skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_name": "Python",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
},
{
"external_id": "564aadce-b2c7-4c4e-a87a-63263963db21",
"skill_cluster_name": "Debug Software",
"skill_cluster_description": "Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system. Debugging requires the ability to identify and fix issues within a software system.",
"skills": [
{
"skill_id": "267d511f-26d4-4c84-b2ae-eae89627deba",
"skill_name": "Unit Testing",
"skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly."
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_name": "Unit Testing",
"default_skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"skill_source": "vocabulary"
}
]
}
]
}
]
}
},
"4levelExample": {
"summary": "4-level Taxonomy",
"value": {
"domains": [
{
"external_id": "845684ba4-6770-4f95-88a1-79dcc38b1c08",
"domain_name": "Skill Based Organisation",
"subdomains": [
{
"external_id": "48329b6e-6770-4f95-88a1-79dcc38b1c08",
"subdomain_name": "Human Resources",
"skill_clusters": [
{
"external_id": "c8e866ac-c1e5-4386-8911-d17320c54db9",
"skill_cluster_name": "Recruiting",
"skill_cluster_description": "Recruiting is the process of attracting, screening, and selecting qualified people for a job. Recruiting requires the ability to identify and attract potential candidates to an organization.",
"skills": [
{
"skill_id": "8037b52e-841c-471c-9c16-ffb0e9c6c490",
"skill_name": "Screening Resumes",
"skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"default_skill_name": "Screening Resumes",
"default_skill_description": "The Screening Resumes process involves reviewing Job applicants' resumes in order to identify those candidates who best match the qualifications and requirements of the open position. The Skill \"Screening Resumes\" requires one to be able to quickly and effectively screen resumes in order to identify qualified candidates for a position.",
"skill_source": "vocabulary"
},
{
"skill_id": "aa0195dc-3784-4c20-9d3c-5a6373ffd179",
"skill_name": "Student Recruiting",
"skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"default_skill_name": "Student Recruiting",
"default_skill_description": "Student Recruiting is the process of attracting and enrolling students for educational institutions. The Skill \"Student Recruiting\" requires the ability to identify and attract potential students to an organization.",
"skill_source": "vocabulary"
},
{
"skill_id": "77a43cdb-51d6-44f0-8f0e-d155f0bd0088",
"skill_name": "Writing",
"skill_description": "",
"default_skill_name": "Writing",
"default_skill_description": "",
"skill_source": "vocabulary"
}
]
}
]
},
{
"external_id": "9c022f76-a649-4d08-a52f-ec3f9ad8ba42",
"subdomain_name": "IT",
"skill_clusters": [
{
"external_id": "2e7c8774-3416-4033-b640-8a255f70df2c",
"skill_cluster_name": "Programming Languages",
"skill_cluster_description": "Knowledge of programming languages and their use in software development.",
"skills": [
{
"skill_id": "c8c4b3a1-2d55-4dde-a71c-d7129c675a77",
"skill_name": "SQL",
"skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"default_skill_name": "SQL",
"default_skill_description": "SQL is a standard database query language.The Skill \\\"SQL\\\" requires the ability to write and execute SQL queries.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_name": "Python",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
},
{
"external_id": "564aadce-b2c7-4c4e-a87a-63263963db21",
"skill_cluster_name": "Debug Software",
"skill_cluster_description": "Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system. Debugging requires the ability to identify and fix issues within a software system.",
"skills": [
{
"skill_id": "267d511f-26d4-4c84-b2ae-eae89627deba",
"skill_name": "Unit Testing",
"skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"default_skill_name": "Unit Testing",
"default_skill_description": "Unit Testing is a software testing method in which individual units of source code, sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures, are tested to determine whether they are fit for use. The Skill \"Unit Testing\" requires the ability to create and run tests on individual components of a software system to ensure they are functioning correctly.",
"skill_source": "vocabulary"
},
{
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b",
"skill_name": "Python",
"skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"default_skill_name": "Python",
"default_skill_description": "Python is a high-level programming language with an intuitive syntax and a versatile standard library. The Skill \"Python\" requires the ability to write code in the Python programming language.",
"skill_source": "vocabulary"
}
]
}
]
}
]
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/changes": {
"get": {
"deprecated": true,
"tags": [
"Taxonomy"
],
"summary": "Get Taxonomy changes",
"description": "Get a list of changes to the Taxonomy within a certain timeframe.",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"example": 50,
"default": 100
},
"description": "The maximal number of Taxonomy changes returned, ordered by their timestamp."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for the returned Taxonomy changes, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to get the Taxonomy changes for. This only works for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "timestamp_from",
"required": true,
"schema": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"description": "The earliest timestamp (in IS08601 format) for which you want to retrieve Taxonomy changes."
},
{
"in": "query",
"name": "timestamp_to",
"required": true,
"schema": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"description": "The latest timestamp (in IS08601 format) for which you want to retrieve Taxonomy changes."
}
],
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure for Taxonomy changes.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"changes",
"count"
],
"properties": {
"count": {
"type": "integer",
"description": "Number of available Taxonomy changes for the provided parameters.",
"example": 1
},
"changes": {
"type": "array",
"description": "Subset of Taxonomy changes starting from `offset` up to `offset + limit`.",
"items": {
"allOf": [
{
"type": "object",
"required": [
"operation_type",
"content"
],
"properties": {
"operation_type": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"update_skill",
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill",
"vocab_update_description"
],
"example": "create_domain",
"description": "The type of operation to be performed."
},
"content": {
"description": "The content of the change. Each type of change has a different content. The content should align with the `operation_type`. Expanding this field shows you the supported change content bodies.",
"oneOf": [
{
"title": "create_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "delete_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "update_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "create_skill_cluster_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"skill_cluster_id",
"skill_cluster_name",
"skill_cluster_description"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain where the Skill Cluster will be created."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "delete_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
}
}
},
{
"title": "update_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "move_skill_cluster_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Domain in your system to where the Skill Cluster will be moved."
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Domain in your system to where the Skill Cluster will be moved."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Skill Cluster that will be moved."
}
}
},
{
"title": "add_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be added."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "remove_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be removed."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "move_skill_change_content",
"type": "object",
"required": [
"from_skill_cluster_id",
"skill_id",
"to_skill_cluster_id"
],
"properties": {
"from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"to_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "create_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill, provided in the default language (`en_uk`)."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill, provided in the default language (`en_uk`)."
}
}
},
{
"title": "delete_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill, provided in the default language (`en_uk`)."
}
}
},
{
"title": "update_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. If this is null, the name will be reset to the default one provided by TechWolf."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. If this is null, the description will be reset to the default one provided by TechWolf."
}
}
},
{
"title": "vocab_update_add_skill",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill, provided in the default language (`en_uk`). `null` if the Skill has no description."
}
}
},
{
"title": "vocab_update_rename_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"old_skill_name",
"new_skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"old_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Old name of the Skill."
},
"new_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "New name of the Skill."
}
}
},
{
"title": "vocab_update_merge_skill",
"type": "object",
"required": [
"merged_from_skill_cluster_id",
"merged_from_skill_cluster_name",
"merged_from_skill_id",
"merged_from_skill_name",
"merged_into_skill_cluster_id",
"merged_into_skill_cluster_name",
"merged_into_skill_id",
"merged_into_skill_name"
],
"properties": {
"merged_from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster from which the Skill is being merged."
},
"merged_from_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being merged."
},
"merged_into_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster into which the Skill is being merged."
},
"merged_into_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill into which the Skill is being merged."
}
}
},
{
"title": "vocab_update_remove_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being removed."
}
}
},
{
"title": "vocab_update_description",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name",
"old_description",
"new_description"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill whose description changed."
},
"old_description": {
"type": "string",
"nullable": true,
"description": "Previous description of the Skill, provided in the default language (`en_uk`). `null` if the Skill had no description before."
},
"new_description": {
"type": "string",
"nullable": true,
"description": "New description of the Skill, provided in the default language (`en_uk`). `null` if the description was cleared."
}
}
}
],
"example": {
"domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domain_name": "HR management"
}
}
}
},
{
"type": "object",
"required": [
"timestamp"
],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the change.",
"example": "2021-01-21T17:32:28"
}
}
}
]
}
}
}
},
{
"description": "Default structure for Taxonomy changes.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"changes",
"count"
],
"properties": {
"count": {
"type": "integer",
"description": "Number of available Taxonomy changes for the provided parameters.",
"example": 1
},
"changes": {
"type": "array",
"description": "Subset of Taxonomy changes starting from `offset` up to `offset + limit`.",
"items": {
"allOf": [
{
"type": "object",
"required": [
"operation_type",
"content"
],
"properties": {
"operation_type": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_subdomain",
"delete_subdomain",
"update_subdomain",
"move_subdomain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"update_skill",
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill",
"vocab_update_description"
],
"example": "create_subdomain",
"description": "The type of operation to be performed."
},
"content": {
"description": "The content of the change. Each type of change has a different content. The content should align with the `operation_type`. Expanding this field shows you the supported change content bodies.",
"oneOf": [
{
"title": "create_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "delete_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "update_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "create_subdomain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"subdomain_id",
"subdomain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "delete_subdomain_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "update_subdomain_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "move_subdomain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"subdomain_id",
"subdomain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Domain in your system to where the Subdomain will be moved."
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Domain in your system to where the Subdomain will be moved."
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Subdomain that will be moved."
}
}
},
{
"title": "create_skill_cluster_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name",
"skill_cluster_id",
"skill_cluster_name",
"skill_cluster_description"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain where the Skill Cluster will be created."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "delete_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
}
}
},
{
"title": "update_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "move_skill_cluster_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Subdomain in your system to where the Skill Cluster will be moved."
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Subdomain in your system to where the Skill Cluster will be moved."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Skill Cluster that will be moved."
}
}
},
{
"title": "add_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be added."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "remove_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be removed."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "move_skill_change_content",
"type": "object",
"required": [
"from_skill_cluster_id",
"skill_id",
"to_skill_cluster_id"
],
"properties": {
"from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"to_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "create_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill, provided in the default language (`en_uk`)."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill, provided in the default language (`en_uk`)."
}
}
},
{
"title": "delete_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill, provided in the default language (`en_uk`)."
}
}
},
{
"title": "update_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. If this is null, the name will be reset to the default one provided by TechWolf."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. If this is null, the description will be reset to the default one provided by TechWolf."
}
}
},
{
"title": "vocab_update_add_skill",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill, provided in the default language (`en_uk`). `null` if the Skill has no description."
}
}
},
{
"title": "vocab_update_rename_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"old_skill_name",
"new_skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"old_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Old name of the Skill."
},
"new_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "New name of the Skill."
}
}
},
{
"title": "vocab_update_merge_skill",
"type": "object",
"required": [
"merged_from_skill_cluster_id",
"merged_from_skill_cluster_name",
"merged_from_skill_id",
"merged_from_skill_name",
"merged_into_skill_cluster_id",
"merged_into_skill_cluster_name",
"merged_into_skill_id",
"merged_into_skill_name"
],
"properties": {
"merged_from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster from which the Skill is being merged."
},
"merged_from_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being merged."
},
"merged_into_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster into which the Skill is being merged."
},
"merged_into_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill into which the Skill is being merged."
}
}
},
{
"title": "vocab_update_remove_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being removed."
}
}
},
{
"title": "vocab_update_description",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name",
"old_description",
"new_description"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill whose description changed."
},
"old_description": {
"type": "string",
"nullable": true,
"description": "Previous description of the Skill, provided in the default language (`en_uk`). `null` if the Skill had no description before."
},
"new_description": {
"type": "string",
"nullable": true,
"description": "New description of the Skill, provided in the default language (`en_uk`). `null` if the description was cleared."
}
}
}
],
"example": {
"subdomain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"subdomain_name": "Research"
}
}
}
},
{
"type": "object",
"required": [
"timestamp"
],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the change.",
"example": "2021-01-21T17:32:28"
}
}
}
]
}
}
}
}
]
},
"examples": {
"3levelExample": {
"summary": "3-level Taxonomy",
"value": {
"count": 1,
"changes": [
{
"operation_type": "create_domain",
"content": {
"domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domain_name": "HR management"
},
"timestamp": "2021-01-21T17:32:28"
}
]
}
},
"4levelExample": {
"summary": "4-level Taxonomy",
"value": {
"count": 1,
"changes": [
{
"operation_type": "create_subdomain",
"content": {
"subdomain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"subdomain_name": "Research"
},
"timestamp": "2021-01-21T17:32:28"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"TaxonomyExport"
],
"summary": "Export Taxonomy changes",
"description": "Export Taxonomy changes with filtering and keyset pagination. This endpoint supports filtering by operation type, external ID, and timestamp, and uses keyset pagination for efficient retrieval of large datasets. This endpoint returns changes for all skills, including those outside the current Taxonomy, and includes the `external_id` field in the response.",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to get Taxonomy changes from. Defaults to TechWolf if not specified. This parameter filters changes to only include vendor-aware operations for the specified vendor, or vendor-unaware operations that apply to all vendors.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "The maximal number of Taxonomy changes returned per page. Used for keyset pagination.",
"example": 100
},
"starting_after": {
"type": "string",
"maxLength": 100,
"description": "The `external_id` of the Taxonomy change to continue looking from. Use this value from the `next_starting_after` field in the previous response to get the next page of results.",
"example": "5a149aca-671a-4eb1-9fe8-37673c11e6ef"
},
"filters": {
"type": "array",
"description": "A list of filters to apply on the Taxonomy changes. Supported filters include filtering by operation type, external ID, and timestamp.",
"items": {
"anyOf": [
{
"type": "object",
"title": "operation_type_is_in_list",
"required": [
"filter",
"operation_types"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter Taxonomy changes based on operation type being in a list.",
"enum": [
"operation_type_is_in_list"
],
"example": "operation_type_is_in_list"
},
"operation_types": {
"type": "array",
"description": "List of operation types to filter by.",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_subdomain",
"delete_subdomain",
"update_subdomain",
"move_subdomain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"create_skill",
"delete_skill",
"update_skill",
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill",
"vocab_update_description"
]
},
"example": [
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill"
]
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "timestamp",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter Taxonomy changes based on their timestamp. The default operator is `gte`.",
"enum": [
"timestamp"
],
"example": "timestamp"
},
"value": {
"description": "The timestamp value (in ISO8601 format) to filter against.",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering Taxonomy changes based on the timestamp value. Operator `lt` returns changes with a timestamp < (before) the given `value`. Operator `lte` returns changes with timestamp <= the given `value`. Operator `gte` returns changes with timestamp >= the given `value`. Operator `gt` returns changes with timestamp > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gte",
"gt"
],
"default": "gte",
"example": "gte"
}
}
}
]
},
"example": [
{
"filter": "operation_type_is_in_list",
"operation_types": [
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill"
]
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"e92ae376-da31-4fd8-b29e-a767715a703d",
"6d7dd039-867b-4376-9f6f-b53ff7651d88"
]
},
{
"filter": "timestamp",
"value": "2021-01-21T17:32:28",
"operator": "gte"
},
{
"filter": "timestamp",
"value": "2021-02-01T00:00:00",
"operator": "lte"
}
]
}
}
},
"examples": {
"basicExample": {
"summary": "Basic request",
"value": {
"limit": 100
}
},
"withFiltersExample": {
"summary": "Request with filters",
"value": {
"limit": 100,
"filters": [
{
"filter": "operation_type_is_in_list",
"operation_types": [
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill"
]
}
]
}
},
"timestampFilterExample": {
"summary": "Request with timestamp filters",
"value": {
"limit": 100,
"filters": [
{
"filter": "timestamp",
"value": "2021-01-21T17:32:28",
"operator": "gte"
},
{
"filter": "timestamp",
"value": "2021-02-01T00:00:00",
"operator": "lte"
}
]
}
},
"paginationExample": {
"summary": "Paginated request",
"value": {
"limit": 50,
"starting_after": "5a149aca-671a-4eb1-9fe8-37673c11e6ef"
}
}
}
}
}
},
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure for Taxonomy changes export (POST endpoint).",
"type": "object",
"title": "3-level Taxonomy Export",
"required": [
"records",
"has_next"
],
"properties": {
"has_next": {
"type": "boolean",
"description": "Whether there are more Taxonomy changes available after the current page.",
"example": true
},
"records": {
"type": "array",
"description": "List of Taxonomy changes returned for the current page, ordered by timestamp.",
"items": {
"allOf": [
{
"type": "object",
"required": [
"external_id",
"operation_type",
"content"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the Taxonomy change.",
"example": "e92ae376-da31-4fd8-b29e-a767715a703d"
},
"operation_type": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"create_skill",
"delete_skill",
"update_skill",
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill",
"vocab_update_description"
],
"example": "vocab_update_rename_skill",
"description": "The type of operation to be performed."
},
"content": {
"description": "The content of the change. Each type of change has a different content. The content should align with the `operation_type`. Expanding this field shows you the supported change content bodies.",
"oneOf": [
{
"title": "create_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "delete_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "update_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "create_skill_cluster_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"skill_cluster_id",
"skill_cluster_name",
"skill_cluster_description"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain where the Skill Cluster will be created."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "delete_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
}
}
},
{
"title": "update_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "move_skill_cluster_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Domain in your system to where the Skill Cluster will be moved."
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Domain in your system to where the Skill Cluster will be moved."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Skill Cluster that will be moved."
}
}
},
{
"title": "add_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be added."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "remove_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be removed."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "move_skill_change_content",
"type": "object",
"required": [
"from_skill_cluster_id",
"skill_id",
"to_skill_cluster_id"
],
"properties": {
"from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"to_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. If this is null, the name will be reset to the default one provided by TechWolf."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. If this is null, the description will be reset to the default one provided by TechWolf."
}
}
},
{
"title": "vocab_update_add_skill",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill, provided in the default language (`en_uk`). `null` if the Skill has no description."
}
}
},
{
"title": "vocab_update_rename_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"old_skill_name",
"new_skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"old_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Old name of the Skill."
},
"new_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "New name of the Skill."
}
}
},
{
"title": "vocab_update_merge_skill",
"type": "object",
"required": [
"merged_from_skill_cluster_id",
"merged_from_skill_cluster_name",
"merged_from_skill_id",
"merged_from_skill_name",
"merged_into_skill_cluster_id",
"merged_into_skill_cluster_name",
"merged_into_skill_id",
"merged_into_skill_name"
],
"properties": {
"merged_from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster from which the Skill is being merged."
},
"merged_from_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being merged."
},
"merged_into_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster into which the Skill is being merged."
},
"merged_into_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill into which the Skill is being merged."
}
}
},
{
"title": "vocab_update_remove_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being removed."
}
}
},
{
"title": "vocab_update_description",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name",
"old_description",
"new_description"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill whose description changed."
},
"old_description": {
"type": "string",
"nullable": true,
"description": "Previous description of the Skill, provided in the default language (`en_uk`). `null` if the Skill had no description before."
},
"new_description": {
"type": "string",
"nullable": true,
"description": "New description of the Skill, provided in the default language (`en_uk`). `null` if the description was cleared."
}
}
}
],
"example": {
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"old_skill_name": "old_skill_name",
"new_skill_name": "new_skill_name"
}
}
}
},
{
"type": "object",
"required": [
"timestamp"
],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the change.",
"example": "2021-01-21T17:32:28"
}
}
}
]
}
},
"next_starting_after": {
"type": "string",
"description": "The `external_id` of the last Taxonomy change in the current page. Use this value as `starting_after` in the next request to get the next page of results. Only present when `has_next` is `true`.",
"example": "5a149aca-671a-4eb1-9fe8-37673c11e6ef"
}
}
},
{
"description": "Default structure for Taxonomy changes export (POST endpoint) for 4-level Taxonomy.",
"type": "object",
"title": "4-level Taxonomy Export",
"required": [
"records",
"has_next"
],
"properties": {
"has_next": {
"type": "boolean",
"description": "Whether there are more Taxonomy changes available after the current page.",
"example": true
},
"records": {
"type": "array",
"description": "List of Taxonomy changes returned for the current page, ordered by timestamp.",
"items": {
"allOf": [
{
"type": "object",
"required": [
"external_id",
"operation_type",
"content"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the Taxonomy change.",
"example": "e92ae376-da31-4fd8-b29e-a767715a703d"
},
"operation_type": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_subdomain",
"delete_subdomain",
"update_subdomain",
"move_subdomain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"create_skill",
"delete_skill",
"update_skill",
"vocab_update_add_skill",
"vocab_update_rename_skill",
"vocab_update_merge_skill",
"vocab_update_remove_skill",
"vocab_update_description"
],
"example": "vocab_update_rename_skill",
"description": "The type of operation to be performed."
},
"content": {
"description": "The content of the change. Each type of change has a different content. The content should align with the `operation_type`. Expanding this field shows you the supported change content bodies.",
"oneOf": [
{
"title": "create_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "delete_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "update_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "create_subdomain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"subdomain_id",
"subdomain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "delete_subdomain_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "update_subdomain_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "move_subdomain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name",
"subdomain_id",
"subdomain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Domain in your system to where the Subdomain will be moved."
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Domain in your system to where the Subdomain will be moved."
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Subdomain that will be moved."
}
}
},
{
"title": "create_skill_cluster_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name",
"skill_cluster_id",
"skill_cluster_name",
"skill_cluster_description"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain where the Skill Cluster will be created."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "delete_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
}
}
},
{
"title": "update_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster."
}
}
},
{
"title": "move_skill_cluster_change_content",
"type": "object",
"required": [
"subdomain_id",
"subdomain_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Subdomain in your system to where the Skill Cluster will be moved."
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Subdomain in your system to where the Skill Cluster will be moved."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Research",
"description": "The name of the Skill Cluster that will be moved."
}
}
},
{
"title": "add_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be added."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "remove_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill will be removed."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
}
}
},
{
"title": "move_skill_change_content",
"type": "object",
"required": [
"from_skill_cluster_id",
"skill_id",
"to_skill_cluster_id"
],
"properties": {
"from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"to_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. If this is null, the name will be reset to the default one provided by TechWolf."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. If this is null, the description will be reset to the default one provided by TechWolf."
}
}
},
{
"title": "vocab_update_add_skill",
"type": "object",
"required": [
"skill_id",
"skill_name",
"skill_description"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill, provided in the default language (`en_uk`). `null` if the Skill has no description."
}
}
},
{
"title": "vocab_update_rename_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"old_skill_name",
"new_skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"old_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Old name of the Skill."
},
"new_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "New name of the Skill."
}
}
},
{
"title": "vocab_update_merge_skill",
"type": "object",
"required": [
"merged_from_skill_cluster_id",
"merged_from_skill_cluster_name",
"merged_from_skill_id",
"merged_from_skill_name",
"merged_into_skill_cluster_id",
"merged_into_skill_cluster_name",
"merged_into_skill_id",
"merged_into_skill_name"
],
"properties": {
"merged_from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster from which the Skill is being merged."
},
"merged_from_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_from_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being merged."
},
"merged_into_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster into which the Skill is being merged."
},
"merged_into_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"merged_into_skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill into which the Skill is being merged."
}
}
},
{
"title": "vocab_update_remove_skill",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill being removed."
}
}
},
{
"title": "vocab_update_description",
"type": "object",
"required": [
"skill_cluster_id",
"skill_cluster_name",
"skill_id",
"skill_name",
"old_description",
"new_description"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster where the Skill belongs to."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill whose description changed."
},
"old_description": {
"type": "string",
"nullable": true,
"description": "Previous description of the Skill, provided in the default language (`en_uk`). `null` if the Skill had no description before."
},
"new_description": {
"type": "string",
"nullable": true,
"description": "New description of the Skill, provided in the default language (`en_uk`). `null` if the description was cleared."
}
}
}
],
"example": {
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"old_skill_name": "old_skill_name",
"new_skill_name": "new_skill_name"
}
}
}
},
{
"type": "object",
"required": [
"timestamp"
],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the change.",
"example": "2021-01-21T17:32:28"
}
}
}
]
}
},
"next_starting_after": {
"type": "string",
"description": "The `external_id` of the last Taxonomy change in the current page. Use this value as `starting_after` in the next request to get the next page of results. Only present when `has_next` is `true`.",
"example": "5a149aca-671a-4eb1-9fe8-37673c11e6ef"
}
}
}
]
},
"examples": {
"vocabUpdateExample": {
"summary": "Vocabulary update changes",
"value": {
"has_next": true,
"next_starting_after": "5a149aca-671a-4eb1-9fe8-37673c11e6ef",
"records": [
{
"external_id": "e92ae376-da31-4fd8-b29e-a767715a703d",
"operation_type": "vocab_update_rename_skill",
"content": {
"skill_cluster_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skill_cluster_name": "HR management",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"old_skill_name": "old_skill_name",
"new_skill_name": "new_skill_name"
},
"timestamp": "2021-01-21T17:32:28"
},
{
"external_id": "db2f7896-682a-4064-8f92-ff32e4562a37",
"operation_type": "vocab_update_merge_skill",
"content": {
"merged_from_skill_cluster_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"merged_from_skill_cluster_name": "HR management",
"merged_from_skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"merged_from_skill_name": "merged_from_skill_name",
"merged_into_skill_cluster_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"merged_into_skill_cluster_name": "HR management",
"merged_into_skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"merged_into_skill_name": "merged_into_skill_name"
},
"timestamp": "2021-01-21T17:32:28"
},
{
"external_id": "6d7dd039-867b-4376-9f6f-b53ff7651d88",
"operation_type": "vocab_update_remove_skill",
"content": {
"skill_cluster_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skill_cluster_name": "HR management",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skill_name": "skill_name"
},
"timestamp": "2021-01-21T17:32:28"
},
{
"external_id": "9b1c3f2a-4d5e-4a6b-8c7d-0e1f2a3b4c5d",
"operation_type": "vocab_update_description",
"content": {
"skill_cluster_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skill_cluster_name": "HR management",
"skill_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"skill_name": "skill_name",
"old_description": "old_description",
"new_description": "new_description"
},
"timestamp": "2021-01-21T17:32:28"
}
]
}
},
"noMoreResultsExample": {
"summary": "No more results",
"value": {
"has_next": false,
"records": [
{
"external_id": "e92ae376-da31-4fd8-b29e-a767715a703d",
"operation_type": "create_domain",
"content": {
"domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domain_name": "HR management"
},
"timestamp": "2021-01-21T17:32:28"
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/taxonomy/apply": {
"post": {
"tags": [
"Taxonomy"
],
"summary": "Apply Taxonomy changes",
"description": "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.",
"parameters": [
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary in which the input Skills exist. This will only work for vendors that are activated on your tenant. If not passed, the input Skills have to be in the TechWolf vocabulary.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
}
],
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "Default structure of a set of changes.",
"type": "object",
"title": "3-level Taxonomy",
"required": [
"changes"
],
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"required": [
"operation_type",
"content"
],
"properties": {
"operation_type": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"update_skill"
],
"example": "create_domain",
"description": "The type of operation to be performed."
},
"content": {
"description": "The content of the change. Each type of change has a different content. The content should align with the `operation_type`. Expanding this field shows you the supported change content bodies.",
"oneOf": [
{
"title": "create_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "delete_domain_change_content",
"type": "object",
"required": [
"domain_id"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "create_skill_cluster_change_content",
"type": "object",
"required": [
"domain_id",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster. Any changes with placeholder values such as \"-\" or \"No description\", or a description that is identical to the Skill Cluster name, will be automatically saved as an empty string (the default)."
}
}
},
{
"title": "delete_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster. Any changes with placeholder values such as \"-\" or \"No description\", or a description that is identical to the Skill Cluster name, will be automatically saved as an empty string (the default)."
}
}
},
{
"title": "move_skill_cluster_change_content",
"type": "object",
"required": [
"domain_id",
"skill_cluster_id"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Domain in your system to where the Skill Cluster will be moved."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "add_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "remove_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "move_skill_change_content",
"type": "object",
"required": [
"from_skill_cluster_id",
"skill_id",
"to_skill_cluster_id"
],
"properties": {
"from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"to_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "create_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. This should be provided in the default language (`en_uk`)."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. This should be provided in the default language (`en_uk`)."
}
}
},
{
"title": "delete_skill_change_content",
"type": "object",
"required": [
"skill_id"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_skill_change_content",
"type": "object",
"required": [
"skill_id"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. If this is null, the name will be reset to the default one provided by TechWolf."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. If this is null, the description will be reset to the default one provided by TechWolf."
}
}
}
],
"example": {
"domain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"domain_name": "HR management"
}
}
}
}
}
}
},
{
"description": "Default structure of a set of changes.",
"type": "object",
"title": "4-level Taxonomy",
"required": [
"changes"
],
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"required": [
"operation_type",
"content"
],
"properties": {
"operation_type": {
"type": "string",
"enum": [
"create_domain",
"delete_domain",
"update_domain",
"create_subdomain",
"delete_subdomain",
"update_subdomain",
"move_subdomain",
"create_skill_cluster",
"delete_skill_cluster",
"update_skill_cluster",
"move_skill_cluster",
"add_skill",
"remove_skill",
"move_skill",
"update_skill"
],
"example": "create_subdomain",
"description": "The type of operation to be performed."
},
"content": {
"description": "The content of the change. Each type of change has a different content. The content should align with the `operation_type`. Expanding this field shows you the supported change content bodies.",
"oneOf": [
{
"title": "create_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "delete_domain_change_content",
"type": "object",
"required": [
"domain_id"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_domain_change_content",
"type": "object",
"required": [
"domain_id",
"domain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"domain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Domain."
}
}
},
{
"title": "create_subdomain_change_content",
"type": "object",
"required": [
"domain_id",
"subdomain_id",
"subdomain_name"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "delete_subdomain_change_content",
"type": "object",
"required": [
"subdomain_id"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_subdomain_change_content",
"type": "object",
"required": [
"subdomain_id"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"subdomain_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Subdomain."
}
}
},
{
"title": "move_subdomain_change_content",
"type": "object",
"required": [
"domain_id",
"subdomain_id"
],
"properties": {
"domain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Domain in your system to where the Subdomain will be moved."
},
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "create_skill_cluster_change_content",
"type": "object",
"required": [
"subdomain_id",
"skill_cluster_id",
"skill_cluster_name"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster. Any changes with placeholder values such as \"-\" or \"No description\", or a description that is identical to the Skill Cluster name, will be automatically saved as an empty string (the default)."
}
}
},
{
"title": "delete_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_skill_cluster_change_content",
"type": "object",
"required": [
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_cluster_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the Skill Cluster."
},
"skill_cluster_description": {
"type": "string",
"description": "Description of the Skill Cluster. Any changes with placeholder values such as \"-\" or \"No description\", or a description that is identical to the Skill Cluster name, will be automatically saved as an empty string (the default)."
}
}
},
{
"title": "move_skill_cluster_change_content",
"type": "object",
"required": [
"subdomain_id",
"skill_cluster_id"
],
"properties": {
"subdomain_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores. This ID is used to identify the Subdomain in your system to where the Skill Cluster will be moved."
},
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "add_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "remove_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_cluster_id"
],
"properties": {
"skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "move_skill_change_content",
"type": "object",
"required": [
"from_skill_cluster_id",
"skill_id",
"to_skill_cluster_id"
],
"properties": {
"from_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"to_skill_cluster_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "create_skill_change_content",
"type": "object",
"required": [
"skill_id",
"skill_name"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. This should be provided in the default language (`en_uk`)."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. This should be provided in the default language (`en_uk`)."
}
}
},
{
"title": "delete_skill_change_content",
"type": "object",
"required": [
"skill_id"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"title": "update_skill_change_content",
"type": "object",
"required": [
"skill_id"
],
"properties": {
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"nullable": true,
"description": "Name of the Skill. If this is null, the name will be reset to the default one provided by TechWolf."
},
"skill_description": {
"type": "string",
"nullable": true,
"description": "Description of the Skill. If this is null, the description will be reset to the default one provided by TechWolf."
}
}
}
],
"example": {
"subdomain_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"subdomain_name": "Research"
}
}
}
}
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains conflicting changes."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/{entity_type}/custom_properties": {
"parameters": [
{
"in": "path",
"name": "entity_type",
"required": true,
"description": "Custom Properties are supported on the following entity types: [`taxonomy/domains`](/reference/latest/Taxonomy/TaxonomyDomains), [`taxonomy/subdomains`](/reference/latest/Taxonomy/TaxonomySubdomains), [`taxonomy/skill_clusters`](/reference/latest/Taxonomy/TaxonomySkillClusters), [`taxonomy/skills`](/reference/latest/Taxonomy/TaxonomySkills), [`employees`](/reference/latest/Employees), [`organisational_units`](), [`job_architecture/job_families`](), [`job_architecture/jobs`](/reference/latest/Jobs), [`vacancies`](/reference/latest/Vacancies), [`courses`](/reference/latest/Courses), [`skill_clusters`](), and [`companies`]().",
"example": "employees",
"schema": {
"type": "string"
}
}
],
"get": {
"tags": [
"CustomPropertiesDefinitions"
],
"summary": "Get all Custom Property Definitions",
"description": "Get a list of all the Custom Property Definitions stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"description": "Default structure for CustomPropertyDefinition.",
"allOf": [
{
"description": "CustomPropertyDefinition property name.",
"type": "object",
"required": [
"property_name"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`.",
"example": "sector"
}
}
},
{
"description": "CustomPropertyDefinition property type.",
"type": "object",
"required": [
"property_type"
],
"properties": {
"property_type": {
"type": "string",
"minLength": 1,
"maxLength": 10,
"example": "text",
"description": "Expected type of the Custom Property.",
"enum": [
"text",
"number",
"boolean",
"list[text]",
"datetime"
]
}
}
}
]
},
"example": [
{
"property_name": "wage",
"property_type": "number"
},
{
"property_name": "sector",
"property_type": "text"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"post": {
"tags": [
"CustomPropertiesDefinitions"
],
"summary": "Create a Custom Property Definition",
"description": "Create a new Custom Property Definition in the system.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Default structure for CustomPropertyDefinition.",
"allOf": [
{
"description": "CustomPropertyDefinition property name.",
"type": "object",
"required": [
"property_name"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`.",
"example": "sector"
}
}
},
{
"description": "CustomPropertyDefinition property type.",
"type": "object",
"required": [
"property_type"
],
"properties": {
"property_type": {
"type": "string",
"minLength": 1,
"maxLength": 10,
"example": "text",
"description": "Expected type of the Custom Property.",
"enum": [
"text",
"number",
"boolean",
"list[text]",
"datetime"
]
}
}
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of created Custom Property Definition.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/{entity_type}/custom_properties/{property_name}": {
"parameters": [
{
"in": "path",
"name": "entity_type",
"required": true,
"description": "Custom Properties are supported on the following entity types: [`taxonomy/domains`](/reference/latest/Taxonomy/TaxonomyDomains), [`taxonomy/subdomains`](/reference/latest/Taxonomy/TaxonomySubdomains), [`taxonomy/skill_clusters`](/reference/latest/Taxonomy/TaxonomySkillClusters), [`taxonomy/skills`](/reference/latest/Taxonomy/TaxonomySkills), [`employees`](/reference/latest/Employees), [`organisational_units`](), [`job_architecture/job_families`](), [`job_architecture/jobs`](/reference/latest/Jobs), [`vacancies`](/reference/latest/Vacancies), [`courses`](/reference/latest/Courses), [`skill_clusters`](), and [`companies`]().",
"example": "employees",
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "property_name",
"required": true,
"schema": {
"description": "CustomPropertyDefinition property name.",
"type": "object",
"required": [
"property_name"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`.",
"example": "sector"
}
}
}
}
],
"get": {
"tags": [
"CustomPropertiesDefinitions"
],
"summary": "Get Custom Property Definition",
"description": "Get the Custom Property Definition information stored inside the system.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Default structure for CustomPropertyDefinition.",
"allOf": [
{
"description": "CustomPropertyDefinition property name.",
"type": "object",
"required": [
"property_name"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`.",
"example": "sector"
}
}
},
{
"description": "CustomPropertyDefinition property type.",
"type": "object",
"required": [
"property_type"
],
"properties": {
"property_type": {
"type": "string",
"minLength": 1,
"maxLength": 10,
"example": "text",
"description": "Expected type of the Custom Property.",
"enum": [
"text",
"number",
"boolean",
"list[text]",
"datetime"
]
}
}
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"CustomPropertiesDefinitions"
],
"summary": "Rename a Custom Property Definition",
"description": "Rename a Custom Property Definition.",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "CustomPropertyDefinition property name.",
"type": "object",
"required": [
"property_name"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`.",
"example": "sector"
}
}
}
}
}
},
"responses": {
"204": {
"description": "No Content",
"headers": {
"Location": {
"description": "The URI of updated Custom Property Definition.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "409 Conflict",
"description": "The resource already exists."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"CustomPropertiesDefinitions"
],
"summary": "Remove a Custom Property Definition from the system",
"description": "Remove a Custom Property Definition from the system.",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/{entity_type}/{entity_type_external_id}/custom_properties": {
"parameters": [
{
"in": "path",
"name": "entity_type",
"required": true,
"description": "Custom Properties are supported on the following entity types: [`taxonomy/domains`](/reference/latest/Taxonomy/TaxonomyDomains), [`taxonomy/subdomains`](/reference/latest/Taxonomy/TaxonomySubdomains), [`taxonomy/skill_clusters`](/reference/latest/Taxonomy/TaxonomySkillClusters), [`taxonomy/skills`](/reference/latest/Taxonomy/TaxonomySkills), [`employees`](/reference/latest/Employees), [`organisational_units`](), [`job_architecture/job_families`](), [`job_architecture/jobs`](/reference/latest/Jobs), [`vacancies`](/reference/latest/Vacancies), [`courses`](/reference/latest/Courses), [`skill_clusters`](), and [`companies`]().",
"example": "employees",
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "entity_type_external_id",
"required": true,
"description": "Unique external ID linked to this entity, consisting of alphanumeric characters, hyphens and underscores. Note that the endpoint [`taxonomy/skills`](/reference/latest/Taxonomy/TaxonomySkills) uses `skill_id`.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"schema": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
],
"get": {
"tags": [
"CustomPropertiesProperties"
],
"summary": "Retrieve all Custom Properties of an entity",
"description": "Fetch all entity's Custom Properties from the system (if any exists, otherwise an empty list is returned).",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "type",
"property_value": "online"
},
{
"property_name": "years_of_experience",
"property_value": 3
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "tools",
"property_value": [
"JIRA",
"Git"
]
},
{
"property_name": "creation_date",
"property_value": "2023-04-25T17:14:30.40"
}
]
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"CustomPropertiesProperties"
],
"summary": "Update Custom Properties of an entity",
"description": "In addition to the default fields available for each entity, a set of Custom Properties can be added. Each entity is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "type",
"property_value": "online"
},
{
"property_name": "years_of_experience",
"property_value": 3
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "tools",
"property_value": [
"JIRA",
"Git"
]
},
{
"property_name": "creation_date",
"property_value": "2023-04-25T17:14:30.40"
}
]
}
]
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
}
},
"examples": {
"BadJSON": {
"value": {
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
},
"DefintionNotFound": {
"value": {
"title": "400 Bad Request",
"description": "Custom property definition not found. Please create this CustomPropertyDefinition first."
}
},
"BadCustomPropertyType": {
"value": {
"title": "400 Bad Request",
"description": "Custom property has invalid type. Expected type: {type}"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"put": {
"tags": [
"CustomPropertiesProperties"
],
"summary": "Replace Custom Properties of an entity",
"description": "In addition to the default fields available for each entity, a set of Custom Properties can be added. Each entity is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).",
"security": [
{
"application": [
"write"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "type",
"property_value": "online"
},
{
"property_name": "years_of_experience",
"property_value": 3
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "tools",
"property_value": [
"JIRA",
"Git"
]
},
{
"property_name": "creation_date",
"property_value": "2023-04-25T17:14:30.40"
}
]
}
]
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
}
},
"examples": {
"BadJSON": {
"value": {
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
},
"DefintionNotFound": {
"value": {
"title": "400 Bad Request",
"description": "Custom property definition not found. Please create this CustomPropertyDefinition first."
}
},
"BadCustomPropertyType": {
"value": {
"title": "400 Bad Request",
"description": "Custom property has invalid type. Expected type: {type}"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "413 Payload Too Large",
"description": "Request payload is too large."
}
]
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "415 Unsupported Media Type",
"description": "Content-type must be one of: application/json"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "422 Unprocessable entity",
"description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"CustomPropertiesProperties"
],
"summary": "Delete all Custom Properties of an entity",
"description": "Drop all entity's Custom Properties from the system (if any exists).",
"security": [
{
"application": [
"write"
]
}
],
"responses": {
"204": {
"description": "No Content"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/counts": {
"get": {
"tags": [
"General Reports"
],
"summary": "Get entity counts",
"description": "\n\nRetrieve the total number of all entities in the system.\n",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The total number of entities for each type.",
"properties": {
"report_name": {
"type": "string",
"example": "counts"
},
"report_data": {
"type": "object",
"description": "Dictionary with the total number of entities for each type.",
"properties": {
"counts": {
"type": "object",
"example": {
"employees": 1000,
"vacancies": 1000,
"courses": 1000
}
}
}
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/employees/skill_cluster_adoption": {
"post": {
"tags": [
"Employee Reports"
],
"summary": "Get the Skill Cluster adoption report",
"description": "\n\nRetrieve the Skill Cluster adoption report for all Employees with respect to the value of a Custom Property and one\nor more Skill Clusters.\n\nThe report consists of three smaller reports. A heatmap, a Skill Cluster adoption report, and a Skill breakdown.\n\n- The heatmap returns the adoption of each requested Skill Cluster for all Employees which have the same Custom\nProperty.\n- The Skill Cluster adoption gives the proficiency level per requested Skill Cluster for each Employee.\n- The Skill breakdown returns an overview of the Skills of the requested Skill Cluster for each Employee.\n",
"parameters": [
{
"in": "query",
"name": "file_format",
"required": false,
"schema": {
"type": "string",
"enum": [
"json",
"csv"
],
"default": "json"
},
"description": "The output format in which the report will be returned. When `csv` is chosen, a ZIP file is returned containing the three reports in csv format."
},
{
"in": "query",
"name": "force_recalculate",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten."
}
],
"security": [
{
"application": [
"read_reports"
]
}
],
"requestBody": {
"description": "Filters for the Skill Cluster adoption report",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"group_by_custom_property": {
"type": "string",
"description": "Group the output by this property.",
"example": "Department"
},
"relevant_skill_clusters": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "List of Skill Clusters used for the Skill Cluster adoption report.",
"example": [
"Artificial Intelligence",
"Programming Languages"
]
}
},
"required": [
"group_by_custom_property",
"relevant_skill_clusters"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Skill Cluster adoption report for the requested Skill Cluster(s) and Custom Property.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report",
"example": "employee_skill_cluster_adoption"
},
"report_data": {
"type": "object",
"properties": {
"property_name": {
"type": "string",
"example": "Department",
"description": "Name of the requested Custom Property"
},
"heatmap": {
"type": "array",
"items": {
"type": "object",
"properties": {
"property_value": {
"type": "string",
"description": "The value for the requested Custom Property by which Employees are grouped"
},
"skill_clusters": {
"type": "array",
"description": "List of relevant Skill Clusters",
"items": {
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The Skill Cluster for which the adoption was calculated"
},
"adoption": {
"type": "number",
"description": "The adoption of the accompanying Skill Cluster. A number between 0 and 1",
"minimum": 0,
"maximum": 1
}
}
}
}
}
},
"example": [
{
"property_value": "IT & Engineering",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"adoption": 0.6
},
{
"skill_cluster_name": "Programming Languages",
"adoption": 0.2
}
]
},
{
"property_value": "Sales",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"adoption": 0.1
},
{
"skill_cluster_name": "Programming Languages",
"adoption": 0.2
}
]
}
]
},
"skill_cluster_adoption": {
"type": "array",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"property_value": {
"type": "string",
"description": "The value of the group_by_custom_property for this Employee"
},
"assigned_position": {
"type": "string",
"description": "The assigned position of this Employee"
},
"skill_clusters": {
"type": "array",
"description": "List of relevant Skill Clusters",
"items": {
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster"
},
"proficiency_level": {
"type": "number",
"minimum": 0,
"maximum": 3,
"description": "The proficiency level for this Skill Cluster, a level between 0 and 3."
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"property_value": "IT & Engineering",
"assigned_position": "Software Engineer",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"proficiency_level": 2
},
{
"skill_cluster_name": "DevOps",
"proficiency_level": 3
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"property_value": "Research",
"assigned_position": "NLP Engineer",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"proficiency_level": 2
}
]
}
]
},
"skill_breakdown": {
"type": "array",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_clusters": {
"type": "array",
"description": "List of relevant Skill Clusters",
"items": {
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "Name of the Skill Cluster"
},
"skills": {
"type": "array",
"description": "List of Skills within the Skill Cluster for which the confidence levels are high for the given Employee",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the Skill"
}
}
}
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"skills": [
{
"name": "Python"
},
{
"name": "Java"
}
]
},
{
"skill_cluster_name": "Artificial Intelligence",
"skills": [
{
"name": "Machine Learning"
},
{
"name": "Deep Learning"
}
]
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"skills": [
{
"name": "Deep Learning"
}
]
}
]
}
]
}
}
}
}
}
]
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/employees/key_metrics": {
"get": {
"tags": [
"Employee Reports"
],
"summary": "Get Employees key metrics",
"description": "\n\nRetrieve all key metrics of all Employees\n",
"parameters": [
{
"in": "query",
"name": "force_recalculate",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten."
}
],
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "A Report containing the key metrics of all Employees.",
"properties": {
"report_name": {
"type": "string",
"example": "employees_key_metrics"
},
"report_data": {
"type": "object",
"description": "The key metrics of all Employees.",
"properties": {
"total_active": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees."
},
"total_active_with_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees with at least one Skill."
},
"total_active_with_validated_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees with at least one validated Skill."
},
"total_active_with_low_data_availability": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees with low data availability."
},
"validated_skills": {
"type": "object",
"description": "The distribution of validated and rejected Skills among active Employees.",
"properties": {
"total_confirmed_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of confirmed Skills among active Employees."
},
"total_rejected_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of rejected Skills among active Employees."
}
}
}
}
}
},
"example": {
"report_name": "employees_key_metrics",
"report_data": {
"total_active": 100,
"total_active_with_skill": 80,
"total_active_with_validated_skill": 60,
"total_active_with_low_data_availability": 10,
"validated_skills": {
"total_confirmed_skills": 50,
"total_rejected_skills": 10
}
}
}
}
]
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/jobs/key_metrics": {
"get": {
"tags": [
"Job Reports"
],
"summary": "Get Jobs key metrics",
"description": "\n\nRetrieve all key metrics of all Jobs\n",
"parameters": [
{
"in": "query",
"name": "force_recalculate",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten."
}
],
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "A Report containing the key metrics of all Jobs.",
"properties": {
"report_name": {
"type": "string",
"example": "jobs_key_metrics"
},
"report_data": {
"type": "object",
"description": "The key metrics of all Jobs.",
"properties": {
"total_active": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs."
},
"total_active_with_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs with at least one Skill."
},
"total_active_with_validated_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs with at least one validated Skill."
},
"total_active_with_low_data_availability": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs with low data availability."
},
"validated_skills": {
"type": "object",
"description": "The distribution of validated and rejected Skills among active Jobs.",
"properties": {
"total_confirmed_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of confirmed Skills among active Jobs."
},
"total_rejected_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of rejected Skills among active Jobs."
}
}
}
}
}
},
"example": {
"report_name": "jobs_key_metrics",
"report_data": {
"total_active": 100,
"total_active_with_skill": 80,
"total_active_with_validated_skill": 60,
"total_active_with_low_data_availability": 10,
"validated_skills": {
"total_confirmed_skills": 50,
"total_rejected_skills": 10
}
}
}
}
]
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/data_maturity_scan/employee_quality_matrix": {
"post": {
"tags": [
"Data Maturity Scan"
],
"summary": "Get Employee Quality Matrix",
"description": "\n\nGenerate the Employee Quality Matrix for all Employees in the system.\n",
"parameters": [
{
"in": "query",
"name": "force_recalculate",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten."
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"type": "array",
"description": "Optional filters to apply to the report.",
"items": {
"type": "object",
"properties": {
"filter": {
"type": "string",
"enum": [
"external_id_is_in_list"
],
"description": "The type of filter to apply."
},
"external_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of Employee external IDs to include in the report."
}
},
"required": [
"filter",
"external_ids"
]
}
}
}
},
"examples": {
"no_filters": {
"summary": "No filters",
"value": {}
},
"with_filter": {
"summary": "Filter by external IDs",
"value": {
"filters": [
{
"filter": "external_id_is_in_list",
"external_ids": [
"employee_1",
"employee_2"
]
}
]
}
}
}
}
}
},
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Quality Matrix per data source and Skill Event type averaged over all Employees.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "employee_quality_matrix"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Employees uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_quality_matrix": {
"type": "array",
"description": "Data Quality Matrix metrics per data source and Skill Event type averaged over all Employees.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source system of the Skill Event. This is used to keep track of where Skill Events originate from.",
"example": "JIRA"
},
"event_type": {
"description": "Type of the Skill Event. Learn more about the Skill Event Types at [How it works](/technology/skill_events/).",
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"feedback",
"goal",
"project",
"ticket",
"certificate",
"skill_notes"
],
"example": "ticket"
},
"source_type": {
"type": "string",
"description": "The type of information this source adds:\n * ‘job-specific' indicates that the Skills extracted from\nthis source are generic across Employees having the same Job.\n * ‘employee-specific’ indicates that this source\ncontributes to the overall granularity of the Employees’ Skill Profiles.",
"enum": [
"job-specific",
"employee-specific"
],
"example": "employee-specific"
},
"source_coverage": {
"type": "number",
"format": "float",
"description": "The percentage of Employees that have at least one SkillEvent of this data source and type, that is considered coherent (i.e. it makes probabilistic sense for the Skills in the Event's Skill Profile to appear together).",
"example": 0.8
},
"empty_profile": {
"type": "number",
"format": "float",
"description": "The percentage of Skill Events of a data source and type for which no Skills have been found.",
"example": 0.05
},
"source_quality": {
"type": "number",
"format": "float",
"description": "The percentage of Skill Events of a data source and type that are considered coherent (i.e. it makes probabilistic sense for the Skills in the Event's Skill Profile to appear together). For example, it might indicate poor quality when the Skills ‘Recruiting’ and ‘Processing Invoices’ are tagged to the same learning event.",
"example": 0.85
},
"total_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of total Skills per Employee that could be inferred from the data source and type.",
"example": 45
},
"unique_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of unique Skills per Employee that could inferred from the data source and type.",
"example": 24
},
"source_differentation": {
"type": "number",
"format": "float",
"description": "Linked to the average number of Skills unique to the data source. If the model finds all Skills from the source in other sources, it does not add new Skills. Instead, it increases the confidence of Skills extracted from other sources. High differentiation means that almost all Skills from the source are new skills that are not found in the other sources.",
"example": 0.68
}
}
}
}
}
}
}
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/data_maturity_scan/job_quality_matrix": {
"post": {
"tags": [
"Data Maturity Scan"
],
"summary": "Get Job Quality Matrix",
"description": "\n\nGenerate the Job Quality Matrix for all Jobs in the system.\n",
"parameters": [
{
"in": "query",
"name": "force_recalculate",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten."
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"type": "array",
"description": "Optional filters to apply to the report.",
"items": {
"type": "object",
"properties": {
"filter": {
"type": "string",
"enum": [
"external_id_is_in_list"
],
"description": "The type of filter to apply."
},
"external_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of Job external IDs to include in the report."
}
},
"required": [
"filter",
"external_ids"
]
}
}
}
},
"examples": {
"no_filters": {
"summary": "No filters",
"value": {}
},
"with_filter": {
"summary": "Filter by external IDs",
"value": {
"filters": [
{
"filter": "external_id_is_in_list",
"external_ids": [
"job_1",
"job_2"
]
}
]
}
}
}
}
}
},
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Quality Matrix, per data source and Job Profile Data type, averaged over all Jobs.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "job_quality_matrix"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Jobs uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_quality_matrix": {
"type": "array",
"description": "Data Quality Matrix metrics, per data source and Job Profile Data type, averaged over all Jobs.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source system of the Job Profile Data. This is used to keep track of where Job Profile Data originate from.",
"example": "Workday"
},
"event_type": {
"description": "Type of the Job Profile Data.",
"type": "string",
"enum": [
"job_description",
"job_title",
"vacancy",
"skill_notes"
],
"example": "job_title"
},
"source_type": {
"type": "string",
"description": "The type of information this source adds:\n * ‘market-specific' indicates that the Skills extracted\nfrom this source are based on external market data only available for this Job.",
"enum": [
"market-specific"
],
"example": "market-specific"
},
"source_coverage": {
"type": "number",
"format": "float",
"description": "The percentage of Jobs that have at least one Job Data item of this data source and type, that is considered coherent (i.e. it makes probabilistic sense for the Skills in the Job Data item's Skill Profile to appear together).",
"example": 0.8
},
"empty_profile": {
"type": "number",
"format": "float",
"description": "The percentage of Job Profile Data of a data source and type for which no Skills have been found.",
"example": 0.05
},
"source_quality": {
"type": "number",
"format": "float",
"description": "The percentage of Job Profile Data of a data source and type that are considered coherent (i.e. it makes probabilistic sense for the Skills in the Job Data item's Skill Profile to appear together). For example, it might indicate poor quality when the Skills ‘recruiting’ and ‘processing invoices’ are tagged to the same learning event.",
"example": 0.85
},
"total_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of total Skills per Job that were inferred from the data source and type.",
"example": 45
},
"unique_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of unique Skills per Job that were inferred from the data source and type.",
"example": 24
},
"source_differentation": {
"type": "number",
"format": "float",
"description": "Linked to the average number of Skills unique to the data source. If the model finds all Skills from the data source in other sources, it does not add new skills. Instead, it increases the confidence of skills extracted from other sources. High differentiation means that almost all skills from the source are new skills that are not found in the other sources.",
"example": 0.68
}
}
}
}
}
}
}
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/data_maturity_scan/employee_maturity_overview": {
"get": {
"tags": [
"Data Maturity Scan"
],
"summary": "Get Employee Maturity Overview",
"description": "\n\nGenerate the Employee Maturity Overview for all Employees in the system.\n",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"example": 250,
"default": 200
},
"description": "The maximal number of returned entities."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "include",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"valid_assigned_position",
"has_business_data",
"sufficient_working_history"
]
}
},
"style": "form",
"explode": true,
"description": "Additional metrics to include in the response. By default, only the `external_id`, `low_data_availability`, and `reasons` fields are returned.\nAvailable metrics:\n * `valid_assigned_position` - Whether the Employee has a valid assigned position (existing Job).\n * `has_business_data` - Whether the Employee has business data (Ticket or Project Skill Events).\n * `sufficient_working_history` - Whether the Employee has at least 3 years of working history.\n"
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
}
],
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Maturity Overview over all Employees.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "employee_maturity_overview"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Employees uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_maturity_overview": {
"type": "array",
"description": "Data Maturity Overview flags for every Employee if sufficient data is available for qualitative Skill inference. Reasons are listed whenever not enough data is available.",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"reasons": {
"type": "array",
"description": "The data issues will result in insufficient data available:\n * `MIN_PROFILE_LENGTH` = less than 10 Skills are found in the final Skill Profile.\n * `MIN_SKILL_VOLUME_EVENTS` = less than 20 Skills are found across all available Skill Event sources.\n * `MAX_SKILL_GENERALITY` = more than 40% of all available Skill Event Skills are considered `generic`, occurring in the final Skill Profile of 25% of all other Jobs.\n * `MAX_SOURCE_GENERALITY` = more than 50% of the Skill Event sources are considered `generic`, mostly based on market data.\n * `MIN_EVENT_TYPE_DIVERSITY` = less than 3 unique Skill Event sources are available.",
"items": {
"type": "string",
"enum": [
"MIN_PROFILE_LENGTH",
"MIN_SKILL_VOLUME_EVENTS",
"MAX_SKILL_GENERALITY",
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
],
"example": [
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
]
}
},
"valid_assigned_position": {
"type": "boolean",
"description": "Whether the Employee has a valid assigned position (an existing Job). Only returned if `valid_assigned_position` is included in the request.",
"example": true
},
"has_business_data": {
"type": "boolean",
"description": "Whether the Employee has business data (Ticket or Project Skill Events). Only returned if `has_business_data` is included in the request.",
"example": true
},
"sufficient_working_history": {
"type": "boolean",
"description": "Whether the Employee has at least 3 years of working history with start and end dates filled in. Only returned if `sufficient_working_history` is included in the request.",
"example": false
}
}
}
}
}
}
}
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/data_maturity_scan/job_maturity_overview": {
"get": {
"tags": [
"Data Maturity Scan"
],
"summary": "Get Job Maturity Overview",
"description": "\n\nGenerate the Job Maturity Overview for all Jobs in the system.\n",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"example": 250,
"default": 200
},
"description": "The maximal number of returned entities."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"description": "The applied offset for returned entities, results starting from `offset` up to `offset + limit`."
},
{
"in": "query",
"name": "include",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"job_data_count",
"data_distribution"
]
}
},
"style": "form",
"explode": true,
"description": "Additional metrics to include in the response. By default, only the `external_id`, `low_data_availability`, and `reasons` fields are returned.\nAvailable metrics:\n * `job_data_count` - Returns a count of Job Profile Data entries by type.\n * `data_distribution` - Returns the distribution of Skills by data source (market_only, market_aligned, internal_only).\n"
},
{
"in": "query",
"name": "is_active",
"schema": {
"type": "boolean",
"example": true,
"default": "None"
},
"description": "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."
}
],
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Maturity Overview across all Jobs.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "job_maturity_overview"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Jobs uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_maturity_overview": {
"type": "array",
"description": "Data Maturity Overview flags for every Job if sufficient data is available for qualitative Skill inference. Reasons are listed whenever not enough data is available.",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"reasons": {
"type": "array",
"description": "The data issues will result in insufficient data available:\n * `MIN_PROFILE_LENGTH` = less than 10 Skills are found in the final profile.\n * `MIN_SKILL_VOLUME_EVENTS` = less than 20 Skills are found across all available Job Profile Data sources.\n * `MAX_SKILL_GENERALITY` = more than 40% of all available Job Profile Data Skills are considered `generic`, occurring in the final profile of 25% of all other Jobs.\n * `MAX_SOURCE_GENERALITY` = more than 50% of the Job Profile Data sources are considered `generic`, mostly based on market data.\n * `MIN_EVENT_TYPE_DIVERSITY` = less than 3 unique Job Profile Data sources are available.",
"items": {
"type": "string",
"enum": [
"MIN_PROFILE_LENGTH",
"MIN_SKILL_VOLUME_EVENTS",
"MAX_SKILL_GENERALITY",
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
],
"example": [
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
]
}
},
"job_data_count": {
"type": "object",
"description": "Count of Job Profile Data entries by type. Only returned if `job_data_count` is included in the request.",
"additionalProperties": {
"type": "integer"
},
"example": {
"Job Title": 1,
"Job Description": 2,
"Vacancy": 0
}
},
"data_distribution": {
"type": "object",
"description": "Distribution of Skills by data source origin. Only returned if `data_distribution` is included in the request.\n * `market_only` = Skills that only come from the Job title.\n * `market_aligned` = Skills that come from the Job title and at least one other data type.\n * `internal_only` = Skills that only come from internal data types (not Job title).",
"properties": {
"market_only": {
"type": "integer",
"description": "Number of Skills that only come from the Job title."
},
"market_aligned": {
"type": "integer",
"description": "Number of Skills that come from the Job title and at least one other data type."
},
"internal_only": {
"type": "integer",
"description": "Number of Skills that only come from internal data types."
}
},
"example": {
"market_only": 5,
"market_aligned": 10,
"internal_only": 8
}
}
}
}
}
}
}
}
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/reports/data_maturity_scan/data_improvement_actions": {
"get": {
"tags": [
"Data Maturity Scan"
],
"summary": "Get Data Improvement Actions",
"description": "\n\nGenerate Data Improvement Actions for all Entities, Skill Events and Job Profile Data in the system.\n",
"parameters": [
{
"in": "query",
"name": "force_recalculate",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Reports are always stored for a certain time, and if this endpoint is called again within that time, the stored report is returned without recalculating. If `force_recalculate` is set to `true`, the report is recalculated and the stored report is overwritten."
},
{
"in": "query",
"name": "active_only",
"schema": {
"type": "boolean",
"example": true,
"default": false
},
"description": "When set to `true`, only active Employees and Jobs are included in the Data Improvement Actions. When set to `false` (default), all Employees and Jobs are included regardless of their active status."
}
],
"security": [
{
"application": [
"read_reports"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "An overview of suggested Data Improvement Actions over all Employees and Jobs.",
"properties": {
"report_name": {
"type": "string",
"example": "data_improvement_actions"
},
"report_data": {
"type": "object",
"properties": {
"data_improvement_actions": {
"type": "array",
"description": "A Data Improvement Action is an observed data issue for specific fields of Entities, Skill Events or Job Profile Data with an assessed impact of resolving the data issue.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source system of the Skill Event or Job Profile Data. This is used to keep track of where Skill Events or Job Profile Data originate from.",
"example": "JIRA"
},
"event_type": {
"description": "Type of the Skill Event or Job Profile Data.",
"type": "string"
},
"content_field": {
"type": "string",
"description": "The data field of the Skill Event or Job Profile Data in which the data issue occurs.",
"example": "ticket_description"
},
"observation": {
"type": "string",
"description": "Description of the data issue.",
"example": "Half of descriptions are too short (less than 300 characters)"
},
"impact": {
"type": "string",
"description": "Prioritisation suggestion on tackling the data issue.",
"enum": [
"High",
"Medium",
"Low"
],
"example": "High"
},
"count": {
"type": "integer",
"description": "The number of occurrences of this data issue.",
"example": 150
},
"examples": {
"oneOf": [
{
"title": "General Examples",
"description": "Example IDs of Skill Events or Job Profile Data where the observation is applicable.",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 5
},
{
"title": "Duplicate Data Examples",
"type": "object",
"required": [
"entity_count",
"example_ids"
],
"properties": {
"title": {
"type": "string",
"description": "Title of the duplicate example entities"
},
"description": {
"type": "string",
"description": "Description of the duplicate example entities"
},
"entity_count": {
"type": "integer",
"description": "Total number of duplicate example entities with this title and description"
},
"example_ids": {
"type": "array",
"description": "IDs of the duplicate example entities",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 20
}
},
"maxItems": 5
},
{
"title": "Working History Date Examples",
"description": "Example Employees with Working History Skill Events that have date issues (missing start date, missing end date, or identical start and end dates).",
"type": "array",
"items": {
"type": "object",
"required": [
"employee_id",
"event_ids"
],
"properties": {
"employee_id": {
"type": "string",
"description": "The external ID of the Employee with problematic Working History Skill Events.",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"event_ids": {
"type": "array",
"description": "IDs of the Working History Skill Events with date issues for this Employee.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 5
}
}
},
"maxItems": 5
}
]
}
}
}
}
}
}
}
}
]
}
}
}
},
"202": {
"description": "Accepted: calculation started or in progress. Polling this endpoint again with a 200 response results in the data."
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/matching_vacancies": {
"post": {
"tags": [
"Export Matching"
],
"summary": "Export top matching Vacancies for Employees.",
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "The maximum number of entities to calculate matches for",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"example": 10,
"default": 10,
"description": "The maximum number of entities to calculate matches for. This controls how many source entities will be processed for matching calculations."
}
}
},
{
"type": "object",
"description": "The maximum number of matches to return per entity",
"properties": {
"match_limit_per_entity": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10,
"description": "The maximum number of matches to return per entity. This controls how many of the best matching results are returned for each source entity."
}
}
},
{
"type": "object",
"description": "The minimum threshold score to apply to match results",
"properties": {
"score_min_threshold": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5,
"description": "The minimum threshold score to apply to match results. All matches with scores below this threshold will not be returned. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum."
}
}
},
{
"type": "object",
"description": "Pagination parameter for cursor-based pagination",
"properties": {
"starting_after": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The UUID of the entity to start pagination after. This is used for cursor-based pagination to retrieve the next page of results. Leave empty or null to start from the beginning.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
},
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"filter",
"multi_max_geo_distances"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distances`. This filter cannot be used together with the `max_geo_distance` filter",
"enum": [
"multi_max_geo_distances"
],
"example": "multi_max_geo_distances"
},
"multi_max_geo_distances": {
"type": "array",
"description": "List of locations and maximum distances. The list must contain at least one item and at most three.",
"items": {
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"max_geo_distance",
"location"
],
"properties": {
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
}
}
},
{
"type": "object",
"title": "language",
"required": [
"filter",
"max_overqualification",
"max_underqualification"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all Employees for which the language level is not within the range defined by `level - max_underqualification` and `level + max_overqualification`, with `level` being the language level of Vacancies. If `level - max_underqualification <= 0`, the filter does not filter any entity without the language.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be above the required level of the Vacancy.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be below the required level of the Vacancy. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "multi_max_geo_distances",
"multi_max_geo_distances": [
{
"max_geo_distance": 20,
"location": {
"lat": 51.34,
"lng": 3.15
}
},
{
"max_geo_distance": 20,
"location": {
"country": "BE",
"postal_code": 9000
}
}
]
},
{
"filter": "language",
"max_overqualification": 2,
"max_underqualification": 1
},
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"description": "List of weights to be applied during matching",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"value": 0.1,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"value": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"value": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"value": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"value": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"value": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"value": 0.04,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"matches"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"matches": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"vacancy_id",
"score"
],
"properties": {
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "vacancy_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"matches"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"matches": {
"type": "array",
"description": "List of Vacancy match results for this Employee with Skill coverage breakdown.",
"items": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"vacancy_id",
"score"
],
"properties": {
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "vacancy_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "Detailed breakdown of the match score on Skill level.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"employee_id": "employee_1_id",
"matches": [
{
"vacancy_id": "vacancy_1_id",
"score": 0.87657
},
{
"vacancy_id": "vacancy_2_id",
"score": 0.82341
}
]
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"employee_id": "employee_1_id",
"matches": [
{
"vacancy_id": "vacancy_1_id",
"score": 0.87657,
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
},
{
"skill_name": "Data Analysis",
"skill_id": "d221427b-52e4-57f2-bf48-c2gcc4c4d79d",
"adjacent_skill_name": "Data Analysis",
"adjacent_skill_id": "6f55478c-63f5-68g3-c382-d4icc5c5e81f",
"adjacency_score": 1
}
],
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill_name": "Docker",
"skill_id": "5c96570e-783a-4e81-9987-b1fbb3b3c74c"
}
]
},
{
"vacancy_id": "vacancy_2_id",
"score": 0.7,
"present_skills": [
{
"skill_name": "JavaScript",
"skill_id": "f332538d-904c-60a4-d160-e4iee6e6f91f",
"adjacent_skill_name": "TypeScript",
"adjacent_skill_id": "7f443649-a15d-71b5-e271-f5jff7f7g02g",
"adjacency_score": 0.9
}
],
"missing_skills": [
{
"skill_name": "React",
"skill_id": "6e37258c-893b-5f93-c059-d3hdd5d5e80e"
}
]
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/vacancies/matching_employees": {
"post": {
"tags": [
"Export Matching"
],
"summary": "Export top matching Employees for Vacancies.",
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "The maximum number of entities to calculate matches for",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"example": 10,
"default": 10,
"description": "The maximum number of entities to calculate matches for. This controls how many source entities will be processed for matching calculations."
}
}
},
{
"type": "object",
"description": "The maximum number of matches to return per entity",
"properties": {
"match_limit_per_entity": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10,
"description": "The maximum number of matches to return per entity. This controls how many of the best matching results are returned for each source entity."
}
}
},
{
"type": "object",
"description": "The minimum threshold score to apply to match results",
"properties": {
"score_min_threshold": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5,
"description": "The minimum threshold score to apply to match results. All matches with scores below this threshold will not be returned. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum."
}
}
},
{
"type": "object",
"description": "Pagination parameter for cursor-based pagination",
"properties": {
"starting_after": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The UUID of the entity to start pagination after. This is used for cursor-based pagination to retrieve the next page of results. Leave empty or null to start from the beginning.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
},
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
},
{
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"filter",
"multi_max_geo_distances"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distances`. This filter cannot be used together with the `max_geo_distance` filter",
"enum": [
"multi_max_geo_distances"
],
"example": "multi_max_geo_distances"
},
"multi_max_geo_distances": {
"type": "array",
"description": "List of locations and maximum distances. The list must contain at least one item and at most three.",
"items": {
"type": "object",
"title": "multi_max_geo_distances",
"required": [
"max_geo_distance",
"location"
],
"properties": {
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
},
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
}
}
},
{
"type": "object",
"title": "language",
"required": [
"filter",
"max_overqualification",
"max_underqualification"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all Employees for which the language level is not within the range defined by `level - max_underqualification` and `level + max_overqualification`, with `level` being the language level of Vacancies. If `level - max_underqualification <= 0`, the filter does not filter any entity without the language.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be above the required level of the Vacancy.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the Employee may be below the required level of the Vacancy. If `level - max_underqualification <= 0` the filter does not filter any entity without the language.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "exclude_match_feedback",
"required": [
"filter",
"exclude_match_feedback"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out matches with a certain match feedback.",
"enum": [
"exclude_match_feedback"
],
"example": "exclude_match_feedback"
},
"exclude_match_feedback": {
"type": "string",
"description": "Matches with this match feedback will be excluded.",
"enum": [
"thumbs_up",
"thumbs_down"
],
"example": "thumbs_up"
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "max_geo_distance",
"max_geo_distance": 50
},
{
"filter": "multi_max_geo_distances",
"multi_max_geo_distances": [
{
"max_geo_distance": 20,
"location": {
"lat": 51.34,
"lng": 3.15
}
},
{
"max_geo_distance": 20,
"location": {
"country": "BE",
"postal_code": 9000
}
}
]
},
{
"filter": "language",
"max_overqualification": 2,
"max_underqualification": 1
},
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"description": "List of weights to be applied during matching",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
},
{
"weight": "geo_distance",
"value": 0.1,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"value": 0.1,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"value": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"value": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"value": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"value": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"value": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"value": 0.04,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"vacancy_id",
"matches"
],
"properties": {
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "vacancy_1_id"
},
"matches": {
"type": "array",
"description": "List of Employee match results for this Vacancy.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Explained",
"type": "object",
"required": [
"vacancy_id",
"matches"
],
"properties": {
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "vacancy_1_id"
},
"matches": {
"type": "array",
"description": "List of Employee match results for this Vacancy with Skill coverage breakdown.",
"items": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"vacancy_id": "vacancy_1_id",
"matches": [
{
"employee_id": "employee_1_id",
"score": 0.87657
},
{
"employee_id": "employee_2_id",
"score": 0.82341
}
]
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"vacancy_id": "vacancy_1_id",
"matches": [
{
"employee_id": "employee_1_id",
"score": 0.87657,
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
},
{
"skill_name": "Data Analysis",
"skill_id": "d221427b-52e4-57f2-bf48-c2gcc4c4d79d",
"adjacent_skill_name": "Data Analysis",
"adjacent_skill_id": "6f55478c-63f5-68g3-c382-d4icc5c5e81f",
"adjacency_score": 1
}
],
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill_name": "Docker",
"skill_id": "5c96570e-783a-4e81-9987-b1fbb3b3c74c"
}
]
},
{
"employee_id": "employee_2_id",
"score": 0.7,
"present_skills": [
{
"skill_name": "JavaScript",
"skill_id": "f332538d-904c-60a4-d160-e4iee6e6f91f",
"adjacent_skill_name": "TypeScript",
"adjacent_skill_id": "7f443649-a15d-71b5-e271-f5jff7f7g02g",
"adjacency_score": 0.9
}
],
"missing_skills": [
{
"skill_name": "React",
"skill_id": "6e37258c-893b-5f93-c059-d3hdd5d5e80e"
}
]
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/export/employees/matching_jobs": {
"post": {
"tags": [
"Export Matching"
],
"summary": "Export top matching Jobs for Employees.",
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "The maximum number of entities to calculate matches for",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"example": 10,
"default": 10,
"description": "The maximum number of entities to calculate matches for. This controls how many source entities will be processed for matching calculations."
}
}
},
{
"type": "object",
"description": "The maximum number of matches to return per entity",
"properties": {
"match_limit_per_entity": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10,
"description": "The maximum number of matches to return per entity. This controls how many of the best matching results are returned for each source entity."
}
}
},
{
"type": "object",
"description": "The minimum threshold score to apply to match results",
"properties": {
"score_min_threshold": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5,
"description": "The minimum threshold score to apply to match results. All matches with scores below this threshold will not be returned. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum."
}
}
},
{
"type": "object",
"description": "Pagination parameter for cursor-based pagination",
"properties": {
"starting_after": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The UUID of the entity to start pagination after. This is used for cursor-based pagination to retrieve the next page of results. Leave empty or null to start from the beginning.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
},
{
"type": "object",
"description": "Filter to include overqualified matches",
"properties": {
"include_overqualified": {
"type": "boolean",
"example": true,
"default": true,
"description": "When set to true, includes matches where the Employee is overqualified for the Job. Overqualified matches are those where the Employee's skill level significantly exceeds the requirements. This filter will only work if matching with skill properties is enabled on the tenant."
}
}
},
{
"type": "object",
"description": "Filter for critical skills match ratio threshold",
"properties": {
"min_critical_skills_match_ratio": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"nullable": true,
"example": 0.8,
"default": null,
"description": "The minimum ratio of critical skills that must be matched. Only matches meeting or exceeding this ratio will be returned. When not provided, no critical skills ratio filtering is applied. This filter will only work if the \"use_criticalities\" feature flag is enabled."
}
}
},
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesSimple` and `PropertiesExplained` schemas for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"matches"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"matches": {
"type": "array",
"description": "List of Job match results for this Employee.",
"items": {
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Explained",
"type": "object",
"required": [
"employee_id",
"matches"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"matches": {
"type": "array",
"description": "List of Job match results for this Employee with Skill coverage breakdown.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}
},
{
"title": "PropertiesSimple",
"description": "Match results with skill properties in simple format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "PropertiesSimple",
"type": "object",
"required": [
"employee_id",
"matches"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "E-123"
},
"matches": {
"type": "array",
"description": "List of Job match results for this Employee.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
}
}
}
}
}
}
},
{
"title": "PropertiesExplained",
"description": "Match results with skill properties in explained format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "PropertiesExplained",
"type": "object",
"required": [
"employee_id",
"matches"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "E-123"
},
"matches": {
"type": "array",
"description": "List of Job match results for this Employee with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"present_skills": {
"description": "A list of Skills that the Employee covers, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses, with detailed skill information including required proficiency level, criticality and gap impact.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"employee_id": "employee_1_id",
"matches": [
{
"job_id": "job_1_id",
"score": 0.87657
},
{
"job_id": "job_2_id",
"score": 0.82341
}
]
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"employee_id": "employee_1_id",
"matches": [
{
"job_id": "job_1_id",
"score": 0.87657,
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
},
{
"skill_name": "Data Analysis",
"skill_id": "d221427b-52e4-57f2-bf48-c2gcc4c4d79d",
"adjacent_skill_name": "Data Analysis",
"adjacent_skill_id": "6f55478c-63f5-68g3-c382-d4icc5c5e81f",
"adjacency_score": 1
}
],
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill_name": "Docker",
"skill_id": "5c96570e-783a-4e81-9987-b1fbb3b3c74c"
}
]
},
{
"job_id": "job_2_id",
"score": 0.7,
"present_skills": [
{
"skill_name": "JavaScript",
"skill_id": "f332538d-904c-60a4-d160-e4iee6e6f91f",
"adjacent_skill_name": "TypeScript",
"adjacent_skill_id": "7f443649-a15d-71b5-e271-f5jff7f7g02g",
"adjacency_score": 0.9
}
],
"missing_skills": [
{
"skill_name": "React",
"skill_id": "6e37258c-893b-5f93-c059-d3hdd5d5e80e"
}
]
}
]
}
]
}
},
"propertiesSimpleExample": {
"summary": "Matching with properties simple example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"employee_id": "E-123",
"matches": [
{
"job_id": "J-456",
"score": 0.58,
"overqualified": false
},
{
"job_id": "J-789",
"score": 0.72,
"overqualified": false
}
]
},
{
"employee_id": "E-456",
"matches": [
{
"job_id": "J-456",
"score": 0.65,
"overqualified": true
}
]
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"employee_id": "E-123",
"matches": [
{
"job_id": "J-456",
"score": 0.58,
"overqualified": false,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/job_architecture/export/jobs/matching_employees": {
"post": {
"tags": [
"Export Matching"
],
"summary": "Export top matching Employees for Jobs.",
"parameters": [
{
"in": "query",
"name": "response_format",
"schema": {
"type": "string",
"default": "simple",
"enum": [
"simple",
"explained"
],
"example": "explained"
},
"description": "If set to `explained`, the response will include an explanation of the match."
},
{
"in": "query",
"name": "external_vendor",
"required": false,
"description": "The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.",
"schema": {
"type": "string",
"default": "techwolf",
"example": "workday",
"enum": [
"techwolf",
"workday",
"sap_attribute_library"
]
}
},
{
"in": "query",
"name": "vocab_language",
"required": false,
"description": "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`. IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`) are also accepted and mapped to their internal equivalents.\n\n**Vendor-specific availability:** Only the following languages are available for the default TechWolf vocabulary: `en`, `en_uk`, `en_us`, `de`, `fr`, `nl`. The additional languages (`es`, `fr_ca`, `it`, `ja`, `ko`, `pt_br`, `zh_cn`, `zh_tw`, `sv`, `fi`, `da`, `no`) are only available when the request is scoped to the `workday` vendor (via `external_vendor=workday`) and the tenant's Workday vocabulary includes them. Use `GET /taxonomy/skills/languages` to discover the exact set of languages available for a given vendor in your tenant.",
"example": "en_uk",
"schema": {
"type": "string",
"default": "en_uk",
"enum": [
"en",
"en_uk",
"en_us",
"de",
"fr",
"nl",
"es",
"fr_ca",
"it",
"ja",
"ko",
"pt_br",
"zh_cn",
"zh_tw",
"sv",
"fi",
"da",
"no"
]
}
}
],
"security": [
{
"application": [
"read"
]
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "The maximum number of entities to calculate matches for",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"example": 10,
"default": 10,
"description": "The maximum number of entities to calculate matches for. This controls how many source entities will be processed for matching calculations."
}
}
},
{
"type": "object",
"description": "The maximum number of matches to return per entity",
"properties": {
"match_limit_per_entity": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 10,
"default": 10,
"description": "The maximum number of matches to return per entity. This controls how many of the best matching results are returned for each source entity."
}
}
},
{
"type": "object",
"description": "The minimum threshold score to apply to match results",
"properties": {
"score_min_threshold": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.7,
"default": 0.5,
"description": "The minimum threshold score to apply to match results. All matches with scores below this threshold will not be returned. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum."
}
}
},
{
"type": "object",
"description": "Pagination parameter for cursor-based pagination",
"properties": {
"starting_after": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The UUID of the entity to start pagination after. This is used for cursor-based pagination to retrieve the next page of results. Leave empty or null to start from the beginning.",
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
}
}
},
{
"type": "object",
"description": "Filter to include overqualified matches",
"properties": {
"include_overqualified": {
"type": "boolean",
"example": true,
"default": true,
"description": "When set to true, includes matches where the Employee is overqualified for the Job. Overqualified matches are those where the Employee's skill level significantly exceeds the requirements. This filter will only work if matching with skill properties is enabled on the tenant."
}
}
},
{
"type": "object",
"description": "Filter for critical skills match ratio threshold",
"properties": {
"min_critical_skills_match_ratio": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"nullable": true,
"example": 0.8,
"default": null,
"description": "The minimum ratio of critical skills that must be matched. Only matches meeting or exceeding this ratio will be returned. When not provided, no critical skills ratio filtering is applied. This filter will only work if the \"use_criticalities\" feature flag is enabled."
}
}
},
{
"type": "object",
"description": "List of filters to be applied on the entities before matching",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "last_updated",
"required": [
"filter",
"value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter the target entities (the ones being matched against the source entity) on their `last_updated` value using the operator below. The default operator is `gte`.",
"enum": [
"last_updated"
],
"example": "last_updated"
},
"value": {
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
"operator": {
"type": "string",
"description": "The operator used for filtering entities based on the `last_updated` value. Operator `lt` returns entities with a `last_updated` date < (before) the given `value`. Operator `lte` returns entities with `last_updated` <= the given `value`. Operator `gte` returns entities with `last_updated` >= the given `value`. Operator `gt` returns entities with `last_updated` > (after) the given `value`.",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"default": "gte",
"example": "lt"
}
}
},
{
"type": "object",
"title": "custom_property_equal",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out the entities for which the Custom Property value is not equal to the Custom Property of the entity for which you're calculating matches. The Custom Property names can be configured independently on both sides.",
"enum": [
"custom_property_equal"
],
"example": "custom_property_equal"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. List properties are not supported. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filters out the entities for which the `list[text]` Custom Property does not contain the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no filtering is applied.",
"example": "desired_wage"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "wage"
}
}
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"filter",
"property_name",
"possible_values"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a Custom Property is not in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering.",
"example": "drivers_licence"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. All entities with a value for the specified Custom Property that is not in this list are filtered out.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the value of their `text` Custom Property is not in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property.",
"example": "shift_regime_codes"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the Custom Property of the entities that are possible match results. Must be a `text` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "desired_regime"
}
}
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"filter",
"property_name",
"property_value"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which a given value is not present in the values of list[text] Custom Property.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. Should be a `list[text]` Custom Property. If the entity does not have this property, it is not included in the result.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values of which at least one should be present in the values list of the Custom Property."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"filter",
"from_entity_property",
"to_entity_property"
],
"properties": {
"filter": {
"type": "string",
"description": "Only allow matches where the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no filtering is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. Matches are also excluded when they do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"title": "external_id_is_in_list",
"required": [
"filter",
"external_ids"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the `external_id` is not in the passed list.",
"enum": [
"external_id_is_in_list"
],
"example": "external_id_is_in_list"
},
"external_ids": {
"type": "array",
"description": "List of `external_id`s of entities.",
"maxItems": 200,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
}
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
},
"example": [
{
"filter": "last_updated",
"value": "2022-01-01",
"operator": "lt"
},
{
"filter": "custom_property_equal",
"from_entity_property": "desired_wage",
"to_entity_property": "wage"
},
{
"filter": "custom_property",
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"filter": "custom_property_is_in",
"from_entity_property": "required_drivers_license",
"to_entity_property": "drivers_licenses"
},
{
"filter": "custom_property_is_in_list",
"property_name": "drivers_license",
"possible_values": [
"C",
"CE"
]
},
{
"filter": "custom_property_contains",
"from_entity_property": "shift_regime_codes",
"to_entity_property": "desired_regime"
},
{
"filter": "custom_property_list_overlap",
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
},
{
"filter": "custom_property_contains_element",
"property_name": "industries",
"property_value": "electronics"
},
{
"filter": "external_id_is_in_list",
"external_ids": [
"c350500-eb84-42dc-a79f-5e7b1fe897b7",
"b450500-eb84-42dc-a79f-5e7b1fe897c8"
]
},
{
"filter": "low_data_availability",
"exclude_low_data_availability": true
}
]
}
}
},
{
"type": "object",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"description": "List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
}
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK\nNote: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the `PropertiesSimple` and `PropertiesExplained` schemas for details on which fields are included.",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"title": "Simple",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"job_id",
"matches"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"matches": {
"type": "array",
"description": "List of Employee match results for this Job.",
"items": {
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
}
}
}
}
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "Explained",
"type": "object",
"required": [
"job_id",
"matches"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"matches": {
"type": "array",
"description": "List of Employee match results for this Job with Skill coverage breakdown.",
"items": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}
},
{
"title": "PropertiesSimple",
"description": "Match results with skill properties in simple format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "PropertiesSimple",
"type": "object",
"required": [
"job_id",
"matches"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "J-456"
},
"matches": {
"type": "array",
"description": "List of Employee match results for this Job.",
"items": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
}
}
}
}
}
}
},
{
"title": "PropertiesExplained",
"description": "Match results with skill properties in explained format. This format is only available if matching with skill properties is enabled on the tenant.",
"type": "object",
"required": [
"records"
],
"properties": {
"has_next": {
"description": "True when there is more data after this page.",
"type": "boolean",
"example": true
},
"next_starting_after": {
"description": "The next `starting_after` value for pagination.",
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
]
},
"records": {
"type": "array",
"description": "List of match results.",
"items": {
"title": "PropertiesExplained",
"type": "object",
"required": [
"job_id",
"matches"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "J-456"
},
"matches": {
"type": "array",
"description": "List of Employee match results for this Job with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"present_skills": {
"description": "A list of Skills that the Employee covers, with detailed skill information including required proficiency level, criticality and gap impact.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses, with detailed skill information including required proficiency level, criticality and gap impact.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
}
}
}
}
}
}
]
},
"examples": {
"simpleExample": {
"summary": "Simple Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"job_id": "job_1_id",
"matches": [
{
"employee_id": "employee_1_id",
"score": 0.87657
},
{
"employee_id": "employee_2_id",
"score": 0.82341
}
]
}
]
}
},
"explainedExample": {
"summary": "Explained Example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"job_id": "job_1_id",
"matches": [
{
"employee_id": "employee_1_id",
"score": 0.87657,
"present_skills": [
{
"skill_name": "Machine Learning",
"skill_id": "c110316a-41d3-46ef-a35e-dbb27785b1c8",
"adjacent_skill_name": "Artificial Intelligence",
"adjacent_skill_id": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"adjacency_score": 0.8
},
{
"skill_name": "Data Analysis",
"skill_id": "d221427b-52e4-57f2-bf48-c2gcc4c4d79d",
"adjacent_skill_name": "Data Analysis",
"adjacent_skill_id": "6f55478c-63f5-68g3-c382-d4icc5c5e81f",
"adjacency_score": 1
}
],
"missing_skills": [
{
"skill_name": "Python",
"skill_id": "4b85469d-6729-4d70-9876-a0faa2a2f63b"
},
{
"skill_name": "Docker",
"skill_id": "5c96570e-783a-4e81-9987-b1fbb3b3c74c"
}
]
},
{
"employee_id": "employee_2_id",
"score": 0.7,
"present_skills": [
{
"skill_name": "JavaScript",
"skill_id": "f332538d-904c-60a4-d160-e4iee6e6f91f",
"adjacent_skill_name": "TypeScript",
"adjacent_skill_id": "7f443649-a15d-71b5-e271-f5jff7f7g02g",
"adjacency_score": 0.9
}
],
"missing_skills": [
{
"skill_name": "React",
"skill_id": "6e37258c-893b-5f93-c059-d3hdd5d5e80e"
}
]
}
]
}
]
}
},
"propertiesSimpleExample": {
"summary": "Matching with properties simple example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"job_id": "J-456",
"matches": [
{
"employee_id": "E-123",
"score": 0.58,
"overqualified": false
},
{
"employee_id": "E-789",
"score": 0.72,
"overqualified": false
}
]
},
{
"job_id": "J-789",
"matches": [
{
"employee_id": "E-123",
"score": 0.65,
"overqualified": true
}
]
}
]
}
},
"propertiesExplainedExample": {
"summary": "Matching with properties explained example",
"value": {
"has_next": true,
"next_starting_after": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"records": [
{
"job_id": "J-456",
"matches": [
{
"employee_id": "E-123",
"score": 0.58,
"overqualified": false,
"present_skills": [
{
"skill_id": "s001",
"skill_name": "Python",
"skill_proficiency": 3,
"critical": true,
"adjacent_skill_name": "Python",
"adjacent_skill_id": "s001",
"adjacent_skill_proficiency": 4,
"adjacency_score": 1,
"gap_impact": "medium"
},
{
"skill_id": "s004",
"skill_name": "SQL",
"skill_proficiency": 5,
"critical": true,
"adjacent_skill_name": "Databases",
"adjacent_skill_id": "s010",
"adjacent_skill_proficiency": 2,
"adjacency_score": 0.85,
"gap_impact": "low"
},
{
"skill_id": "s006",
"skill_name": "Business",
"skill_proficiency": 1,
"critical": false,
"adjacent_skill_name": "Business",
"adjacent_skill_id": "s006",
"adjacent_skill_proficiency": 1,
"adjacency_score": 1,
"gap_impact": "none"
}
],
"missing_skills": [
{
"skill_id": "s007",
"skill_name": "PowerPoint",
"skill_proficiency": 3,
"critical": true,
"gap_impact": "high"
}
]
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"description": "Description of the error.",
"anyOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "string",
"description": "Description of the error."
}
}
]
}
},
"example": [
{
"title": "400 Bad Request",
"description": "The request body was not structured correctly."
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"title": "Not Found",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "404 Not Found",
"description": "Unknown external_id describing this resource. Please create this resource first."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "503 Service Unavailable",
"description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
}
]
}
}
}
}
}
}
},
"/version": {
"get": {
"tags": [
"Version"
],
"summary": "Get API Version",
"description": "Get the current version of the API for your tenant.",
"security": [
{
"application": [
"read"
]
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"format": "date",
"example": "2021-01-19"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "401 Unauthorized",
"description": "OAuth access token is missing, invalid or expired."
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "403 Forbidden",
"description": "You don't have access to this resource."
}
]
}
}
}
},
"405": {
"description": "Method Not Allowed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the error."
},
"description": {
"type": "string",
"description": "Description of the error."
}
},
"example": [
{
"title": "405 Method Not Allowed",
"description": "This method is not allowed for the requested URL."
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "max connections reached: "
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"application": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://techwolf.eu.auth0.com/oauth/token",
"scopes": {
"write": "allows modifying resources",
"read": "allows reading resources",
"read_reports": "allows reading reports"
}
}
}
},
"application-us": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://techwolf-us.us.auth0.com/oauth/token",
"scopes": {
"write": "allows modifying resources",
"read": "allows reading resources",
"read_reports": "allows reading reports"
}
}
}
}
},
"schemas": {
"EmployeeDataListReduced": {
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
"EmployeeDataCRUDReduced": {
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position. Only one of `assigned_position` or `assigned_position_id` should be provided upon creation or update. Note that setting `assigned_position` instead of `assigned_position_id` does not provide Skill Profile data, as there is no link to a Job entity."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`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.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
"EmployeeCRUDData": {
"description": "Default structure for Employee data.",
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position. Only one of `assigned_position` or `assigned_position_id` should be provided upon creation or update. Note that setting `assigned_position` instead of `assigned_position_id` does not provide Skill Profile data, as there is no link to a Job entity."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`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.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
}
]
},
"SubmissionEmployeeData": {
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position. Only one of `assigned_position` or `assigned_position_id` should be provided upon creation or update. Note that setting `assigned_position` instead of `assigned_position_id` does not provide Skill Profile data, as there is no link to a Job entity."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`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.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
}
]
},
{
"type": "object",
"description": "Employee information to submit for processing by the system.",
"properties": {
"location": {
"description": "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).",
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"employee_documents": {
"type": "array",
"nullable": true,
"description": "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.",
"items": {
"type": "object",
"description": "Base64 encoded CV of the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
}
}
}
}
]
},
"EmployeeDataReduced": {
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`external_id` of the Job the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
"EmployeeData": {
"description": "Default structure for Employee data.",
"allOf": [
{
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"required": [
"external_id"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`external_id` of the Job the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
}
]
},
"UpdateEmployeeData": {
"description": "Default structure for updating Employee data.",
"allOf": [
{
"description": "Reduced structure for Employee data.",
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position. Only one of `assigned_position` or `assigned_position_id` should be provided upon creation or update. Note that setting `assigned_position` instead of `assigned_position_id` does not provide Skill Profile data, as there is no link to a Job entity."
},
"assigned_position_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "`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.",
"pattern": "[a-zA-Z0-9_-]+"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Nested structure for Employee data.",
"properties": {
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
},
"education_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for education history listed for an Employee.",
"type": "object",
"required": [
"degree_name"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the education (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2016-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the education (IS08601 format). Omit the end date if the education is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"school": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Harvard University"
},
"degree_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "Master in Human Resources Management"
}
}
}
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "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."
},
"desired_functions": {
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for a (non) desired function of an Employee.",
"type": "object",
"required": [
"title",
"importance"
],
"properties": {
"title": {
"type": "string",
"description": "A function title, can either be a single-line string or free text.",
"minLength": 1,
"example": "Business Analyst"
},
"importance": {
"type": "number",
"format": "float",
"description": "Importance of the function title.",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
},
"description": "List of desired functions of the Employee. Elements consist of a title and an 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.",
"example": [
{
"title": "Business Analyst",
"importance": 0.5
},
{
"title": "Police Officer",
"importance": 1
}
]
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
},
"non_desired_functions": {
"type": "array",
"deprecated": true,
"nullable": true,
"description": "List of non-desired functions of the Employee. Elements consist of a title and an 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."
}
}
},
{
"type": "object",
"description": "Employee information to submit for processing by the system.",
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"employee_documents": {
"type": "array",
"description": "List of base64 encoded documents (e.g. CVs) related to the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.",
"items": {
"type": "object",
"description": "Base64 encoded CV of the Employee in PDF (.pdf), Word (.doc or .docx) or plain-text (.txt) format.",
"required": [
"mimeType",
"base64Content"
],
"properties": {
"mimeType": {
"type": "string",
"enum": [
"application/pdf",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
},
"base64Content": {
"type": "string",
"format": "byte",
"minLength": 1
}
},
"example": {
"mimeType": "application/pdf",
"base64Content": "JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
}
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Employee will not be used in matching if active is `false`. This is useful when an Employee is being phased out."
},
"organisational_unit": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "e4d3a59c-2f37-4a3f-9318-9d75e0e7a8f1",
"description": "The external ID of the Organisational Unit the Employee is assigned to.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
"DeprecatedRequestSkill": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
"SkillWithRequiredHasSkillProficiency": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
},
"self_rated_proficiency_level": {
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency level from the Skill for this Employee. You can only set this for a Skill that is validated (`has_skill` should be `true`). `self_rated_proficiency_level` and `self_rated_proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"self_rated_proficiency_float": {
"description": "The self-rated proficiency (passed as a float) for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency from the Skill for this Employee. You can only set this for a Skill that is validated (`has_skill` should be `true`). `self_rated_proficiency_level` and `self_rated_proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
}
}
}
]
},
"ExternalVendorSkillWithRequiredHasSkillProficiency": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill_id",
"has_skill"
],
"properties": {
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning (ML)",
"description": "The name of the Skill."
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
},
"self_rated_proficiency_level": {
"description": "The self-rated proficiency level for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`).",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"self_rated_proficiency_float": {
"description": "The self-rated proficiency (passed as a float) for this Skill that is associated with the Employee. Setting this to `null` will remove any existing self-rated proficiency from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `self_rated_proficiency_level` and `self_rated_proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
}
}
}
]
},
"CollectionMetric": {
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
"EmployeeCollectionMetric": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Employee"
}
}
}
]
},
"EmployeeCount": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Employee"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Employee objects stored inside the system.",
"example": 1000
}
}
}
]
},
"CustomPropertyFilter": {
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
"SkillsMatchWeights": {
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"DesiredFunctionsWeights": {
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"EmployabilityPostData": {
"description": "Default structure for Employee data.",
"allOf": [
{
"type": "object",
"description": "Filters to be applied during the calculation",
"properties": {
"employee_filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
}
},
"vacancy_filters": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "max_geo_distance",
"required": [
"filter",
"max_geo_distance"
],
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the distance is more than the provided `max_geo_distance`.",
"enum": [
"max_geo_distance"
],
"example": "max_geo_distance"
},
"max_geo_distance": {
"type": "integer",
"description": "The maximal allowed distance (in km, as the crow flies) between a matching Employee & Vacancy.",
"example": 50
}
}
},
{
"type": "object",
"title": "custom_property",
"required": [
"filter",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Filter out all entities for which the given Custom Property does not match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for filtering. List properties are not supported. If the entity does not have this property, it is not included in the result.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the property value and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`\n * `boolean`: `eq`, `neq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`, `neq`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt",
"neq"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
]
},
{
"type": "object",
"title": "low_data_availability",
"required": [
"filter",
"exclude_low_data_availability"
],
"properties": {
"filter": {
"type": "string",
"description": "Exclude entities that have low data availability. Entities with low data availability have insufficient data for qualitative Skill inference.",
"enum": [
"low_data_availability"
],
"example": "low_data_availability"
},
"exclude_low_data_availability": {
"type": "boolean",
"description": "Set to `true` to exclude entities with low data availability from the matching results. Set to `false` to include all entities regardless of their data availability.",
"example": true
}
}
}
]
}
}
}
},
{
"type": "object",
"description": "List of weights to be applied during the calculation",
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"value": 1
},
{
"weight": "desired_functions",
"value": 0.03
}
]
}
}
}
]
},
"EntityMetric": {
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for an entity metric",
"required": [
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
"EmployeeEntityMetric": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for an entity metric",
"required": [
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"type": "object",
"required": [
"entity_type"
],
"properties": {
"entity_type": {
"type": "string",
"example": "Employee"
}
}
}
]
},
"EmployeeEmployability": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for an entity metric",
"required": [
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
},
{
"type": "object",
"required": [
"entity_type"
],
"properties": {
"entity_type": {
"type": "string",
"example": "Employee"
}
}
}
]
},
{
"type": "object",
"description": "A measure indicating the degree to which this Employee can find other opportunities within your available Vacancies, reported as a number between 0 and 1.",
"required": [
"metric_name",
"metric_value"
],
"properties": {
"metric_name": {
"type": "string",
"example": "configurable_employability"
},
"metric_value": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8
}
}
}
]
},
"VacancyData": {
"description": "Default structure for Vacancy data.",
"required": [
"external_id",
"job_title",
"job_description"
],
"allOf": [
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
}
]
},
"SubmissionVacancyData": {
"allOf": [
{
"description": "Default structure for Vacancy data.",
"required": [
"external_id",
"job_title",
"job_description"
],
"allOf": [
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
}
]
},
{
"type": "object",
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
]
},
"UpdateVacancyData": {
"description": "Default structure for updating Vacancy data.",
"allOf": [
{
"description": "Default structure for updating Vacancy data.",
"type": "object",
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Vacancy will not be used in matching if active is `false`. This is useful when a Vacancy is being phased out."
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for languages required by the Vacancy, 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."
},
"company": {
"type": "string",
"format": "uuid",
"nullable": true,
"minLength": 1,
"example": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
"pattern": "[a-zA-Z0-9_-]+",
"description": "external_id from the External Company the Vacancy is linked to."
}
}
},
{
"type": "object",
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
}
}
}
]
},
"ResponseSkill": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
"SkillWithoutHasSkillProficiency": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
}
}
}
]
},
"ExternalVendorSkillWithoutHasSkillProficiency": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill_id",
"has_skill"
],
"properties": {
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present."
}
}
}
]
},
"VacancyCollectionMetric": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Vacancy"
}
}
}
]
},
"VacancyCount": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Vacancy"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Vacancy objects stored inside the system.",
"example": 1000
}
}
}
]
},
"CourseData": {
"description": "Default structure for Course data.",
"type": "object",
"required": [
"external_id",
"course_title",
"course_description"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
},
{
"properties": {
"source": {
"description": "Source system or location of this Course.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Udemy"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Course will not be used in matching if active is `false`. This is useful when a Course is being phased out."
}
}
}
]
},
"SubmissionCourseData": {
"allOf": [
{
"description": "Default structure for Course data.",
"type": "object",
"required": [
"external_id",
"course_title",
"course_description"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"course_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Computer Science 101",
"description": "Title of the Course."
},
"course_description": {
"type": "string",
"minLength": 1,
"example": "This Professional Certificate will start you at the absolute beginning teaching you about the fundamental binary language of modern computers. You’ll learn about the Turing Machine—a model for the digital computer. You’ll also learn the basics of analytic logic and how learning and applying basic principles of logic can help you both work with and work on technical solutions. You’ll work in a managed environment and learn to code your very first program in Python – a powerful but simple programming language used by app developers and data scientists.",
"description": "Textual description of the Course."
}
}
},
{
"properties": {
"source": {
"description": "Source system or location of this Course.",
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Udemy"
},
"active": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "The Course will not be used in matching if active is `false`. This is useful when a Course is being phased out."
}
}
}
]
}
]
},
"OrganisationalUnitData": {
"description": "Default structure for Organisational Unit data.",
"type": "object",
"required": [
"external_id",
"name",
"parent_id",
"active",
"total_nr_of_employees"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "Engineering",
"description": "The name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not."
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. Organisational Units with `parent_id=null` are root Organisational Units."
}
}
},
{
"properties": {
"total_nr_of_employees": {
"type": "integer",
"minimum": 0,
"example": 13,
"description": "Total number of Employees in this Organisational Unit and all its subordinate Organisational Units."
}
}
}
]
},
"SubmissionOrganisationalUnitData": {
"description": "Information needed for creating an Organisational Unit.",
"type": "object",
"required": [
"external_id",
"name"
],
"allOf": [
{
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "Engineering",
"description": "The name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not.",
"default": true
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"default": null,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. Organisational Units with `parent_id=null` are root Organisational Units."
}
}
}
]
},
"UpdateOrganisationalUnitData": {
"description": "Default structure for Organisational Unit data.",
"type": "object",
"allOf": [
{
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Engineering",
"description": "Name of the Organisational Unit."
},
"active": {
"type": "boolean",
"description": "Indicates whether the Organisational Unit is active or not.",
"default": true
}
}
},
{
"properties": {
"parent_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "b4824606-fc95-53ed-b80g-6f8c2ge908c8",
"pattern": "[a-zA-Z0-9_-]+",
"description": "Unique identifier for the parent Organisational Unit, establishing the organisational structure. If updated with `parent_id=null`, the Organisational Unit becomes a root Organisational Unit."
}
}
}
]
},
"CourseCollectionMetric": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Course"
}
}
}
]
},
"CourseCount": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "Course"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Course objects stored inside the system.",
"example": 1000
}
}
}
]
},
"SkillClusterCollectionMetric": {
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "SkillCluster"
}
}
}
]
},
"SkillClusterCount": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The base template for a metric.",
"type": "object",
"required": [
"entity_type",
"entity_id",
"metric_name",
"metric_value",
"last_update"
],
"properties": {
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"metric_name": {
"type": "string"
},
"metric_value": {
"type": "number"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The base template for a collection metric"
}
]
},
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"example": "SkillCluster"
}
}
}
]
},
{
"type": "object",
"properties": {
"metric_name": {
"type": "string",
"example": "count"
},
"metric_value": {
"type": "integer",
"description": "Total number of Skill Cluster objects stored inside the system.",
"example": 1000
}
}
}
]
},
"CompanyReadData": {
"allOf": [
{
"description": "Default structure for External Company data.",
"type": "object",
"required": [
"external_id",
"name",
"vat"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
}
}
},
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
},
"CompanyCreateData": {
"allOf": [
{
"description": "Default structure for External Company data.",
"type": "object",
"required": [
"external_id",
"name",
"vat"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
}
}
},
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for language requirements of the External Company, 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."
}
}
}
]
},
"SubmissionCompanyData": {
"allOf": [
{
"allOf": [
{
"description": "Default structure for External Company data.",
"type": "object",
"required": [
"external_id",
"name",
"vat"
],
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "TechWolf",
"description": "Name of the External Company."
},
"vat": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"example": "BE0702852201",
"description": "The VAT identification number for this External Company."
}
}
},
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"oneOf": [
{
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
},
{
"description": "A geographic location, expressed as an address. This can represent a home address, an office location... Each entity is limited to having a single location.",
"type": "object",
"title": "Address",
"required": [
"country",
"postal_code",
"city"
],
"properties": {
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter country code (ISO 3166-1 alpha-2).",
"example": "BE"
},
"state": {
"type": "string",
"description": "State, province, or region.",
"example": "Flanders"
},
"postal_code": {
"type": "string",
"description": "ZIP or postal code. Not required when `city` is specified.",
"example": "9000"
},
"city": {
"type": "string",
"description": "City, district, suburb, town, or village. Not required when `postal_code` is specified.",
"example": "Ghent"
},
"address": {
"type": "string",
"description": "Street name and post office box number.",
"example": "Overzet 14B"
}
}
}
]
},
"languages": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "nl"
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 2
}
}
},
"description": "List of ISO 639-1 codes for language requirements of the External Company, 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."
}
}
}
]
}
]
},
"ResponseSkillName": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_name",
"skill_id"
]
}
]
},
"GeoDistanceWeights": {
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The geo distance weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"LanguageWeights": {
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyWeights": {
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyIsInWeights": {
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyIsInListWeights": {
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property is in list weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyContainsWeights": {
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you're calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyContainsElementWeights": {
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property contains element weight applies the specified score boosting effect (`value`) to all the entities for which the values list of a Custom Property contains a given value.",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Should be a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "string",
"type": "string",
"minLength": 1,
"description": "Property value that should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values should be present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyListOverlapWeights": {
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property list overlap weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "number",
"format": "float",
"description": "The weight value to apply.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"VacancyCustomProperties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
},
"EmployeeVacancyMatchResultCustomPropertiesVacancy": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
},
"EmployeeVacancyMatchResultEntityVacancy": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the Job title and Job description of the matching Vacancy.",
"required": [
"job_title",
"job_description"
],
"properties": {
"job_title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Vacancy."
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "We are looking for a software engineer with great communication Skills in Ghent. Experience in front-end development, git, agile working is a plus.",
"description": "Textual description of the Vacancy (job posting)."
}
}
}
]
},
"EmployeeVacancyMatchResultLocation": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the location of the matching entity.",
"required": [
"location"
],
"properties": {
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
}
]
},
"SkillsMatchWeightsContribution": {
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"DesiredFunctionsWeightsContribution": {
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"GeoDistanceWeightsContribution": {
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The *geo distance* weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"LanguageWeightsContribution": {
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyWeightsContribution": {
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyIsInWeightsContribution": {
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in* weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you are calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyIsInListWeightsContribution": {
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in list* weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyContainsWeightsContribution": {
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains* weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyContainsElementWeightsContribution": {
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains element* weight applies the specified\nscore boosting effect (`value`) to all the entities for which the\nvalues list of a Custom Property contains a given value.\n",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Is a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"CustomPropertyListOverlapWeightsContribution": {
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *list overlap* weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
"EmployeeVacancyMatchResultBreakdown": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"weights"
],
"properties": {
"weights": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"title": "skills_match",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the Skills match.",
"enum": [
"skills_match"
],
"example": "skills_match"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "desired_functions",
"required": [
"weight"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Change the weighting of the desired function boost.",
"enum": [
"desired_functions"
],
"example": "desired_functions"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "geo_distance",
"required": [
"weight",
"full_score_distance",
"zero_score_distance"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The *geo distance* weight will apply a matching boost to entities withing close proximity of each other. Between the `full_score_distance` and `zero_score_distance`, the boost value linearly decreases. If the distance is shorter than `full_score_distance`, the full boost is applied, while any distance bigger than `zero_score_distance` will result in a zero boost.",
"enum": [
"geo_distance"
],
"example": "geo_distance"
},
"full_score_distance": {
"type": "integer",
"description": "The distance (in km) to where the boosting is fully applied.",
"example": 5
},
"zero_score_distance": {
"type": "integer",
"description": "The distance (in km) from where no boosting will be applied.",
"example": 50
},
"location": {
"description": "A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.",
"type": "object",
"title": "Location",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"format": "float",
"minimum": -90,
"maximum": 90,
"description": "The latitude of the location",
"example": 51.0216707
},
"lng": {
"type": "number",
"format": "float",
"minimum": -180,
"maximum": 180,
"description": "The longitude of the location",
"example": 3.6887328
}
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "language",
"required": [
"weight",
"max_overqualification",
"max_underqualification"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The language weight will apply a matching boost to entities with similar language levels. How similar the language levels must be for boosting, can be determined using the `max_overqualification` and `max_underqualification` parameters.",
"enum": [
"language"
],
"example": "language"
},
"max_overqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be above the required level.",
"minimum": 1,
"maximum": 5,
"example": 3
},
"max_underqualification": {
"type": "integer",
"description": "The amount of language levels that the entity may be below the required level. If `level - max_underqualification <= 0` all entities with a lower language level receive a boost.",
"minimum": 1,
"maximum": 5,
"example": 3
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Property match the condition `property_name` `operator` `property_value`",
"enum": [
"custom_property"
],
"example": "custom_property"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for score boosting. List properties are not supported. If the entity does not have this property, the score boosting does not apply to the matching score of this entity.",
"example": "yearly_salary"
},
"operator": {
"type": "string",
"description": "The type of comparison to apply between the `property_value` and the Custom Properties' value. The following operators are supported per property type:\n * `text`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `number`: `lt`, `lte`, `eq`, `gte`, `gt`\n * `boolean`: `eq`\n * `datetime`: `lt`, `lte`, `eq`, `gte`, `gt`",
"enum": [
"lt",
"lte",
"eq",
"gte",
"gt"
],
"default": "eq",
"example": "gte"
},
"property_value": {
"description": "Value used in the comparison to the Custom Properties' value.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in* weight applies the specified score boosting effect (`value`) to all the entities for which the `list[text]` Custom Property contains the `text` Custom Property of the entity for which you are calculating matches.",
"enum": [
"custom_property_is_in"
],
"example": "custom_property_is_in"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_work_regime"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "offered_work_regimes"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_is_in_list",
"required": [
"weight",
"property_name",
"possible_values"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *is in list* weight applies the specified score boosting effect (`value`) to all the entities for which a Custom Property is contained in a list of given values.",
"enum": [
"custom_property_is_in_list"
],
"example": "custom_property_is_in_list"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting.",
"example": "region"
},
"possible_values": {
"type": "array",
"description": "List of allowed values for the Custom Property. No score boosting is applied to all entities with a value for the specified Custom Property that is not in this list.",
"items": {
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
}
]
}
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains* weight applies the specified score boosting effect (`value`) to all the entities for which the value of their `text` Custom Property is contained in the `list[text]` Custom Property of the entity for which you're calculating matches.",
"enum": [
"custom_property_contains"
],
"example": "custom_property_contains"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property for the entity for which you are calculating matches. Must be a `list[text]` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "sectors"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "Property name of the property of the entities that are possible match results. Should be a `text` Custom Property. If the entity does not have this property, no score boost is applied.",
"example": "desired_sector"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_contains_element",
"required": [
"weight",
"property_name",
"property_value"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *contains element* weight applies the specified\nscore boosting effect (`value`) to all the entities for which the\nvalues list of a Custom Property contains a given value.\n",
"enum": [
"custom_property_contains_element"
],
"example": "custom_property_contains_element"
},
"property_name": {
"type": "string",
"minLength": 1,
"description": "Name of the Custom Property used for boosting. Is a `list[text]` Custom Property.",
"example": "industries"
},
"property_value": {
"oneOf": [
{
"title": "String",
"type": "string",
"minLength": 1,
"description": "Property value that is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing this value.",
"example": "electronics"
},
{
"title": "List of Strings",
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"description": "List of property values. One of these values is present in the values list of the Custom Property. No score boosting is applied to all entities with a list not containing any of these values."
},
"example": [
"electronics",
"aviation"
]
}
]
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
},
{
"type": "object",
"title": "custom_property_list_overlap",
"required": [
"weight",
"from_entity_property",
"to_entity_property"
],
"allOf": [
{
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "The Custom Property *list overlap* weight applies the specified score boosting effect (`value`) to all the entities for which the given Custom Properties of type `list[text]` have at least one item in common.",
"enum": [
"custom_property_list_overlap"
],
"example": "custom_property_list_overlap"
},
"from_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the entity to find matches for. If the entity does not have this property, no weight is applied.",
"example": "desired_industries"
},
"to_entity_property": {
"type": "string",
"minLength": 1,
"description": "The name of a `list[text]` property of the matching entities. The weight is not applied if matches do not have this Custom Property.",
"example": "industries"
}
}
},
{
"type": "object",
"required": [
"contribution"
],
"properties": {
"contribution": {
"type": "number",
"format": "float",
"description": "The contribution of this weight to the total matching score. The sum of the contributions of all weights should be equal to the match score, except when this sum is greater than 1, in which case the total match score is capped to 1.",
"minimum": 0,
"maximum": 1,
"example": 0.05
}
}
}
]
}
]
},
"example": [
{
"weight": "skills_match",
"contribution": 0.53
},
{
"weight": "desired_functions",
"contribution": 0.03
},
{
"weight": "geo_distance",
"contribution": 0.02,
"full_score_distance": 5,
"zero_score_distance": 50
},
{
"weight": "language",
"contribution": 0.03,
"max_overqualification": 2,
"max_underqualification": 3
},
{
"weight": "custom_property",
"contribution": 0.04,
"property_name": "yearly_salary",
"operator": "gte",
"property_value": 45000
},
{
"weight": "custom_property_is_in",
"contribution": 0.06,
"from_entity_property": "desired_work_regime",
"to_entity_property": "offered_work_regimes"
},
{
"weight": "custom_property_is_in_list",
"contribution": 0.05,
"property_name": "region",
"possible_values": [
"Flanders",
"Wallonia"
]
},
{
"weight": "custom_property_contains",
"contribution": 0.07,
"from_entity_property": "sectors",
"to_entity_property": "desired_sector"
},
{
"weight": "custom_property_contains_element",
"contribution": 0.04,
"property_name": "industries",
"property_value": [
"Electronics",
"Aviation"
]
},
{
"weight": "custom_property_list_overlap",
"contribution": 0.02,
"from_entity_property": "desired_industries",
"to_entity_property": "industries"
}
]
}
}
}
]
},
"EmployeeVacancyMatchResultExplained": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the score breakdown for this result, showing the contributions of each individual applied weight to the total matching score.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Vacancy requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
"EmployeeCustomProperties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
},
"EmployeeVacancyMatchResultCustomPropertiesEmployee": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
},
"EmployeeVacancyMatchResultEntityEmployee": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Vacancy.",
"type": "object",
"required": [
"employee_id",
"vacancy_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and Vacancy, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Vacancy, including the assigned position and working history of the matching Employee.",
"required": [
"assigned_position",
"working_history"
],
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
}
}
}
]
},
"CourseCustomProperties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "source",
"property_value": "https://online.stanford.edu/courses/soe-ycscs101-sp-computer-science-101"
},
{
"property_name": "price",
"property_value": 399
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "required_prerequisites",
"property_value": [
"General programming Skills",
"3 years of experience"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
},
"EmployeeJobMatchResultExplained": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
"EmployeeJobMatchResultPropertiesExplainedSingle": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
},
"JobCustomProperties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
},
"EmployeeJobMatchResultCustomPropertiesJob": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
},
"EmployeeJobMatchResultEntityJob": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the name of the Job and the external ID of the corresponding Job Family.",
"required": [
"job_title",
"job_description",
"job_name"
],
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Job."
}
}
}
]
},
"EmployeeJobMatchResultPropertiesSimple": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"description": "A match result between an Employee and a Job, including overqualified status.",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
},
"EmployeeJobMatchResultPropertiesExplained": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"description": "A match result between an Employee and a Job, including detailed skill information with proficiency levels, criticality and gap impact.",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the Employee does not possess, with detailed skill information including required proficiency level, criticality and gap impact.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the Employee possesses, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
},
"EmployeeJobMatchResultCustomPropertiesEmployee": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
},
"EmployeeJobMatchResultEntityEmployee": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job.",
"type": "object",
"required": [
"job_id",
"employee_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job, including the assigned position and working history of the Employee.",
"required": [
"assigned_position",
"working_history"
],
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
}
}
}
]
},
"JobSourceJobMatchResultCustomPropertiesJob": {
"allOf": [
{
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a source Job, including the Custom Properties of the source Job.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
},
"JobSourceJobMatchResultEntityJob": {
"allOf": [
{
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a source Job, including the name of the source Job.",
"required": [
"job_name"
],
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Job."
}
}
}
]
},
"JobSourceJobMatchResultExplained": {
"allOf": [
{
"description": "A match result between a Job and a source Job.",
"type": "object",
"required": [
"job_id",
"source_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"source_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a source Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a source Job, including an explanation of what Skills are missing and what Skills are present in the source Job's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job requires, but the source Job does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job requires and the source Job possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
"JobTargetJobMatchResultCustomPropertiesJob": {
"allOf": [
{
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a target Job, including the Custom Properties of the target Job.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
},
"JobTargetJobMatchResultEntityJob": {
"allOf": [
{
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a target Job, including the name of the target Job.",
"required": [
"job_name"
],
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the Job."
}
}
}
]
},
"JobTargetJobMatchResultExplained": {
"allOf": [
{
"description": "A match result between a Job and a target Job.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between a Job and a target Job, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between a Job and a target Job, including an explanation of what Skills are missing and what Skills are present in the target Job's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the target Job requires, but the provided Job does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the target Job requires and the provided Job possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
"JobTaskMatchResultExplained": {
"title": "Explained",
"allOf": [
{
"title": "Simple",
"description": "A task-based match result between two Jobs.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result between two Jobs, including a per-Task breakdown of the match. Each Task on either side of the pair is reported once per direction as either present (it has a sufficiently similar Task on the other side) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task on the other side of the pair.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task on the other side of the pair.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
},
"JobTaskMatchResultWithIncludes": {
"allOf": [
{
"title": "Simple",
"description": "A task-based match result between two Jobs.",
"type": "object",
"required": [
"job_id",
"target_job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result, optionally enriched with attributes requested via the `include` query parameter.",
"properties": {
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software engineer",
"description": "Title of the target Job. Present when `include=entity`."
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "freelance",
"property_value": false
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
},
"AdHocTaskMatchResultExplained": {
"title": "Explained",
"allOf": [
{
"title": "Simple",
"description": "An ad-hoc task-based match result between two task sets.",
"type": "object",
"required": [
"score"
],
"properties": {
"score": {
"description": "The symmetric task-based match score between the two task sets, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "An ad-hoc task-based match result between two task sets, including a per-Task breakdown of the match. Each Task on either side is reported once per direction as either present (it has a sufficiently similar Task in the other set) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task in the other set.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task in the other set.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
},
"EmployeeJobFamilyMatchResultExplained": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "A match result between an Employee and a Job Family, including an explanation of what Skills are missing and what Skills are present in the Employee's Skill Profile.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"missing_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires, but the Employee does not possess.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
},
"present_skills": {
"type": "array",
"description": "A list of Skills that the Job Family requires and the Employee possesses.",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
}
}
}
]
},
"JobFamilyCustomProperties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
},
"EmployeeJobFamilyMatchResultCustomPropertiesJobFamily": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
},
"EmployeeJobFamilyMatchResultEntityJobFamily": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the name of the Job Family and Job Family Group",
"required": [
"job_family_name",
"job_family_group"
],
"properties": {
"job_family_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software Development",
"description": "Name of the Job Family."
},
"job_family_group": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Information Technology",
"description": "Name of the Job Family Group."
}
}
}
]
},
"EmployeeJobFamilyMatchResultCustomPropertiesEmployee": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the Custom Properties of the matching entity.",
"required": [
"custom_properties"
],
"properties": {
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "direct_manager",
"property_value": "John Doe"
},
{
"property_name": "yearly_wage",
"property_value": 50000
},
{
"property_name": "freelancer",
"property_value": false
},
{
"property_name": "driving_licenses",
"property_value": [
"B",
"C"
]
},
{
"property_name": "start_date",
"property_value": "2020-01-14"
},
{
"property_name": "creation_date",
"property_value": "2020-01-12T17:14:30.40"
}
]
}
]
}
}
}
]
},
"EmployeeJobFamilyMatchResultEntityEmployee": {
"allOf": [
{
"title": "Simple",
"description": "A match result between an Employee and a Job Family.",
"type": "object",
"required": [
"job_family_id",
"employee_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b003505-eb84-42dc-a79f-5e7b1fe897b7"
},
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The matching score between an Employee and a Job Family, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"type": "object",
"description": "A match result between an Employee and a Job Family, including the assigned position and working history of the Employee.",
"required": [
"assigned_position",
"working_history"
],
"properties": {
"assigned_position": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 255,
"example": "Python Developer",
"description": "Job title of the Employee's assigned position."
},
"working_history": {
"description": "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.",
"type": "array",
"nullable": true,
"items": {
"description": "Default structure for work experiences listed for an Employee.",
"type": "object",
"required": [
"job_title"
],
"properties": {
"start_date": {
"type": "string",
"description": "Start date of the work experience (IS08601 format).",
"minLength": 1,
"format": "date",
"example": "2018-09-05"
},
"end_date": {
"type": "string",
"description": "End date of the work experience (IS08601 format). Omit the end date if the work experience is still ongoing.",
"minLength": 1,
"format": "date",
"example": "2020-06-17"
},
"company": {
"type": "string",
"minLength": 1,
"example": "TechWolf BV"
},
"job_title": {
"type": "string",
"minLength": 1,
"example": "HR Manager"
},
"job_description": {
"type": "string",
"minLength": 1,
"example": "Manage the HR department and perform workforce planning"
}
}
}
}
}
}
]
},
"JobFamilyTaskMatchResultExplained": {
"title": "Explained",
"allOf": [
{
"description": "A task-based match result between two Job Families.",
"type": "object",
"required": [
"job_family_id",
"target_job_family_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Job Families, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result between two Job Families, including a per-Task breakdown of the match. Each Task on either side of the pair is reported once per direction as either present (it has a sufficiently similar Task on the other side) or missing (it does not). Returned when `response_format=explained`.",
"required": [
"present_tasks",
"missing_tasks"
],
"properties": {
"present_tasks": {
"type": "array",
"description": "The Tasks that contributed to the match, each paired with its most similar Task on the other side of the pair.",
"items": {
"description": "A Task that contributed to the match: it has a sufficiently similar Task on the other side of the pair (its adjacent Task), so it adds to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction",
"adjacent_task_id",
"adjacent_task_name",
"adjacency_score",
"hours_share"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Write unit tests for backend services"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set) and was matched against its most similar Task on the target side. `target_to_source` is the inverse: the Task is on the target side and was matched against its most similar Task on the source side. Because the score is symmetric, both directions are evaluated and a Task can appear once per direction."
},
"adjacent_task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the most similar Task on the other side of the pair, i.e. the Task this one was matched against.",
"example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
},
"adjacent_task_name": {
"type": "string",
"description": "The name of the adjacent Task.",
"example": "Add automated test coverage for backend services"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.91,
"description": "The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Only pairs scoring above the internal similarity floor are kept; a Task with no above-floor counterpart is reported under `missing_tasks` instead."
},
"hours_share": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.6,
"description": "The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Tasks with more weekly hours weigh more heavily. Within a direction, summing `hours_share × adjacency_score` across the present Tasks reconstructs that direction's contribution to the overall symmetric score."
}
}
}
},
"missing_tasks": {
"type": "array",
"description": "The Tasks that did not contribute to the match because they had no sufficiently similar Task on the other side of the pair.",
"items": {
"description": "A Task that did not contribute to the match: it has no sufficiently similar Task on the other side of the pair, so it adds nothing to the match score.",
"type": "object",
"required": [
"task_id",
"task_name",
"direction"
],
"properties": {
"task_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"description": "The unique ID of the Task.",
"example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
},
"task_name": {
"type": "string",
"description": "The name of the Task.",
"example": "Operate legacy mainframe for payroll processing"
},
"direction": {
"type": "string",
"enum": [
"source_to_target",
"target_to_source"
],
"example": "source_to_target",
"description": "Which side of the pair the Task belongs to. `source_to_target` means the Task is on the source side (the `{job_external_id}` Job, or the `source_tasks` set); `target_to_source` means it is on the target side. The Task had no above-floor counterpart on the opposite side, so no adjacency fields are returned for it."
}
}
}
}
}
}
]
},
"JobFamilyTaskMatchResultWithIncludes": {
"allOf": [
{
"description": "A task-based match result between two Job Families.",
"type": "object",
"required": [
"job_family_id",
"target_job_family_id",
"score"
],
"properties": {
"job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "b0035050-eb84-42dc-a79f-5e7b1fe897b7"
},
"target_job_family_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7"
},
"score": {
"description": "The symmetric task-based match score between the two Job Families, expressed as a number between 0 and 1.",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.42
}
}
},
{
"type": "object",
"description": "A task-based match result, optionally enriched with attributes requested via the `include` query parameter.",
"properties": {
"job_family_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Software Engineering",
"description": "Name of the target Job Family. Present when `include=entity`."
},
"job_family_group": {
"type": "string",
"maxLength": 255,
"example": "Engineering",
"description": "Group of the target Job Family. Present when `include=entity`."
},
"custom_properties": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "language",
"property_value": "Dutch"
},
{
"property_name": "experience",
"property_value": 5
},
{
"property_name": "required_driving_licenses",
"property_value": [
"B",
"C"
]
}
]
}
]
}
}
}
]
},
"SkillWithRequiredHasSkillProperty": {
"required": [
"score"
],
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill.",
"deprecated": true
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present. Cannot be `false` if the Skill is not present in the Skill Profile of the entity."
},
"proficiency_level": {
"description": "The required proficiency level for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"proficiency_float": {
"description": "The required proficiency level (passed as a float) for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
},
"critical": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the Skill is critical for the entity. Setting this to `null` will remove the critical flag from the Skill. You can only set this for a Skill that is validated (`has_skill` should be `true`)."
}
}
}
]
},
"ExternalVendorSkillWithRequiredHasSkillProperty": {
"required": [
"score"
],
"allOf": [
{
"type": "object",
"required": [
"skill",
"skill_id",
"has_skill"
],
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning (ML)",
"description": "The name of the Skill."
},
"skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Indicates whether the Skill is present. Cannot be `false` if the Skill is not present in the Skill Profile of the entity."
},
"proficiency_level": {
"description": "The required proficiency level for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "integer",
"format": "int32",
"nullable": true,
"minimum": 1
},
"proficiency_float": {
"description": "The required proficiency level (passed as a float) for this Skill that is associated with the entity. Setting this to `null` will remove any existing proficiency level from the Skill for this entity. You can only set this for a Skill that is validated (`has_skill` should be `true`). `proficiency_level` and `proficiency_float` are mutually exclusive!",
"type": "number",
"format": "float",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 1,
"nullable": true
},
"critical": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the Skill is critical for the entity. Setting this to `null` will remove the critical flag from the Skill. You can only set this for a Skill that is validated (`has_skill` should be `true`)."
}
}
}
]
},
"FeedbackSkill": {
"title": "skills_feedback",
"description": "Default structure for Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"required": [
"skill",
"skill_id"
]
}
]
},
{
"type": "object",
"required": [
"has_skill"
],
"properties": {
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
},
"ExternalVendorFeedbackSkill": {
"title": "external_vendor_skills_feedback",
"description": "Default structure for External Vendor Skills in Feedback Data.",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"techwolf_skill",
"techwolf_skill_id",
"external_skill_name",
"external_skill_id",
"has_skill"
],
"properties": {
"techwolf_skill": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"techwolf_skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"external_skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"external_skill_id": {
"title": "External Vendor Skill ID",
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "111-BBB",
"description": "The ID of the Skill, consisting of alphanumeric characters, hyphens and underscores. The format of this ID will differ from vendor to vendor.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"has_skill": {
"type": "boolean",
"description": "Whether the Skill is present."
}
}
}
]
},
"CustomPropertyDefinitionData": {
"description": "Default structure for CustomPropertyDefinition.",
"allOf": [
{
"description": "CustomPropertyDefinition property name.",
"type": "object",
"required": [
"property_name"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`.",
"example": "sector"
}
}
},
{
"description": "CustomPropertyDefinition property type.",
"type": "object",
"required": [
"property_type"
],
"properties": {
"property_type": {
"type": "string",
"minLength": 1,
"maxLength": 10,
"example": "text",
"description": "Expected type of the Custom Property.",
"enum": [
"text",
"number",
"boolean",
"list[text]",
"datetime"
]
}
}
}
]
},
"CustomPropertiesCRUD": {
"allOf": [
{
"description": "A list of properties for a given entity. Property values are either strings or numbers.",
"type": "array",
"items": {
"type": "object",
"required": [
"property_name",
"property_value"
],
"properties": {
"property_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The name of the Custom Property. Can not contain `__`."
},
"property_value": {
"description": "Fill in the value of the property.",
"oneOf": [
{
"title": "Boolean",
"type": "boolean"
},
{
"title": "Number",
"oneOf": [
{
"title": "Integer",
"type": "integer"
},
{
"title": "Float",
"type": "number",
"format": "float"
}
]
},
{
"title": "Date",
"oneOf": [
{
"title": "IS08601 Date",
"type": "string",
"description": "IS08601-formatted date.",
"format": "date",
"example": "2025-05-02"
},
{
"title": "IS08601 Datetime",
"type": "string",
"description": "IS08601-formatted datetime.",
"format": "date-time",
"example": "2025-05-02T14:30:00+02:00"
}
]
},
{
"title": "String",
"type": "string",
"minLength": 1
},
{
"title": "List of Strings",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
]
}
},
"minItems": 1,
"maxItems": 100
}
},
{
"example": [
{
"property_name": "type",
"property_value": "online"
},
{
"property_name": "years_of_experience",
"property_value": 3
},
{
"property_name": "online",
"property_value": true
},
{
"property_name": "tools",
"property_value": [
"JIRA",
"Git"
]
},
{
"property_name": "creation_date",
"property_value": "2023-04-25T17:14:30.40"
}
]
}
]
},
"Counts": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The total number of entities for each type.",
"properties": {
"report_name": {
"type": "string",
"example": "counts"
},
"report_data": {
"type": "object",
"description": "Dictionary with the total number of entities for each type.",
"properties": {
"counts": {
"type": "object",
"example": {
"employees": 1000,
"vacancies": 1000,
"courses": 1000
}
}
}
}
}
}
]
},
"SkillClusterAdoptionReport": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Skill Cluster adoption report for the requested Skill Cluster(s) and Custom Property.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report",
"example": "employee_skill_cluster_adoption"
},
"report_data": {
"type": "object",
"properties": {
"property_name": {
"type": "string",
"example": "Department",
"description": "Name of the requested Custom Property"
},
"heatmap": {
"type": "array",
"items": {
"type": "object",
"properties": {
"property_value": {
"type": "string",
"description": "The value for the requested Custom Property by which Employees are grouped"
},
"skill_clusters": {
"type": "array",
"description": "List of relevant Skill Clusters",
"items": {
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The Skill Cluster for which the adoption was calculated"
},
"adoption": {
"type": "number",
"description": "The adoption of the accompanying Skill Cluster. A number between 0 and 1",
"minimum": 0,
"maximum": 1
}
}
}
}
}
},
"example": [
{
"property_value": "IT & Engineering",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"adoption": 0.6
},
{
"skill_cluster_name": "Programming Languages",
"adoption": 0.2
}
]
},
{
"property_value": "Sales",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"adoption": 0.1
},
{
"skill_cluster_name": "Programming Languages",
"adoption": 0.2
}
]
}
]
},
"skill_cluster_adoption": {
"type": "array",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"property_value": {
"type": "string",
"description": "The value of the group_by_custom_property for this Employee"
},
"assigned_position": {
"type": "string",
"description": "The assigned position of this Employee"
},
"skill_clusters": {
"type": "array",
"description": "List of relevant Skill Clusters",
"items": {
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "The name of the Skill Cluster"
},
"proficiency_level": {
"type": "number",
"minimum": 0,
"maximum": 3,
"description": "The proficiency level for this Skill Cluster, a level between 0 and 3."
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"property_value": "IT & Engineering",
"assigned_position": "Software Engineer",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"proficiency_level": 2
},
{
"skill_cluster_name": "DevOps",
"proficiency_level": 3
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"property_value": "Research",
"assigned_position": "NLP Engineer",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"proficiency_level": 2
}
]
}
]
},
"skill_breakdown": {
"type": "array",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"skill_clusters": {
"type": "array",
"description": "List of relevant Skill Clusters",
"items": {
"type": "object",
"properties": {
"skill_cluster_name": {
"type": "string",
"description": "Name of the Skill Cluster"
},
"skills": {
"type": "array",
"description": "List of Skills within the Skill Cluster for which the confidence levels are high for the given Employee",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the Skill"
}
}
}
}
}
}
}
}
},
"example": [
{
"external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a",
"skill_clusters": [
{
"skill_cluster_name": "Programming Languages",
"skills": [
{
"name": "Python"
},
{
"name": "Java"
}
]
},
{
"skill_cluster_name": "Artificial Intelligence",
"skills": [
{
"name": "Machine Learning"
},
{
"name": "Deep Learning"
}
]
}
]
},
{
"external_id": "61a6e076-d780-11ec-9d64-0242ac120002",
"skill_clusters": [
{
"skill_cluster_name": "Artificial Intelligence",
"skills": [
{
"name": "Deep Learning"
}
]
}
]
}
]
}
}
}
}
}
]
},
"EmployeesKeyMetrics": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "A Report containing the key metrics of all Employees.",
"properties": {
"report_name": {
"type": "string",
"example": "employees_key_metrics"
},
"report_data": {
"type": "object",
"description": "The key metrics of all Employees.",
"properties": {
"total_active": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees."
},
"total_active_with_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees with at least one Skill."
},
"total_active_with_validated_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees with at least one validated Skill."
},
"total_active_with_low_data_availability": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Employees with low data availability."
},
"validated_skills": {
"type": "object",
"description": "The distribution of validated and rejected Skills among active Employees.",
"properties": {
"total_confirmed_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of confirmed Skills among active Employees."
},
"total_rejected_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of rejected Skills among active Employees."
}
}
}
}
}
},
"example": {
"report_name": "employees_key_metrics",
"report_data": {
"total_active": 100,
"total_active_with_skill": 80,
"total_active_with_validated_skill": 60,
"total_active_with_low_data_availability": 10,
"validated_skills": {
"total_confirmed_skills": 50,
"total_rejected_skills": 10
}
}
}
}
]
},
"JobsKeyMetrics": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "A Report containing the key metrics of all Jobs.",
"properties": {
"report_name": {
"type": "string",
"example": "jobs_key_metrics"
},
"report_data": {
"type": "object",
"description": "The key metrics of all Jobs.",
"properties": {
"total_active": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs."
},
"total_active_with_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs with at least one Skill."
},
"total_active_with_validated_skill": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs with at least one validated Skill."
},
"total_active_with_low_data_availability": {
"type": "integer",
"minimum": 0,
"description": "The total number of active Jobs with low data availability."
},
"validated_skills": {
"type": "object",
"description": "The distribution of validated and rejected Skills among active Jobs.",
"properties": {
"total_confirmed_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of confirmed Skills among active Jobs."
},
"total_rejected_skills": {
"type": "integer",
"minimum": 0,
"description": "The total number of rejected Skills among active Jobs."
}
}
}
}
}
},
"example": {
"report_name": "jobs_key_metrics",
"report_data": {
"total_active": 100,
"total_active_with_skill": 80,
"total_active_with_validated_skill": 60,
"total_active_with_low_data_availability": 10,
"validated_skills": {
"total_confirmed_skills": 50,
"total_rejected_skills": 10
}
}
}
}
]
},
"EmployeeQualityMatrix": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Quality Matrix per data source and Skill Event type averaged over all Employees.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "employee_quality_matrix"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Employees uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_quality_matrix": {
"type": "array",
"description": "Data Quality Matrix metrics per data source and Skill Event type averaged over all Employees.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source system of the Skill Event. This is used to keep track of where Skill Events originate from.",
"example": "JIRA"
},
"event_type": {
"description": "Type of the Skill Event. Learn more about the Skill Event Types at [How it works](/technology/skill_events/).",
"type": "string",
"enum": [
"working_history",
"education_history",
"resume_document",
"learning",
"feedback",
"goal",
"project",
"ticket",
"certificate",
"skill_notes"
],
"example": "ticket"
},
"source_type": {
"type": "string",
"description": "The type of information this source adds:\n * ‘job-specific' indicates that the Skills extracted from\nthis source are generic across Employees having the same Job.\n * ‘employee-specific’ indicates that this source\ncontributes to the overall granularity of the Employees’ Skill Profiles.",
"enum": [
"job-specific",
"employee-specific"
],
"example": "employee-specific"
},
"source_coverage": {
"type": "number",
"format": "float",
"description": "The percentage of Employees that have at least one SkillEvent of this data source and type, that is considered coherent (i.e. it makes probabilistic sense for the Skills in the Event's Skill Profile to appear together).",
"example": 0.8
},
"empty_profile": {
"type": "number",
"format": "float",
"description": "The percentage of Skill Events of a data source and type for which no Skills have been found.",
"example": 0.05
},
"source_quality": {
"type": "number",
"format": "float",
"description": "The percentage of Skill Events of a data source and type that are considered coherent (i.e. it makes probabilistic sense for the Skills in the Event's Skill Profile to appear together). For example, it might indicate poor quality when the Skills ‘Recruiting’ and ‘Processing Invoices’ are tagged to the same learning event.",
"example": 0.85
},
"total_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of total Skills per Employee that could be inferred from the data source and type.",
"example": 45
},
"unique_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of unique Skills per Employee that could inferred from the data source and type.",
"example": 24
},
"source_differentation": {
"type": "number",
"format": "float",
"description": "Linked to the average number of Skills unique to the data source. If the model finds all Skills from the source in other sources, it does not add new Skills. Instead, it increases the confidence of Skills extracted from other sources. High differentiation means that almost all Skills from the source are new skills that are not found in the other sources.",
"example": 0.68
}
}
}
}
}
}
}
}
]
},
"JobQualityMatrix": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Quality Matrix, per data source and Job Profile Data type, averaged over all Jobs.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "job_quality_matrix"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Jobs uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_quality_matrix": {
"type": "array",
"description": "Data Quality Matrix metrics, per data source and Job Profile Data type, averaged over all Jobs.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source system of the Job Profile Data. This is used to keep track of where Job Profile Data originate from.",
"example": "Workday"
},
"event_type": {
"description": "Type of the Job Profile Data.",
"type": "string",
"enum": [
"job_description",
"job_title",
"vacancy",
"skill_notes"
],
"example": "job_title"
},
"source_type": {
"type": "string",
"description": "The type of information this source adds:\n * ‘market-specific' indicates that the Skills extracted\nfrom this source are based on external market data only available for this Job.",
"enum": [
"market-specific"
],
"example": "market-specific"
},
"source_coverage": {
"type": "number",
"format": "float",
"description": "The percentage of Jobs that have at least one Job Data item of this data source and type, that is considered coherent (i.e. it makes probabilistic sense for the Skills in the Job Data item's Skill Profile to appear together).",
"example": 0.8
},
"empty_profile": {
"type": "number",
"format": "float",
"description": "The percentage of Job Profile Data of a data source and type for which no Skills have been found.",
"example": 0.05
},
"source_quality": {
"type": "number",
"format": "float",
"description": "The percentage of Job Profile Data of a data source and type that are considered coherent (i.e. it makes probabilistic sense for the Skills in the Job Data item's Skill Profile to appear together). For example, it might indicate poor quality when the Skills ‘recruiting’ and ‘processing invoices’ are tagged to the same learning event.",
"example": 0.85
},
"total_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of total Skills per Job that were inferred from the data source and type.",
"example": 45
},
"unique_skill_volume": {
"type": "number",
"format": "integer",
"description": "The average number of unique Skills per Job that were inferred from the data source and type.",
"example": 24
},
"source_differentation": {
"type": "number",
"format": "float",
"description": "Linked to the average number of Skills unique to the data source. If the model finds all Skills from the data source in other sources, it does not add new skills. Instead, it increases the confidence of skills extracted from other sources. High differentiation means that almost all skills from the source are new skills that are not found in the other sources.",
"example": 0.68
}
}
}
}
}
}
}
}
]
},
"EmployeeMaturityOverview": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Maturity Overview over all Employees.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "employee_maturity_overview"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Employees uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_maturity_overview": {
"type": "array",
"description": "Data Maturity Overview flags for every Employee if sufficient data is available for qualitative Skill inference. Reasons are listed whenever not enough data is available.",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"reasons": {
"type": "array",
"description": "The data issues will result in insufficient data available:\n * `MIN_PROFILE_LENGTH` = less than 10 Skills are found in the final Skill Profile.\n * `MIN_SKILL_VOLUME_EVENTS` = less than 20 Skills are found across all available Skill Event sources.\n * `MAX_SKILL_GENERALITY` = more than 40% of all available Skill Event Skills are considered `generic`, occurring in the final Skill Profile of 25% of all other Jobs.\n * `MAX_SOURCE_GENERALITY` = more than 50% of the Skill Event sources are considered `generic`, mostly based on market data.\n * `MIN_EVENT_TYPE_DIVERSITY` = less than 3 unique Skill Event sources are available.",
"items": {
"type": "string",
"enum": [
"MIN_PROFILE_LENGTH",
"MIN_SKILL_VOLUME_EVENTS",
"MAX_SKILL_GENERALITY",
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
],
"example": [
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
]
}
},
"valid_assigned_position": {
"type": "boolean",
"description": "Whether the Employee has a valid assigned position (an existing Job). Only returned if `valid_assigned_position` is included in the request.",
"example": true
},
"has_business_data": {
"type": "boolean",
"description": "Whether the Employee has business data (Ticket or Project Skill Events). Only returned if `has_business_data` is included in the request.",
"example": true
},
"sufficient_working_history": {
"type": "boolean",
"description": "Whether the Employee has at least 3 years of working history with start and end dates filled in. Only returned if `sufficient_working_history` is included in the request.",
"example": false
}
}
}
}
}
}
}
}
]
},
"JobMaturityOverview": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "The Data Maturity Overview across all Jobs.",
"properties": {
"report_name": {
"type": "string",
"description": "Name of the report.",
"example": "job_maturity_overview"
},
"report_data": {
"type": "object",
"properties": {
"entity_count": {
"type": "number",
"description": "The number of Jobs uploaded to the tenant.",
"format": "integer",
"example": 100
},
"data_maturity_overview": {
"type": "array",
"description": "Data Maturity Overview flags for every Job if sufficient data is available for qualitative Skill inference. Reasons are listed whenever not enough data is available.",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
},
"low_data_availability": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether sufficient data is available for qualitative Skill inference for a given entity."
},
"reasons": {
"type": "array",
"description": "The data issues will result in insufficient data available:\n * `MIN_PROFILE_LENGTH` = less than 10 Skills are found in the final profile.\n * `MIN_SKILL_VOLUME_EVENTS` = less than 20 Skills are found across all available Job Profile Data sources.\n * `MAX_SKILL_GENERALITY` = more than 40% of all available Job Profile Data Skills are considered `generic`, occurring in the final profile of 25% of all other Jobs.\n * `MAX_SOURCE_GENERALITY` = more than 50% of the Job Profile Data sources are considered `generic`, mostly based on market data.\n * `MIN_EVENT_TYPE_DIVERSITY` = less than 3 unique Job Profile Data sources are available.",
"items": {
"type": "string",
"enum": [
"MIN_PROFILE_LENGTH",
"MIN_SKILL_VOLUME_EVENTS",
"MAX_SKILL_GENERALITY",
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
],
"example": [
"MAX_SOURCE_GENERALITY",
"MIN_EVENT_TYPE_DIVERSITY"
]
}
},
"job_data_count": {
"type": "object",
"description": "Count of Job Profile Data entries by type. Only returned if `job_data_count` is included in the request.",
"additionalProperties": {
"type": "integer"
},
"example": {
"Job Title": 1,
"Job Description": 2,
"Vacancy": 0
}
},
"data_distribution": {
"type": "object",
"description": "Distribution of Skills by data source origin. Only returned if `data_distribution` is included in the request.\n * `market_only` = Skills that only come from the Job title.\n * `market_aligned` = Skills that come from the Job title and at least one other data type.\n * `internal_only` = Skills that only come from internal data types (not Job title).",
"properties": {
"market_only": {
"type": "integer",
"description": "Number of Skills that only come from the Job title."
},
"market_aligned": {
"type": "integer",
"description": "Number of Skills that come from the Job title and at least one other data type."
},
"internal_only": {
"type": "integer",
"description": "Number of Skills that only come from internal data types."
}
},
"example": {
"market_only": 5,
"market_aligned": 10,
"internal_only": 8
}
}
}
}
}
}
}
}
}
]
},
"DataImprovementActions": {
"allOf": [
{
"description": "The base template for a report.",
"type": "object",
"properties": {
"report_name": {
"type": "string"
},
"report_data": {
"type": "object"
},
"last_update": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T11:45:49Z"
}
}
},
{
"type": "object",
"description": "An overview of suggested Data Improvement Actions over all Employees and Jobs.",
"properties": {
"report_name": {
"type": "string",
"example": "data_improvement_actions"
},
"report_data": {
"type": "object",
"properties": {
"data_improvement_actions": {
"type": "array",
"description": "A Data Improvement Action is an observed data issue for specific fields of Entities, Skill Events or Job Profile Data with an assessed impact of resolving the data issue.",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The source system of the Skill Event or Job Profile Data. This is used to keep track of where Skill Events or Job Profile Data originate from.",
"example": "JIRA"
},
"event_type": {
"description": "Type of the Skill Event or Job Profile Data.",
"type": "string"
},
"content_field": {
"type": "string",
"description": "The data field of the Skill Event or Job Profile Data in which the data issue occurs.",
"example": "ticket_description"
},
"observation": {
"type": "string",
"description": "Description of the data issue.",
"example": "Half of descriptions are too short (less than 300 characters)"
},
"impact": {
"type": "string",
"description": "Prioritisation suggestion on tackling the data issue.",
"enum": [
"High",
"Medium",
"Low"
],
"example": "High"
},
"count": {
"type": "integer",
"description": "The number of occurrences of this data issue.",
"example": 150
},
"examples": {
"oneOf": [
{
"title": "General Examples",
"description": "Example IDs of Skill Events or Job Profile Data where the observation is applicable.",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 5
},
{
"title": "Duplicate Data Examples",
"type": "object",
"required": [
"entity_count",
"example_ids"
],
"properties": {
"title": {
"type": "string",
"description": "Title of the duplicate example entities"
},
"description": {
"type": "string",
"description": "Description of the duplicate example entities"
},
"entity_count": {
"type": "integer",
"description": "Total number of duplicate example entities with this title and description"
},
"example_ids": {
"type": "array",
"description": "IDs of the duplicate example entities",
"items": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 20
}
},
"maxItems": 5
},
{
"title": "Working History Date Examples",
"description": "Example Employees with Working History Skill Events that have date issues (missing start date, missing end date, or identical start and end dates).",
"type": "array",
"items": {
"type": "object",
"required": [
"employee_id",
"event_ids"
],
"properties": {
"employee_id": {
"type": "string",
"description": "The external ID of the Employee with problematic Working History Skill Events.",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"event_ids": {
"type": "array",
"description": "IDs of the Working History Skill Events with date issues for this Employee.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "[a-zA-Z0-9_-]+"
},
"maxItems": 5
}
}
},
"maxItems": 5
}
]
}
}
}
}
}
}
}
}
]
},
"VacancyExplainedMatch": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"vacancy_id",
"score"
],
"properties": {
"vacancy_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "vacancy_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"description": "Detailed breakdown of the match score on Skill level.",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
},
"EmployeeExplainedMatch": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
},
"JobExplainedMatch": {
"allOf": [
{
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "Explained",
"type": "object",
"required": [
"missing_skills",
"present_skills"
],
"properties": {
"present_skills": {
"description": "A list of Skills that the Employee covers.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "adjacent_skill_1_id",
"description": "The uuid of the adjacent Skill.",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacency_score": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.8,
"description": "The adjacency score between the Skill and the adjacent Skill."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses.",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the required Skill."
},
"skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "required_skill_1_id",
"description": "The uuid of the required Skill.",
"pattern": "[a-zA-Z0-9_-]+"
}
}
}
]
}
}
}
}
]
},
"JobPropertiesSimpleMatch": {
"allOf": [
{
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
},
"JobPropertiesExplainedMatch": {
"allOf": [
{
"title": "Simple",
"description": "A job match result.",
"type": "object",
"required": [
"job_id",
"score"
],
"properties": {
"job_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "job_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"present_skills": {
"description": "A list of Skills that the Employee covers, with detailed skill information including criticality of the Skill, gap impact and required proficiency level for the Skill.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses, with detailed skill information including required proficiency level, criticality and gap impact.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
},
"EmployeePropertiesSimpleMatch": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesSimple",
"type": "object",
"required": [
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
}
}
}
]
},
"EmployeePropertiesExplainedMatch": {
"allOf": [
{
"title": "Simple",
"type": "object",
"required": [
"employee_id",
"score"
],
"properties": {
"employee_id": {
"allOf": [
{
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.",
"pattern": "[a-zA-Z0-9_-]+"
}
],
"example": "employee_1_id"
},
"score": {
"description": "The match score between the two entities",
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"example": 0.87657
}
}
},
{
"title": "PropertiesExplained",
"type": "object",
"required": [
"missing_skills",
"present_skills",
"overqualified"
],
"properties": {
"overqualified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the Employee is over-qualified for the Job. This is true when the Employee's skill level significantly exceeds the requirements."
},
"present_skills": {
"description": "A list of Skills that the Employee covers, with detailed skill information including required proficiency level, criticality and gap impact.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level of the Skill for the Employee."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"adjacent_skill_name": {
"type": "string",
"minLength": 1,
"example": "Artificial Intelligence",
"description": "The name of the adjacent Skill."
},
"adjacent_skill_id": {
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "5ad448e1-593a-442c-bd44-bf6b49159d06",
"description": "The universally unique ID of the adjacent 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
},
"adjacent_skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 4,
"description": "The proficiency level of the adjacent Skill for the Job."
},
"adjacency_score": {
"type": "number",
"format": "float",
"example": 1,
"description": "The adjacency score between the Skill and the adjacent Skill."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "medium",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
},
"missing_skills": {
"description": "A list of Skills that the Employee misses, with detailed skill information including required proficiency level, criticality and gap impact.",
"type": "array",
"items": {
"allOf": [
{
"description": "Default structure for an individual Skill.",
"type": "object",
"properties": {
"skill_name": {
"type": "string",
"minLength": 1,
"example": "Machine Learning",
"description": "The name of the Skill."
},
"skill_id": {
"title": "TechWolf Skill UUID",
"type": "string",
"format": "uuid",
"minLength": 1,
"maxLength": 100,
"example": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
"description": "The universally 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.\n",
"pattern": "[a-zA-Z0-9_-]+"
}
}
},
{
"properties": {
"skill_proficiency": {
"type": "integer",
"format": "int32",
"minimum": 1,
"example": 3,
"description": "The proficiency level required for the Skill by the Job."
},
"critical": {
"type": "boolean",
"example": true,
"description": "Indicates whether the Skill is critical for the Job."
},
"gap_impact": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high"
],
"example": "high",
"description": "The impact of the skill gap on the match score."
}
}
}
]
}
}
}
}
]
}
}
},
"x-tagGroups": [
{
"name": "API Documentation",
"tags": [
"Introduction",
"Authentication"
]
},
{
"name": "API Versioning",
"tags": [
"Versioning Overview",
"Breaking Changes",
"Deprecations",
"Compatible Changes"
]
},
{
"name": "Taxonomy",
"tags": [
"TaxonomyDomains",
"TaxonomySubdomains",
"TaxonomySkillClusters",
"TaxonomySkills",
"Taxonomy"
]
},
{
"name": "Employees",
"tags": [
"EmployeeCRUD",
"EmployeeProfile",
"EmployeeMetrics",
"EmployeeSearch",
"SkillEvents",
"EmployeeInteractions",
"EmployeeSuggestions"
]
},
{
"name": "Job Families",
"tags": [
"JobFamilyCRUD",
"JobFamilyProfile",
"Job Family Profile Data"
]
},
{
"name": "Jobs",
"tags": [
"JobCRUD",
"JobProfile",
"JobTaskProfile",
"Job Profile Data",
"JobIssues",
"JobChanges",
"JobSuggestions",
"JobMetrics"
]
},
{
"name": "Peer Groups",
"tags": [
"PeerGroups"
]
},
{
"name": "Vacancies",
"tags": [
"VacancyCRUD",
"VacancyProfile",
"VacancyMetrics",
"VacancySearch"
]
},
{
"name": "Courses",
"tags": [
"CourseCRUD",
"CourseProfile",
"CourseMetrics"
]
},
{
"name": "Skill Clusters",
"tags": [
"SkillClusterCRUD",
"SkillClusterProfile",
"SkillClusterMetrics"
]
},
{
"name": "External Companies",
"tags": [
"CompanyCRUD",
"CompanySearch"
]
},
{
"name": "Skills",
"tags": [
"Skill Search",
"Skill Gaps",
"Skill Lookup"
]
},
{
"name": "Tasks",
"tags": [
"TasksCRUD",
"TaskSearch",
"TaskValidation"
]
},
{
"name": "Organisational Structure",
"tags": [
"OrganisationalUnits"
]
},
{
"name": "Custom Properties",
"tags": [
"CustomPropertiesDefinitions",
"CustomPropertiesProperties"
]
},
{
"name": "Matchmaking",
"tags": [
"Vacancy Matching",
"Course Recommendations",
"External Company Matching",
"Job Matching",
"Job Family Matching",
"Task Matching",
"Match Feedback",
"Export Matching"
]
},
{
"name": "Matching Configuration",
"tags": [
"Filters"
]
},
{
"name": "Export",
"tags": [
"ExportEmployeesSkillClusters",
"JobArchitectureExport",
"CoursesExportSkillProfiles",
"VacanciesExportSkillProfiles",
"ExportEmployeeAssignedPosition",
"TaxonomyExport",
"ExportTasks",
"OrganisationalStructureExport"
]
},
{
"name": "Reports",
"tags": [
"General Reports",
"Employee Reports",
"Vacancy Reports",
"Job Reports",
"Data Maturity Scan"
]
},
{
"name": "Version",
"tags": [
"Version"
]
}
]
}