Skip to content
Skills Intelligence

Compare to Profession🔗

The /skills/compare_to_profession endpoint allows to compare a set of skills of a candidate to the skill set related to a target profession.

NOTE that the skill set used to determine the "common skills" is a larger set than the skills that the /suggest_skills endpoint returns. This is done to ensure also less salient skills are listed as common ones if they are related to both professions. That means that the "common skills" don't necessarily align with the suggested skills.


Method Media URL
POST application/json

Input parameters🔗

Parameter Type Default Description
skill_code_ids list str OR list Skill None (required) The skill code IDs which should be compared against the given profession. The list can contain up to 50 skill codes.
The skills can be either a list of str, or a list of Skill objects, as described in the section below. The Skill object allows to add a skill score that will be applied as weight.
profession_code_id list str None (required) The profession code IDs to compare the skill set to.
output_language str None (optional) Parameter to set the language of the returned descriptions.
If not set, the service will return no descriptions. Expects a language in ISO 639-1 format (e.g. "en", "nl").

Skill object🔗

The Skill object is an object that contains a code_id, a score and optionally a description. This object is used in all skill-based requests and responses of the Ontology Service. Therefore, the response skills of one endpoint are immediately portable to the request for the next.

Property Type Required? Description
code_id str Yes The code ID of the skill. This should be a valid code ID from the TK taxonomy.
score float Yes The score or weight of a skill. In responses this means the score of the output. In requests this means the weight that will be applied to the skill. This must be a value in the range [0 - 1]
description str No Description label of the skill. Does not have any effect in requests.

Using the score property to weight input skills🔗

The score property in requests determines the weight of a skill in the input. A logical use case of this property would for example be to translate a candidate's proficiency level for that skill to a weight. When the request contains a list of Skill objects, supplying scores for all skills is mandatory. When the request contains a list of str objects, all skills are weighted equally.

The score values need to be in the range [0 - 1]. For example, if your data model uses proficiency levels [1, 2, 3, 4, 5], they should be translated into weights [0.2, 0,4, 0.6, 0.8, 1.0].

The weights are relative, so SKILL_A.weight = 0.2 and SKILL_B.weight = 0.4 is equivalent to SKILL_A.weight = 0.5 and SKILL_B.weight = 1.0.


Status Content type Content description
200 (OK) application/json A JSON object containing:
  • suggested_professions: the list of related skills with their relation strength
  • meta: meta information of the service version
400 (Bad request) The input request body is incorrect
422 (Validation error) The profession code ID is not a valid code ID in the Textkernel profession taxonomy or none of the skill codes are valid codes in the Textkernel skill taxonomy.


Using skill codes as a list of str:

curl -X POST "" \
        -H "Authorization: Bearer $TOKEN"\
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -d "{\"skill_code_ids\": [\"KS04QIYB82UAEDED1GIQ\", \"KS04UWLJBN9X1M3N0PZ4\"], \"profession_code_id\": \"696\"}"

Using a list of Skill objects:

curl -X POST "" \
        -H "Authorization: Bearer $TOKEN"\
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -d \"skill_code_ids\": [{\"code_id\": \"KS123KG6DL8N3D5ZW036\", \"score\": 0.8}, {\"code_id\": \"KS123CW67MS8YB3L3FP3\", \"score\": 0.2}], \"profession_code_id\": \"696\"}"


  "meta": {
    "service_version": "0.0.9",
    "taxonomy_release": "2021-07-21"
  "warnings": null,
  "similarity_score": 0.03435295632587281,
  "common_skills": [
      "score": 0.988187958388946,
      "code_id": "KS120076FGP5WGWYMP0F"
  "exclusive_skills": {
    "696": [
        "score": 0.9651344675938166,
        "code_id": "KS124PR62MV42B5C9S9F"
        "score": 0.9649344434730116,
        "code_id": "KS125HH5XDBPZT3RFGZZ"
    "input_skills": [
        "score": 1,
        "code_id": "KS04QIYB82UAEDED1GIQ"

Response fields🔗

Field Type Value
similarity_score float A similarity score between the skill set and profession. The score is a value in the range [0 - 1].
common_skills list skill List of common skills between skill set and profession.
exclusive_skills map List of exclusive skills for the profession and the input skill set. The profession skill set will be denoted as its code ID. The input skill set will be denoted as input_skills.
skill.code_id str The code ID of the related Skill in the Textkernel Skill taxonomy.
skill.score float An association score indicating the relationship strength. The score is a value in the range [0 - 1].
skill.description str The skill description as per the TK taxonomy in the specified output_language. Will only be returned if output_language is specified.

Rate limits🔗

Accounts have a limited request rate. If you exceed the limit you will receive 429 Too Many Requests HTTP responses.

Plan Limit Units
Standard 1000 Minute
Demo 30 Minute

Remember to send your authentication token with each request (see Authentication).