Introduction
General information
Deprecation Notice: The Classic API, though currently functional, is built on older architecture and may be subject to future deprecation or significant changes. While it currently offers a wider range of features than the new API, certain endpoints or functionalities might be phased out over time. If you rely on the Classic API for critical processes, be sure to regularly review updates, release notes, and migration timelines to mitigate the risk of disruption to your integrations.
API Overview
The API works based on HTTP status codes. We have described in one of the next chapters all the information about the HTTP status codes, what they mean, and in which type of situation they are used. We have a default part of an error message if we are sending something back with an HTTP status code. Each error has its own code which can be found in this documentation to give you detailed information about the error.
API URL
The API URL is always built like:
https://{domain}/api/{version}/{controller}/{action}
All calls and results in this document are described in the JSON format.
Default Result Message
All result messages are in the JSON format. If we return messages, they have the following format. We serialize the object to JSON:
{
"id": 1,
"name": "EnVision",
"email": "[email protected]"
}
Default Error Message Part
Below, we have described the default part for the error:
{
"code": 1234,
"message": "Something went wrong",
"description": "More details about the error here"
}
HTTP Status Codes
Below is a description of which HTTP status code we use and in which situation:
- 200 OK – Response to a successful GET.
- 201 Created – Response to a POST that results in a creation. The URL to the new resource is in the Location header.
- 204 No Content – Response to a successful request that won’t be returning a body; we use this for a DELETE or a PUT.
- 400 Bad Request – The request is malformed.
- 401 Unauthorized – When no or invalid authentication details are provided.
- 403 Forbidden – When authentication succeeded but authenticated users don’t have access to the resource.
- 404 Not Found – When a non-existent resource is requested.
- 405 Method Not Allowed – When an HTTP method is being requested that isn’t allowed for the authenticated user.
- 410 Gone – Indicates that the resource at this endpoint is no longer available.
- 422 Unprocessable Entity – If incorrect content type was provided as part of the request.
- 429 Too Many Requests – When a request is rejected due to rate limiting.
HTTP Request Header
For each HTTP call, we need a few headers in the HTTP request:
API Version
In each call, you can add the version of the API. The key is placed into the header with the name api-version, with a number of the versions.
API Key
In each call, we add the API key for identification. Based on this API key, we can determine the data domain in which the application does its search. The key is placed into the header with the name api-key. You add the API key (provided for your application) as the value.
Customer Key
The customer’s external ID needs to be sent in the header for all API calls of that customer. The key is placed into the header with the name customer-key.
Token
Each application needs an authentication token. When calling a method, you need to send the token through the HTTP header. It is a “Bearer” token. It is submitted in the following format into the header with the name Authorization:
Bearer <token>
Where <token> needs to be replaced by the actual token obtained from the authentication part of the API.
HTTP Response Header
There are some circumstances where we give back functional information in the response header of a call. All the situations that have a response header are described below in this chapter.
POST
When posting to create a new entry, there will always be a Location response header. In this response header, you will find the URL of the newly created resource. The full URL, including the domain on which the API is hosted, will be supplied.
Paging
The API supports paging when retrieving a list of items. There are two different parameters you can give in the URL, through the use of query strings.
Page Parameter
The page parameter indicates which page of results you want to get. By supplying the page parameter through the URL, you get items for that page. When not supplying the page parameter in the URL, you always get the first page.
Example: If you request 15 items on a page, and you request page=2, you get items 16–30 of the result.
Example URL:
/customers?page=2
PageSize Parameter
The pagesize parameter indicates how many items appear on one page. By supplying the pagesize parameter in the URL, you get that number of items back on a single page (if enough items are present). When you do not supply the pagesize parameter, the API returns 15 items by default. The maximum allowed is 1000 items per page; any page size above 1000 will also return 1000 items.
Example URL:
/customers?pageSize=50
Sorting
Some endpoints that return a list offer the ability to sort. Sorting is triggered by supplying the sort parameter in the URL. The value of the sort parameter is a comma-separated list of fields to sort by. You can specify descending order by prefixing a - (minus sign) to the field name.
Example URL:
/customers?sort=country,name
(If you wanted to sort by country descending and then by name, you could do /customers?sort=-country,name.)
Searching
The API has the ability to perform simple searches, which limit the results you get back. Searching works by adding field names (that exist in the return objects) with a value in the query parameters. All searches are case-insensitive. If you want to search for a substring, you can use the % sign at the beginning (or end) of the value as a wildcard.
Example URLs:
/customers?name=Envision
or
/customers?name=%vision&sortby=creationDate
Validation Errors
When your application does a POST or a PUT, you can get a validation error when the object posted does not meet the requirements of validation. When this happens, the API will return an HTTP status code 422, with the validation errors in the body. Below is an example validation error response body:
{
"message": "Validation errors",
"code": 400,
"result": false,
"functionCode": "<number or empty>",
"objectJson": "{\"Company\":\"Company ABC\",\"function\":\"Functie ABC\",\"Code\":\"Code ABC\",\"Active\":true,\"Email\":\"[email protected]\",\"Firstname\":\"Firstname ABC\",\"Lastname\":\"Lastname ABC\"}",
"errors": [
{
"message": "Field 'name' is required",
"fields": "name"
},
{
"message": "Field 'birthdate' has no correct date format",
"fields": "birthdate"
}
]
}
Validation Codes
| Code | Description |
|---|---|
| 4000 | Incoming (input) entity could not be validated. |
| 4050 | Could not delete entity. |
When a validation code other than 4000 is returned, a specific function code can be given. It will be described in the relevant API method.
POST
When doing POST requests to the API, you need to supply the data as JSON and set an HTTP Header Content-Type with the value application/json.
If you do a POST through jQuery, you often do not need to set Content-Type explicitly, as shown in the following example:
$.ajax({
type: 'POST',
url: '/api/customer',
data: JSON.stringify(createrequestdata),
headers: {
'api-version': 1,
'api-key': $('#txt_apikey').val(),
'Content-type': 'application/json'
},
beforeSend: function (xhr, settings) {
xhr.setRequestHeader('Authorization', 'Bearer ' + $('#txt_token').val());
},
success: function (data, status) {
console.log("data", data);
}
});
Note: If you receive a 415 Unsupported Media Type error, verify that you have correctly set the Content-Type header (e.g., when using Postman, be sure to add Content-Type: application/json).
Candidate Analysis Result Explanation
Below is an explanation of the result items with scores of an analysis result. They are arrays of values with the name in bold.
Normscores
These are the scores for talents, generally in a range of 1 to 9. The scores are calculated based on the norm for a certain country/culture.
Aptitudescores
These are the scores for competences in a range of 1 to 10 (numbers can include decimals).
NormScorePercentage
These represent percentage scores for competences, based on the new aptitude scores.
NormScoreScales
These are scaled scores for talents in a range of 1 to 4, based on a predefined scale.
AptitudescoresScale
These are scaled scores for competences in a range of 1 to 4, based on a predefined scale.