Skill Engine API (2021-04-13)

Download OpenAPI specification:Download

The Skill Engine API is your single stop for continuous skill tracking, matching, learning management and strategic insights. This API specification describes how to augment your existing data sources with skills to build your workforce of tomorrow.

Authentication

The Skill Engine API uses OAuth2 for authentication. You'll receive a client_id, client_secret, audience and tenant from TechWolf,that you can use to receive an Authorization token. With these credentials, you can request a token at https://techwolf.eu.auth0.com/oauth/token with grant_type client_credentials.

An example request is as follows:


curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \

-H 'accept: application/json'  \

-H 'Content-Type: application/json' \

-d '{"client_id": "abcd12317icwFq2x3f4v4BZlQ2sB5q2i2E",
    "client_secret": "abcd1234JViv17icwFq2x3f4v4BZlQ2sB5q2i2E",
    "audience": "eu3.techwolf.ai",
    "grant_type": "client_credentials",
    "tenant": "company_xyz"}'

The response will contain an access_token, which has a limited lifetime:


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

If you're not using a standard OAuth2 client, make sure to store this token and reuse it until it expires.

In the subsequent API calls you can authorize using the access_token by including the header Authorization: Bearer {access_token}. The access is limited to endpoints for which your token has a scope. (e.g. when you receive a token with the read scope, you cannot execute write calls (POST, PUT, DELETE) with this token)

For example, to retrieve the list of employee ids available in the system, you can execute the following request:


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

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

Versioning Overview

The SkillEngine API is a date-based versioned API system, such that each integrator interacts with a certain version of our product. To know your own version, you can call the version-endpoint (description can be found below).

Your version is set by us at the time your tenant is created. This version controls how your API will behave (in terms of supported parameters, response formats, etc.).

As it is possible that we introduce breaking changes in future updates that may break your code, we will not update your version unless you specifically request this. Breaking changes will always be released under a new date and can be tracked in the documentation below.

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

In case you want to test a specific version of the API, e.g. when switching versions, you can add the header X-API-Version to your requests. The value of this header is the version of the API you want to use, for example 2021-03-19.

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

Compatible Changes

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

April 2021

  • Add strict parameter to entity creation and update operations (Employees, Competencies, Courses, Documents, Occupations, Vacancies)
  • Change the outward facing side of (non-)desired functions during Employee creation. Output and input now better reflect internal results
  • Add languages field to Companies
  • You can now add a geo distance weight to the matching endpoints. Match scores are increased when two entities are in proximity to each other.
  • You can now add custom property weights to the matching endpoints. Match scores are increased when the applied condition on the matching entities' specified custom property checks out.

March 2021

  • You can now specify the non-desired functions when creating or updating an Employee to take their negative preference into account when matching to new positions.
  • You can now modify the non-desired functions boost used during matching by setting the appropriate weight on the match endpoints employees/{external_id}/matching_vacancies and vacancies/{external_id}/matching_employees.
  • You can now submit multiple desired functions linked to a given Company through a single multiline string using the new request_format=free_text query parameter on the /companies/{external_id}/desired_functions endpoint.
  • You can now submit free text, multiline strings desired functions & non-desired functions for an Employee through the desired_functions & non_desired_functions attributes.
  • You can now search for Vacancies and Companies based on free text, through the endpoints /vacancies/search and /companies/search.
  • You can now add datetime-typed custom properties.
  • You can now provide a list of filters when searching for entities using free text through the endpoints /employees/search, /vacancies/search and /companies/search.
  • You can now provide multiple values (as a list) when using the custom_property_contains_element filter. Entities will not be filtered out if they contain at least one of the provided values in the list custom property.
  • You can now specify the comparison operator when using the custom_property filter. If no operator is specified, the filter defaults to the equals operator.
  • You can now specify an offset on matching endpoints for employees,vacancies and companies
  • You can now specify an offset on search endpoints for employees,vacancies and companies
  • You can now pass the null value for optional fields during creation and updating of all entities. Passing the null value during an update will unset the entity's attribute. Objects will be unset as null, arrays as the empty array [] and strings as the empty string ''.
  • Companies now support custom properties.
  • (Non-)desired function score boosting is now calculated relative to the relevancy of the function title, instead of a binary boost on occurrence of a title
  • You can now provide a list of filters at the match endpoints employees/{external_id}/matching_companies and companies/{external_id}/matching_employees. This will be used to filter out entities that do not need to be considered during matching.
  • You can now provide a list of weights at the match endpoints employees/{external_id}/matching_companies and companies/{external_id}/matching_employees. The weights can override some default weights during matching (e.g. desired functions boost).
  • Custom property definitions are no longer allowed to contain double underscores in their name.
  • You can now set the weight of the skills-related match component contributing to the final match score (this was previously hard-coded to 1.0)
  • You can now filter on the custom properties of companies linked to a vacancy, when matching employees to vacancies and vice versa.

