NAV Navbar
xml
  • Introduction
  • End Points
  • Authentication
  • Client Methods
  • Screening Methods
  • 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 service can be tested with test account details at the location:

    https://cvokcore‐test.mendixcloud.com/rest/{operation}

    For production the API can be reached with production account details at:

    https://cvokcore.mendixcloud.com/rest/{operation}

    Where {operation} must be replaced with the appropriate REST service call identifier.

    Authentication

    To authorize, use WebServiceUsername & WebServicePassword header tags in every message:

    
        "Username": "WebServiceUsername"
        "Password": "WebServicePassword"	
    

    Make sure to replace WebServiceUsername & WebServicePassword between the quotes with the given credentials for your Web Service User.

    Also, the header tag "Content-Type" should be set to "application/json" for all messages.

    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 can not be used to login to the website front‐end of Validata Group. If you want access to the client portal you will need to request a separate client user account.

    Client Methods

    RetrieveAllClients

    Request message structure for a GET-call to RetrieveAllClients

    
    {
    }
    

    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.

    Request message structure for a GET-call to RetrieveClientInfo

    
    {
    	"ClientID": 1234
    }
    

    The above command returns a JSON structured message like this:

    
    
    {
    	"ClientID":1234,
    	"StatutoryName": "StatutoryName",
    	"Name": "ClientName",
    	"ClientUsers": [
    		{ 
    			"Email": "john.doe@companyname.com",
    			"Fullname": "John Doe"
    		}
    	],
    	"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.
    Email String (100) This is the email address that identifies the client user account.
    Fullname String (200) This the fullname of the client user.
    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 (100) 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

    Request message structure for a POST-call to RequestScreening

    
    
    {
    	"ClientID": 1234, 
    	"ProfileID": 1423,
    	"CandidateName": "John Doe", 
    	"CandidateEmail": "john.doe@validatagroup.com", 
    	"CandidatePhone": "06-12345678",
    	"CompanyName": "CompanyNameString", 
    	"KvKNumber": "12345678", 
    	"EntityID": "OrganisationalEntity",
    	"LanguageCode": "nl_NL", 
    	"ClientUser": "clientuserID@client.com",
    	"StartDate": "2019-06-01"
    }
    
    

    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 or company.

    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 parameters required 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.

    Additional parameters required for company screenings

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

    Returned parameters

    Field Data type Description
    ScreeningID Integer/Long The unique ID that was created for the screening.

    CheckScreening

    Request message structure for a GET-call to CheckScreening

    
    {
    	"ScreeningID": 1234567
    }
    
    

    The above command returns a JSON structured message like this:

    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.

    Field Data type Description
    ScreeningID Integer/Long The unique ID that was created for the screening.
    
    
    {
    	"ScreeningStatus":{
    		"Status":"Concept_PES",
    		"AvailableDocuments":[
    			{	"Name":"CV",
    				"DocumentType":"CV",
    				"DocumentID":"8382"
    			},
    			{	"Name":"VOG",
    				"DocumentType":"Certificate_of_Good_Conduct",
    				"DocumentID":"8385"
    			},
    			{	"Name":"Akkoordverklaring",
    				"DocumentType":"Declaration_of_consent",
    				"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 'Waiting_for_candidate', 'Processing', 'Waiting_for_VOG', 'Concept_PES', 'Inactive', 'Finalized', '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

    Request message structure for a GET-call to GetScreeningDocument

    
    {
    	"ScreeningID": 123567,
    	"DocumentID": 4321
    }
    

    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), which is available to retrieve from the web service in the status 'Concept_PES' or 'Finalised'. In the status 'Concept_PES', a concept of the report is generated, whereas in the status 'Finalised' the report is re-generated in its final form. When a report is ready to be retrieved, Validata Group will call your webhook if it is in place.

    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:

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