Introduction to the Validata REST API
Validata Group is the Dutch leader in performing background screenings for employees, candidates and companies.
The Validata Group API is an RESTFULL webservice Application Programming Interface you can integrate using JSON to have your website or app automatically request screenings and receive screening reports. This document will start with a summary of the screening process which will help to understand the different web service operations available. Then it will continue by giving technical details about the different operations.
End Points
The web services can be implemented and tested using a test account. Details for a test account will be shared upon request. Details of the location will be shared as well. The general format for the web service operations is this:
https://{baseURL}/rest/validata_api/v1/{Operation}?[Options]
Where {baseURL}
denotes the server, and {Operation}
must be replaced with the appropriate REST service call identifier. Additional options depend on the operation that is called.
Authentication
Basic Authentication specifies that the header of every message contains the tag:
Authorization: Basic {Base64 encoding of 'WebServiceUsername:WebServicePassword'}
For example:
Authorization: Basic V2ViU2VydmljZVVzZXJuYW1lOldlYlNlcnZpY2VQYXNzd29yZA
You must replace
WebServiceUsername
&WebServicePassword
with the given credentials for your Web Service User. For all messages, the header tag "Content-Type" should be set to "application/json", and the header tag "Accept" should be "application/json".
Only 1 space is allowed after the "Basic" prefix and before you add the Base64 encoding. The use of additional spaces results in a transaction failure.
For authentication you will need login details for a Web Service account that will be provided upon request. When performing a web service call, your Web Service account details have to be included in the header of every request. This serves two purposes: validation of your authenticity as a Validata Group partner and to know for which client the candidate screening has to be created.
The Web Service Account is limited to a preset number of requests per day. The default value for the limit is set to 1000.
To authorize, use the protocol for Basic Authentication.
Client Methods
RetrieveAllClients
The operation URL is
https://{baseURL*}/rest/validata_api/v1/retrieveAllClients
Request message structure for a GET-call to retrieveAllClients is not applicable.
Returns a JSON message structured like this:
{"ListOfClients":
[
{
"ClientID": 1234,
"Name": "NameOftheClient",
"StatutoryName": "StatutoryName"
},
{
"ClientID": 5678,
"Name": "NameOftheClient_2",
"StatutoryName": "StatutoryName_2"
}
]
}
The purpose of the RetrieveAllClients web service GET-call is to obtain all clients associated with your Web Service user account with corresponding ID's. With those ID's you can request up to date client information such as available profiles, entities and client users. Please refer to the retrieveClientInfo documentation for additional information.
Returned parameters
Field | Data type | Description |
---|---|---|
ClientID | Integer/Long | The ID number that is unique to the client company and is created upon registration in the Validata application. |
Name | String (200) | This the name of the client in the Validata application. |
StatutoryName | String (200) | Statutory name of the client. |
RetrieveClientInfo
The purpose of this web service is to obtain up‐to‐date information on the client associated with your user account with a specific ClientID and the ProfileIDs that are associated with the client. The ClientID and a ProfileID are required to request a screening. It is recommended to always use this web service before requesting a screening to make sure you use up‐to‐date information.
If there is only a single customer and limited number of profiles, it is also possible to receive these manually so that you do not need to implement this web service. The main details you need for making requests are the client, profile and entity IDs.
The operation URL is
https://{baseURL*}/rest/validata_api/v1/retrieveClientInfo?ClientID={ClientID}
Request message structure for the GET-call is not applicable.
The above command returns a JSON structured message like this:
{
"ClientID":1234,
"StatutoryName": "StatutoryName",
"ClientName": "ClientName",
"ClientUsers": [
{
"Email": "john.doe@companyname.com",
"Fullname": "John Doe"
}
],
"Entities": [
{
"EntityName": "Finance",
"Description": "Financial Department",
"EntityID": 123456789
}
],
"ScreeningProfileList": [
{ "ProfileID": 1345,
"NameNL": "Basis",
"NameEN": "Basis",
"DescriptionNL": "Basis profiel",
"DescriptionEN": "Basic profile",
"CompanyScreening": "false"
}
]
}
Required parameters
Field | Data type | Description |
---|---|---|
ClientID | Integer/Long | The ID number that is unique to the company ordering the screening |
Returned parameters
Field | Data type | Description |
---|---|---|
ClientID | Integer/Long | The ID number that is unique to the client company and is created upon registration in the Validata application. |
Name | String (200) | This the name of the client in the Validata application. |
StatutoryName | String (200) | Statutory name of the client. |
String (100) | This is the email address that identifies the client user account. | |
Fullname | String (200) | This the fullname of the client user. |
Name | String (200) | This the name of the organisational entity. |
Description | String (1000) | This the description of the organisational entity. |
EntityID | Integer/Long | This is a unique ID that is associated with the entity. |
ProfileID | Integer/Long | This is a unique ID that is associated with the profile. |
NameNL | String (100) | The Dutch name of the profile. |
NameEN | String (100) | The English name of the profile. |
DescriptionNL | String (500) | The Dutch description of the profile. |
DescriptionEN | String (500) | The English description of the profile. |
CompanyScreening | Boolean | Indicates if this profile is for screening a company (as opposed a profile for screening candidates). Possible values are 'true' and 'false'. |
Screening Methods
RequestScreening
The operation URL is
https://{baseURL*}/rest/validata_api/v1/requestScreening
The request message structure for the POST-call requestScreening should look like this:
{
"ClientID": 1234,
"ProfileID": 1423,
"CandidateName": "John Doe",
"CandidateEmail": "john.doe@validatagroup.com",
"CandidatePhone": "06-12345678",
"CompanyName": "CompanyNameString",
"KvKNumber": "12345678",
"EntityID": 4321,
"LanguageCode": "nl_NL",
"ClientUser": "clientuserID@client.com",
"Education": "MandatoryEducationName",
"WorkExperience": "MandatoryWorkExperienceName",
"StartDate": "2019-06-01",
"JobTitle": "CandidateJobTitle",
"CostCenter":"12354CC",
"CVFileName": "FileName.pdf",
"CVFileContents": "BASE64_ENCODED_FILE_CONTENTS"
}
The above command returns a JSON structured message like this:
{
"ScreeningID": 1234567
}
This web service can be used to request a new screening for a candidate. If successfull, a status 201 is returned.
Requesting a new screening for a company is currently not supported.
Required Parameters
Field | Data type | Description |
---|---|---|
ClientID | Integer/Long | The ID number that is unique to the company ordering the screening. |
ProfileID | Integer/Long | This is a unique ID that is associated with the profile. |
ClientUser | String | Unique mail address of ClientUser which will be used for communication about the requested screening. |
Additional required parameters for candidate screenings
Field | Data type | Description |
---|---|---|
CandidateName | String (200) | The first and last name of the candidate to be screened. |
CandidateEmail | String (100) | The email address of the candidate. |
CandidatePhone | String (30) | The phone number of the candidate. |
LanguageCode | String (5) | This is used to select a language for the candidate. Possible codes are 'en_US' for English and 'nl_NL' for Dutch. |
Optional parameters for candidate screenings
Field | Data type | Description |
---|---|---|
StartDate | String (10) | Start date of the candidate. The expected format is yyyy-MM-dd. |
JobTitle | String (40) | The job title of candidate. |
CVFileName | String (200) | File name of the CV document. This should be a document of the format .doc, .docx or .pdf. | CVFileContents | String (unlimited) | Base64 encode file contents of the CV document. |
Education | String (200) | Name of the mandatory education. This education experience will be automatically added to the screening. | WorkExperience | String (200) | Name of the mandatory work experience. This work experience will be automatically added to the screening. |
Additional required parameters for company screenings
Requesting a new screening for a company is currently not supported.
Field | Data type | Description |
---|---|---|
CompanyName | String (150) | The name of the company to be screened. |
KvKNumber | String (8) | The 'Kamer van Koophandel' (Chamber of Commerce) number of the company. |
Optional parameters (for candidate or company screenings)
Field | Data type | Description |
---|---|---|
EntityID | Integer/Long | Unique Entity ID that could be used for invoice purposes. * |
CostCenter | String (200) | Can be used to specify a Purchase Order or cost center. |
Returned parameters
Field | Data type | Description |
---|---|---|
ScreeningID | Integer/Long | The unique ID that was created for the screening. |
CheckScreeningStatus
The purpose of this service is to allow users to check the status of a given screening as well as get an overview of the screening. This service also gives an overview of the documents attached to a particular screening.
The operation URL is
https://{baseURL*}/rest/validata_api/v1/checkScreeningStatus?ScreeningID={ScreeningID}
Request message structure for the GET-call is not applicable.
Field | Data type | Description |
---|---|---|
ScreeningID | Integer/Long | The unique ID that was created for the screening. |
The above command returns JSON message structured like this:
{
"ScreeningStatus":{
"Status":"Processing",
"AvailableDocuments":[
{ "Name":"CV",
"DocumentType":"CV",
"DocumentID":8382
},
{ "Name":"VOG",
"DocumentType":"VOG",
"DocumentID":8385
},
{ "Name":"Akkoordverklaring",
"DocumentType":"LetterOfApproval",
"DocumentID":8386
},
{ "Name":"Concept_Rapport_Piet Janssen_created_6-12-18 8:29.pdf",
"DocumentType":"PES_report",
"DocumentID":8387
}
]
}
}
Returned parameters
Field | Data type | Description |
---|---|---|
Status | String (22) | The current status of the screening. Possible values are 'WaitingForCandidate', 'Processing', 'Deactivated', 'WaitingForVOG', 'Finished', 'SavedForClient', 'Anonymized'. |
DocumentName | String (200) | The name of the document. |
DocumentType | String (40) | The type of document. |
DocumentID | Integer/Long | The ID of the document. |
GetScreeningDocument
The operation URL is
https://{baseURL*}/rest/validata_api/v1/getScreeningDocument?ScreeningID={ScreeningID}&DocumentID={DocumentID}
Request message structure for the GET-call is not applicable.
The above command returns JSON message structured like this:
{
"FileContents":"BASE64_ENCODED_FILE_CONTENTS",
"DocumentName": "Descriptive document name",
"Name": "Filename.pdf"
}
This service allows for users to download associated documents to a particular screening.
In two stages of the screening, a report is created (the so-called Pre-Employment Screening report, or PES-report), which is available to retrieve from the web service in the status 'WaitingForVOG' and 'Finalised'. In the status 'WaitingForVOG', a concept version of the report is generated, whereas in the status 'Finalised' the report is re-generated in its final form, including the result for the criminal background check ('VOG' in Dutch).
As an input for this operation, the web service requires the screening number that is to be called. In order for the web service to work, it has to conform to three conditions:
- A valid screening number needs to be provided
- The screening should be connected to the web service user
- The number of requests has not exceeded the daily limit.
When either of these conditions is not met, an error will be returned by the web service. When all conditions are met, the web service will return the requested document.
Required parameters
Field | Data type | Description |
---|---|---|
ScreeningID | Integer/Long | Unique ID created for the screening. |
DocumentID | Integer/Long | Unique ID created for the document. |
Returned parameters
Field | Data type | Description |
---|---|---|
DocumentName | String (100) | The name of the file and its extention. |
Name | String (200) | This the name of the client in the Validata application. |
Contents | String (unlimited) | Base64 encode file contents. |