February 2021

  • You can now search for Employees based on free text, through the endpoint /employees/search.
  • You can add an (optional) Company link to a Vacancy, through the endpoint /vacancies and attribute company.
  • You can now list, create, retrieve, update and delete Companies through the endpoints /companies/*.
  • You can now optionally mark Vacancies as inactive using the field active. When this is field has the value False, the Vacancy will not be used for matching.
  • Deleting Companies now deletes all linked inactive Vacancies in cascade.
  • You can now find the best Employees for a given Company with an overview of its matching Vacancies, through the endpoint /companies/{external_id}/matching_employees.
  • You can now find the best Companies for a given Employee with an overview of the matching Vacancies per Company, through the endpoint /employees/{external_id}/matching_companies.
  • You can now upload desired functions as inactive Vacancies linked to a given Company, through the endpoint /companies/{external_id}/desired_functions.
  • You can now see when an entity was last updated by checking the attribute last_updated upon entity retrieval.
  • You can now provide a list of filters at the match endpoints employees/{external_id}/matching_vacancies and vacancies/{external_id}/matching_employees. This will be used to filter out entities that do not need to be considered during matching.
  • You can now provide a list of languages with proficiency levels during Vacancy creation.
  • You can now provide a list of weights at the match endpoints employees/{external_id}/matching_vacancies and vacancies/{external_id}/matching_employees. The weights can override some default weights during matching (e.g. desired functions boost).
  • The POST-type methods on matching_vacancies and matching_employees are now the preferred way to request the matches.
  • You can now add a list of strings as a Custom Property.
  • You can now explicitly provide the language used in skill profile extraction during entity creation/update using the language query parameter. Supported languages are auto, nl, fr and en.
  • You can now optionally add a job description to the entries in the working_history of an Employee. These descriptions will also be used for skill extraction.

January 2021

  • You can add a (optional) max_geo_distance attribute when creating an Employee through the endpoint /employees. This is used for matching if there is no max_geo_distance provided as query parameter. The default distance in our system when nothing is provided, is 50 km.

Breaking Changes

2021-03-19

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

2021-02-25

  • Employee creation (POST /employees) and updates (PATCH /employees/{external_id}) no longer support uploading individual resumes (as employee_resume) in favour of accepting a list of multiple resumes (as employee_documents) with the same format.

2021-02-03

  • The list entity endpoints (GET /employees, GET /vacancies, GET /courses, GET /occupations, GET /competencies and GET /documents) no longer support the response_format query parameter. The response now corresponds to the former objects response format for all endpoints.

2021-01-19

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

CRUD

List Employees

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

Authorizations:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100
Example: limit=50

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

offset
integer >= 0
Default: 0

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

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Employee

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

Authorizations:
application (write)
query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

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

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

object Nullable

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

assigned_position
string (AssignedPosition) [ 1 .. 255 ] characters Nullable

Job title of the Employee's assigned position.

max_geo_distance
number <float> > 0 Nullable

The maximal allowed distance (in km, as the crow flies) for matching with vacancies.

Array of objects (WorkExperience) Nullable
Array of objects (Education) Nullable
Array of objects (Language) Nullable

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. If you want to leave this field empty, make sure to submit an empty list. This field can be filled automatically based on the resume (when present).

desired_functions
Array of strings Nullable

List of desired function titles of the Employee. Elements can be either a single-line string or free text

non_desired_functions
Array of strings Nullable

List of non-desired function titles of the Employee. Elements can be either a single-line string or free text

Array of objects (Certificate) Nullable

List of obtained certificates by the Employee, combined with an expiry date. If the expiry date is omitted, it is assumed that the certificate never expires.

Array of objects (EmployeeResume) Nullable

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

Responses

Request samples

Content type
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "location": {
    },
  • "assigned_position": "Python Developer",
  • "max_geo_distance": 50,
  • "working_history": [
    ],
  • "education_history": [
    ],
  • "languages": [
    ],
  • "desired_functions": [
    ],
  • "non_desired_functions": [
    ],
  • "certificates": [
    ],
  • "employee_documents": [
    ]
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get Employee

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

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
include
Array of strings
Items Value: "custom_properties"
Example: include=custom_properties

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

Responses

Response samples

Content type
application/json
Example
{
  • "last_updated": "2021-01-21T17:32:28.000Z",
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "location": {
    },
  • "assigned_position": "Python Developer",
  • "max_geo_distance": 50,
  • "working_history": [
    ],
  • "education_history": [
    ],
  • "languages": [
    ],
  • "desired_functions": [
    ],
  • "non_desired_functions": [
    ],
  • "certificates": [
    ]
}

Update Employee

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

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

Passing the null value unsets non-required attributes. Objects will be unset as null, arrays as the empty array [] and strings as the empty string ''.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

Request Body schema: application/json
object Nullable

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

assigned_position
string (AssignedPosition) [ 1 .. 255 ] characters Nullable

Job title of the Employee's assigned position.

max_geo_distance
number <float> > 0 Nullable

The maximal allowed distance (in km, as the crow flies) for matching with vacancies.

Array of objects (WorkExperience) Nullable
Array of objects (Education) Nullable
Array of objects (Language) Nullable

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. If you want to leave this field empty, make sure to submit an empty list. This field can be filled automatically based on the resume (when present).

desired_functions
Array of strings Nullable

List of desired function titles of the Employee. Elements can be either a single-line string or free text

non_desired_functions
Array of strings Nullable

List of non-desired function titles of the Employee. Elements can be either a single-line string or free text

Array of objects (Certificate) Nullable

List of obtained certificates by the Employee, combined with an expiry date. If the expiry date is omitted, it is assumed that the certificate never expires.

Array of objects (EmployeeResume)

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

Responses

Request samples

Content type
application/json
{
  • "location": {
    },
  • "assigned_position": "Python Developer",
  • "max_geo_distance": 50,
  • "working_history": [
    ],
  • "education_history": [
    ],
  • "languages": [
    ],
  • "desired_functions": [
    ],
  • "non_desired_functions": [
    ],
  • "certificates": [
    ],
  • "employee_documents": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Employee

Remove an Employee from the system. This step deletes all information linked exclusively to this Employee, while leaving other (potentially linked) entities such as documents authored by the user. If these need to be removed as well, make sure to do this separately. By deleting an Employee, you delete their skill profile history, which cannot be recreated or recovered afterwards.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all Custom Property Definitions

Get a list of all the Custom Property Definitions stored inside the system.

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a Custom Property Definition

Create a new Custom Property Definition in the system.

Authorizations:
application (write)
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

property_type
required
string non-empty
Enum: "text" "number" "boolean" "list[text]" "datetime"

Expected type of the custom property.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Custom Property Definition

Get the Custom Property Definition information stored inside the system.

Authorizations:
application (read)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Rename a Custom Property Definition

Rename a Custom Property Definition.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector"
}

Response samples

Content type
application/json
[
  • {
    }
]

Remove a Custom Property Definition from the system

Remove a Custom Property Definition from the system.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all custom Employee properties

Fetch all Employee properties from the system (if any exists, otherwise an empty list is returned).

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Replace custom Employee properties

In addition to the default fields available for each Employee, a set of custom properties can be added. Each Employee is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Update custom Employee properties

In addition to the default fields available for each Employee, a set of custom properties can be added. Each Employee is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Delete all custom Employee properties

Drop all Employee properties from the system (if any exists).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Skill Profile

Get the skill profile for an Employee

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

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
response_format
string
Default: "list"
Enum: "list" "trending" "competencies"
Example: response_format=list

The format in which the skill profile needs to be returned. List returns the skills, trending indicates per skill if it is trending and competencies return the skill profile in your own Competencies. More info about adding your Competencies can be found in the tutorials.

Responses

Response samples

Content type
application/json
Example
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "skills": [
    ]
}

Update an Employee skill profile with feedback

Provide feedback about an existing Employee skill profile to update it inside the system. The body of the feedback message replaces the existing skill profile, so if a skill is not present in the body or has weight 0, it will be removed. The feedback can contain updates (e.g. score changes or skills added through related skills / skill search) and removals. The feedback_format query parameter indicates the format in which the feedback is given (currently skills and competencies). Typically used to process insights gained from end users through a front-end application.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
feedback_format
string
Default: "skills"
Enum: "skills" "competencies"
Example: feedback_format=skills

The format in which feedback for the skill profile is given.

Request Body schema: application/json
One of
Array of objects (SkillWithScoreArray)

The skills contained in this profile, along with their scores.

Responses

Request samples

Content type
application/json
Example
{
  • "skills": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Metrics

Get the employability metric

Retrieve the employability for this Employee. Employability is an indication of the extent to which an Employee fits the open Vacancies within your company. It is reported as a number between 0 and 1, with the upper end indicating that an Employee has many matching opportunities, while a lower score indicates fewer opportunities (or only lower-quality matches) are available.

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
{
  • "entity_type": "Employee",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "employability",
  • "metric_value": 0.8,
  • "last_update": "2020-09-01T11:45:49Z"
}

Get Employee count

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

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
{
  • "entity_type": "Employee",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "count",
  • "metric_value": 1000,
  • "last_update": "2020-09-01T11:45:49Z"
}

Get the position alignment metric

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

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
response_format
string
Default: "simple"
Enum: "simple" "explained"
Example: response_format=simple

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

Responses

Response samples

Content type
application/json
Example
{
  • "entity_type": "Employee",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "position_alignment",
  • "metric_value": 0.8,
  • "last_update": "2020-09-01T11:45:49Z"
}

Search

Search for Employees based on free text

Search for Employees

Authorizations:
application (read)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

The maximal number of results returned.

offset
integer >= 0
Default: 0

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

Request Body schema: application/json
text
required
string

Input text.

object (Location)

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

required
Array of MaxGeoDistanceFilter (object) or CustomPropertyFilter (object) or CustomPropertyIsInListFilter (object) or CustomPropertyContainsElementFilter (object) (SingleEntityFilterList)

Responses

Request samples

Content type
application/json
{
  • "text": "Bakery",
  • "location": {
    },
  • "filters": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

CRUD

List Vacancies

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.

Authorizations:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100
Example: limit=50

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

offset
integer >= 0
Default: 0

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

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Vacancy

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

Authorizations:
application (write)
query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

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

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

job_title
required
string non-empty

Title of the Job.

job_description
required
string non-empty

Textual description of the Job (job posting).

active
boolean Nullable

If false, the vacancy won't be used for matching. Used to mark historic data.

object Nullable

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

company
string <uuid> non-empty Nullable [a-zA-Z0-9_-]+

external_id from the Company the Vacancy is linked to.

Array of objects (Language) Nullable

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.

Responses

Request samples

Content type
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "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.",
  • "active": true,
  • "location": {
    },
  • "company": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "languages": [
    ]
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get Vacancy

Get the Vacancy information stored inside the system.

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
include
Array of strings
Items Value: "custom_properties"
Example: include=custom_properties

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

Responses

Response samples

Content type
application/json
Example
{
  • "last_updated": "2021-01-21T17:32:28.000Z",
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "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.",
  • "active": true,
  • "location": {
    },
  • "company": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "languages": [
    ]
}

Update Vacancy

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.

Passing the null value unsets non-required attributes. Objects will be unset as null, arrays as the empty array [] and strings as the empty string ''.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

Request Body schema: application/json
job_title
string non-empty

Title of the Job.

job_description
string non-empty

Textual description of the Job (job posting).

active
boolean Nullable

If false, the vacancy won't be used for matching. Used to mark historic data.

object Nullable

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

company
string <uuid> non-empty Nullable [a-zA-Z0-9_-]+

external_id from the Company the Vacancy is linked to.

Array of objects (Language) Nullable

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.

Responses

Request samples

Content type
application/json
{
  • "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.",
  • "active": true,
  • "location": {
    },
  • "company": "b3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "languages": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Vacancy

Remove a Vacancy from the system. This step deletes all information linked exclusively to this Vacancy, while leaving other (potentially linked) entities such as documents authored by the user. 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.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all Custom Property Definitions

Get a list of all the Custom Property Definitions stored inside the system.

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a Custom Property Definition

Create a new Custom Property Definition in the system.

Authorizations:
application (write)
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

property_type
required
string non-empty
Enum: "text" "number" "boolean" "list[text]" "datetime"

Expected type of the custom property.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Custom Property Definition

Get the Custom Property Definition information stored inside the system.

Authorizations:
application (read)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Rename a Custom Property Definition

Rename a Custom Property Definition.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector"
}

Response samples

Content type
application/json
[
  • {
    }
]

Remove a Custom Property Definition from the system

Remove a Custom Property Definition from the system.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all custom Vacancy properties

Fetch all Vacancy properties from the system (if any exists, otherwise an empty list is returned).

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Replace custom Vacancy properties

In addition to the default fields available for each Vacancy, a set of custom properties can be added. Each Vacancy is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Update custom Vacancy properties

In addition to the default fields available for each Vacancy, a set of custom properties can be added. Each Vacancy is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Delete all custom Vacancy properties

Drop all Vacancy properties from the system (if any exists).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Skill Profile

Get the skill profile for a Vacancy

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!

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
response_format
string
Default: "list"
Enum: "list" "trending" "competencies"
Example: response_format=list

The format in which the skill profile needs to be returned. List returns the skills, trending indicates per skill if it is trending and competencies return the skill profile in your own Competencies. More info about adding your Competencies can be found in the tutorials.

Responses

Response samples

Content type
application/json
Example
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "skills": [
    ]
}

Update a Vacancy skill profile with feedback

Provide feedback about an existing Vacancy skill profile to update it inside the system. The body of the feedback message replaces the existing skill profile, so if a skill is not present in the body or has weight 0, it will be removed. The feedback can contain updates (e.g. score changes or skills added through related skills / skill search) and removals. The feedback_format query parameter indicates the format in which the feedback is given (currently skills and competencies). Typically used to process insights gained from end users through a front-end application.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
feedback_format
string
Default: "skills"
Enum: "skills" "competencies"
Example: feedback_format=skills

The format in which feedback for the skill profile is given.

Request Body schema: application/json
One of
Array of objects (SkillWithScoreArray)

The skills contained in this profile, along with their scores.

Responses

Request samples

Content type
application/json
Example
{
  • "skills": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Metrics

Get Vacancy count

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

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
{
  • "entity_type": "Vacancy",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "count",
  • "metric_value": 1000,
  • "last_update": "2020-09-01T11:45:49Z"
}

Search

Search for Vacancies based on free text

Search for Vacancies

Authorizations:
application (read)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

The maximal number of results returned.

offset
integer >= 0
Default: 0

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

Request Body schema: application/json
text
required
string

Input text.

object (Location)

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

required
Array of MaxGeoDistanceFilter (object) or CustomPropertyFilter (object) or CustomPropertyIsInListFilter (object) or CustomPropertyContainsElementFilter (object) (SingleEntityFilterList)

Responses

Request samples

Content type
application/json
{
  • "text": "Bakery",
  • "location": {
    },
  • "filters": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

CRUD

List Courses

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.

Authorizations:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100
Example: limit=50

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

offset
integer >= 0
Default: 0

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

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Course

Submit new Course information to initialise its Skill Profile inside the Skill Engine API.

Authorizations:
application (write)
query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

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

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

course_title
required
string non-empty

Title of the Course.

course_description
required
string non-empty

Textual description of the Course.

Responses

Request samples

Content type
application/json
{
  • "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."
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get Course

Get the Course information stored inside the system.

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
include
Array of strings
Items Value: "custom_properties"
Example: include=custom_properties

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

Responses

Response samples

Content type
application/json
Example
{
  • "last_updated": "2021-01-21T17:32:28.000Z",
  • "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."
}

Update Course

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.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

Request Body schema: application/json
course_title
string non-empty

Title of the Course.

course_description
string non-empty

Textual description of the Course.

Responses

Request samples

Content type
application/json
{
  • "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."
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Course

Remove a Course from the system. This step deletes all information linked exclusively to this Course and cannot be undone.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all Custom Property Definitions

Get a list of all the Custom Property Definitions stored inside the system.

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a Custom Property Definition

Create a new Custom Property Definition in the system.

Authorizations:
application (write)
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

property_type
required
string non-empty
Enum: "text" "number" "boolean" "list[text]" "datetime"

Expected type of the custom property.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Custom Property Definition

Get the Custom Property Definition information stored inside the system.

Authorizations:
application (read)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Rename a Custom Property Definition

Rename a Custom Property Definition.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector"
}

Response samples

Content type
application/json
[
  • {
    }
]

Remove a Custom Property Definition from the system

Remove a Custom Property Definition from the system.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all custom Course properties

Fetch all Course properties from the system (if any exists, otherwise an empty list is returned).

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {},
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Update custom Course properties

In addition to the default fields available for each Course, a set of custom properties can be added. Each Course is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {},
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Replace custom Course properties

In addition to the default fields available for each Course, a set of custom properties can be added. Each Course is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {},
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Delete all custom Course properties

Drop all Course properties from the system (if any exists).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Skill Profile

Get the skill profile for a Course

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!

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
response_format
string
Default: "list"
Enum: "list" "trending" "competencies"
Example: response_format=list

The format in which the skill profile needs to be returned. List returns the skills, trending indicates per skill if it is trending and competencies return the skill profile in your own Competencies. More info about adding your Competencies can be found in the tutorials.

Responses

Response samples

Content type
application/json
Example
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "skills": [
    ]
}

Update a Course skill profile with feedback

Provide feedback about an existing Course skill profile to update it inside the system. The body of the feedback message replaces the existing skill profile, so if a skill is not present in the body or has weight 0, it will be removed. The feedback can contain updates (e.g. score changes or skills added through related skills / skill search) and removals. The feedback_format query parameter indicates the format in which the feedback is given (currently skills and competencies). Typically used to process insights gained from end users through a front-end application.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
feedback_format
string
Default: "skills"
Enum: "skills" "competencies"
Example: feedback_format=skills

The format in which feedback for the skill profile is given.

Request Body schema: application/json
One of
Array of objects (SkillWithScoreArray)

The skills contained in this profile, along with their scores.

Responses

Request samples

Content type
application/json
Example
{
  • "skills": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Metrics

Get Course count

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

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
{
  • "entity_type": "Course",
  • "entity_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "metric_name": "count",
  • "metric_value": 1000,
  • "last_update": "2020-09-01T11:45:49Z"
}

CRUD

List Occupations

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

Authorizations:
application (read)
query Parameters
limit
integer [ 1 .. 200 ]
Default: 100
Example: limit=50

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

offset
integer >= 0
Default: 0

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

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "results": [
    ]
}

Create Occupation

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

Authorizations:
application (write)
query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

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

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

occupation_name
required
string non-empty

Title of the Occupation.

occupation_description
required
string non-empty

Textual description of the Occupation.

occupation_titles
Array of strings Nullable

A list of alternate names for the occupation

Responses

Request samples

Content type
application/json
{
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "occupation_name": "Python Developer",
  • "occupation_description": "Developer that is skilled at the Python language.",
  • "occupation_titles": [
    ]
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get Occupation

Get the Occupation information stored inside the system.

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
include
Array of strings
Items Value: "custom_properties"
Example: include=custom_properties

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

Responses

Response samples

Content type
application/json
Example
{
  • "last_updated": "2021-01-21T17:32:28.000Z",
  • "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
  • "occupation_name": "Python Developer",
  • "occupation_description": "Developer that is skilled at the Python language.",
  • "occupation_titles": [
    ]
}

Update Occupation

Submit the most up to date Occupation 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.

Passing the null value unsets non-required attributes. Objects will be unset as null, arrays as the empty array [] and strings as the empty string ''.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
language
string
Default: "auto"
Enum: "auto" "nl" "fr" "en"
Example: language=en

The language used in skill extraction. auto will automatically detect the language used in the provided data.

strict
boolean
Default: true

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

Request Body schema: application/json
occupation_name
string non-empty

Title of the Occupation.

occupation_description
string non-empty

Textual description of the Occupation.

occupation_titles
Array of strings Nullable

A list of alternate names for the occupation

Responses

Request samples

Content type
application/json
{
  • "occupation_name": "Python Developer",
  • "occupation_description": "Developer that is skilled at the Python language.",
  • "occupation_titles": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Occupation

Remove a Occupation from the system. This step deletes all information linked exclusively to this Occupation, while leaving other (potentially linked) entities such as documents authored by the user. If these need to be removed as well, make sure to do this separately. By deleting a Occupation, you delete their skill profile history, which cannot be recreated or recovered afterwards.

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all Custom Property Definitions

Get a list of all the Custom Property Definitions stored inside the system.

Authorizations:
application (read)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a Custom Property Definition

Create a new Custom Property Definition in the system.

Authorizations:
application (write)
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

property_type
required
string non-empty
Enum: "text" "number" "boolean" "list[text]" "datetime"

Expected type of the custom property.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Custom Property Definition

Get the Custom Property Definition information stored inside the system.

Authorizations:
application (read)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
{
  • "property_name": "sector",
  • "property_type": "text"
}

Rename a Custom Property Definition

Rename a Custom Property Definition.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector
Request Body schema: application/json
property_name
required
string non-empty

The name of the custom property. Can not contain '__'.

Responses

Request samples

Content type
application/json
{
  • "property_name": "sector"
}

Response samples

Content type
application/json
[
  • {
    }
]

Remove a Custom Property Definition from the system

Remove a Custom Property Definition from the system.

Authorizations:
application (write)
path Parameters
property_name
required
string non-empty
Example: sector

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all custom Occupation properties

Fetch all Occupation properties from the system (if any exists, otherwise an empty list is returned).

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Replace custom Occupation properties

In addition to the default fields available for each Occupation, a set of custom properties can be added. Each Occupation is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Update custom Occupation properties

In addition to the default fields available for each Occupation, a set of custom properties can be added. Each Occupation is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Request Body schema: application/json
Array ([ 1 .. 100 ] items)
property_name
string non-empty
boolean or (Number (integer or number)) or (Date (string or string)) or string or Array of strings

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "title": "400 Bad Request",
  • "description": "The request body was not structured correctly."
}

Delete all custom Occupation properties

Drop all Occupation properties from the system (if any exists).

Authorizations:
application (write)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Skill Profile

Get the skill profile for a Occupation

Get an export of the Occupation 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!

Authorizations:
application (read)
path Parameters
external_id
required
string <uuid> (UUID) non-empty [a-zA-Z0-9_-]+
Example: a3903505-eb84-42dc-a79f-5e7b1fe897b7

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

query Parameters
response_format
string
Default: "list"
Enum: "list" "trending" "competencies"
Example: response_format=list

The format in which the skill profile needs to be returned. List returns the skills, trending indicates per skill if it is trending and competencies return the skill profile in your own Competencies. More info about adding your Competencies can be found in the tutorials.

Responses

Response samples

Content type
application/json
Example
{
  • "external_id":