NAV Navbar
xml
  • Introduction
  • End Points
  • Authentication
  • Client Methods
  • Screening Methods

    • Introduction to the Valluga REST API

    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/v2/{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

    Request

    
  POST https://{baseURL}/rest/validata_api/v2/oauth HTTP/1.1
  Content-Type: application/x-www-form-urlencoded;
  grant_type=client_credentials&
  client_id=a.clientid&
  client_secret=a.clientsecret

    Response

    
  { 
      "access_token": "DDfaAeoinBr2S5aPy6FIo9SFyyDTVMuQql8Xi.......",
      "expires_in": 3600,
      "token_type": "Bearer"
  }

    For authorization Validata uses OAuth 2.0 with the Client credentials flow. A POST request containing grant_type, client_id and client_secret is required to retrieve an access token that will be valid for 60 minutes. That access token should be included in the Authorization header of any requests to the API.

    The Web Service Account is limited to a preset number of requests per day. The default value for the limit is set to 1000.

    Client Methods

    RetrieveAllClients

    Request

    
GET https://{baseURL}/rest/validata_api/v2/retrieveAllClients HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN

    Response

    
Content-Type: application/json

{
  "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 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

    
GET https://{baseURL}/rest/validata_api/v2/retrieveClientInfo?ClientID={ClientID} HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN

    Response

    
Content-Type: application/json

{
  "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 client company and is created upon registration in the Validata application.

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

    Request

    
POST https://{baseURL}/rest/validata_api/v2/requestScreening HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Content-Type: application/json;
  
{
  "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",
  "VOGProfileNumber": "Profile123"
}

    Response

    
HTTP/1.1 200 OK
Content-Type: application/json

{
  "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.
    VOGProfileNumber String (200) Profile number of VOG (Dutch Certificate of Conduct).

    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.

    Request

    
GET https://{baseURL}/rest/validata_api/v2/checkScreeningStatus?ScreeningID={ScreeningID} HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN

    Response

    
Content-Type: application/json
{
	"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
			}
		]
	}
}
    Field Data type Description
    ScreeningID Integer/Long The unique ID that was created for the screening.

    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

    Request

    
GET https://{baseURL}/rest/validata_api/v2/getScreeningDocument?ScreeningID={ScreeningID}&DocumentID={DocumentID} HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN

    Response

    
Content-Type: application/json
{
	"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:

    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.

    DeactivateScreening

    Request

    
POST https://{baseURL}/rest/validata_api/v2/deactivateScreening HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Content-Type: application/json;
  
{
  "ScreeningNumber": 1234,
  "DeactivationReasonClient": "Candidate stops process"
}

    Response

    
HTTP/1.1 200 OK
Content-Type: application/json

{
  "Screening 1234 successfully deactivated"
}

    This web service can be used to deactivate a screening. If successfull, a status 200 is returned.

    It is mandatory to also give a reason for the deactivation.

    Required Parameters

    Field Data type Description
    ScreeningNumber Integer/Long The ID number that is unique to the screening that needs to be deactivated.
    DeactivationReasonClient String The reason for deactivating the screening.

    ReactivateScreening

    Request

    
POST https://{baseURL}/rest/validata_api/v2/reactivateScreening HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Content-Type: application/json;
  
{
  "ScreeningNumber": 1234
}

    Response

    
HTTP/1.1 200 OK
Content-Type: application/json

{
  "Screening 1234 successfully reactivated"
}

    This web service can be used to reactivate a screening. If successfull, a status 200 is returned.

    Please note that a screening can only be reactivated once through this service.

    Required Parameters

    Field Data type Description
    ScreeningNumber Integer/Long The ID number that is unique to the screening that needs to be reactivated.
    CODE