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

    Validata is the Dutch leader in performing background screenings for employees, candidates and companies.

    The Validata Group API is an Application Programming Interface you can integrate 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.

    The SOAP Interface is described in this document. The technical details in a XML document (WSDL and XSD) can be obtained upon request.

    End Points

    The web service can be tested with web service user account details at the location:

    https://valluga-accp.mendixcloud.com/ws/Validata_Group_API

    Authentication

    To authorize, use this code:

    <soap:Header>
      <tns:authentication>
        <username>user</username>
        <password>pass</password>
      </tns:authentication>
    </soap:Header>
    

    Make sure to replace user & pass with your credentials.

    For authentication you will need login details for a Web Service Account. When performing a web service call, your account information is included with the screening 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.

    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

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Header>
            <tns:authentication>
                <username>exampleUser</username>
                <password>examplePassword</password>
            </tns:authentication>
        </soap:Header>
        <soap:Body>
            <tns:retrieveAllClients/>
        </soap:Body>
    </soap:Envelope>
    

    The above command returns SOAP structured like this:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Body>
            <tns:retrieveAllClientsResponse>
                <Client>
                    <ClientID>123456789</ClientID>
                    <Name>exampleString</Name>
                    <StatutoryName>exampleString</StatutoryName>
                </Client>
                <Client>
                    <ClientID>123456789</ClientID>
                    <Name>exampleString</Name>
                    <StatutoryName>exampleString</StatutoryName>
                </Client>
                <Client>
                    <ClientID>123456789</ClientID>
                    <Name>exampleString</Name>
                    <StatutoryName>exampleString</StatutoryName>
                </Client>
            </tns:retrieveAllClientsResponse>
        </soap:Body>
    </soap:Envelope>
    

    The purpose of this web service 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.

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

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Header>
            <tns:authentication>
                <username>exampleUser</username>
                <password>examplePassword</password>
            </tns:authentication>
        </soap:Header>
        <soap:Body>
            <tns:retrieveClientInfo>
                <ClientID>123</ClientID>
            </tns:retrieveClientInfo>
        </soap:Body>
    </soap:Envelope>
    

    The above command returns SOAP structured like this:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Body>
            <tns:retrieveClientInfoResponse>
                <clients>
                    <ClientID>123456789</ClientID>
                    <Name>exampleString</Name>
                    <StatutoryName>exampleString</StatutoryName>
                    <ClientUser_Client>
                        <ClientUser>
                            <Mail>exampleString</Mail>
                            <FullName>exampleString</FullName>
                        </ClientUser>
                    </ClientUser_Client>
                    <Entity_Client>
                        <Entity>
                            <Name>exampleString</Name>
                            <Description>exampleString</Description>
                            <EntityID>123456789</EntityID>
                        </Entity>
                    </Entity_Client>
                    <UpdateClientsScreeningProfile_Client>
                        <UpdateClientsScreeningProfile>
                            <ProfileID>123</ProfileID>
                            <NameNL>exampleString</NameNL>
                            <NameEN>exampleString</NameEN>
                            <DescriptionNL>exampleString</DescriptionNL>
                            <DescriptionEN>exampleString</DescriptionEN>
                            <CompanyScreening>false</CompanyScreening>
                        </UpdateClientsScreeningProfile>
                    </UpdateClientsScreeningProfile_Client>
                </clients>
            </tns:retrieveClientInfoResponse>
        </soap:Body>
    </soap:Envelope>
    

    Additional required parameters for candidate screening

    Field Data type Description
    ClientID Integer/Long The ID number that is unique to the company ordering the screening

    Screenings

    RequestScreening

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Header>
            <tns:authentication>
                <username>exampleUser</username>
                <password>examplePassword</password>
            </tns:authentication>
        </soap:Header>
        <soap:Body>
            <tns:requestScreening>
                <ScreeningRequest>
                    <ClientID>123</ClientID>
                    <ProfileID>123</ProfileID>
                    <CandidateName>exampleString</CandidateName>
                    <CandidateEmail>exampleString</CandidateEmail>
                    <CandidatePhone>exampleString</CandidatePhone>
                    <CompanyName>exampleString</CompanyName>
                    <KvKNumber>exampleString</KvKNumber>
                    <EntityID>123</EntityID>
                    <LanguageCode>exampleString</LanguageCode>
                    <requestCheck_requestScreening>
                        <CheckRequest>
                            <Name>exampleString</Name>
                            <CheckType>[key]</CheckType>
                        </CheckRequest>
                    </requestCheck_requestScreening>
                    <ClientUser>exampleString</ClientUser>
                    <ScreeningDocument_requestScreening>
                        <ScreeningDocument>
                            <FileName>exampleString.pdf</FileName>
                            <FileContents>Base64 encode file content</FileContents>
                        </ScreeningDocument>
                    </ScreeningDocument_requestScreening>
                    <EmploymentStartDate>2020-06-22T09:00:00</EmploymentStartDate>
                    <CostCentre>CC-ABC-1234</CostCentre>
                    <JobTitle>ExampleJobTitle</JobTitle>
                </ScreeningRequest>
            </tns:requestScreening>
        </soap:Body>
    </soap:Envelope>
    

    The above command returns SOAP structured like this:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Body>
            <tns:requestScreeningResponse>
                <ScreeningID>123</ScreeningID>
            </tns:requestScreeningResponse>
        </soap:Body>
    </soap:Envelope>
    

    The Validata Group request screening web service is the web service that is used to request a new screening for one of your candidates.

    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 (100) Unique mail address of ClientUser which will be used for communication about the requested screening.

    Additional required parameters for candidate screening

    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.

    Additional required parameters for company screening

    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' number of the company

    Optional parameters (for company and candidate screenings)

    Field Data type Description
    EntityID* Integer/Long Unique Entity ID that could be used for invoice purposes
    CheckRequest* Object list If you want to specify one work experiences and / or one education that must be verified in the screening.
    ScreeningDocument Object list This makes it possible to add a CV document to the screening.
    EmploymentStartDate* DateTime Specifies the contractual start date for the candidate. For example 2020-06-22T09:00:00
    CostCenter String (200) Can be used to specify a Purchase Order or cost center.
    JobTitle String (40) Can be used to specify a job title.

    ScreeningDocument object

    Field Data type Description
    FileName String (400) File name of the CV document. This document should be of the format .doc, docx or .pdf.
    FileContents String (unlimited) Base64 encode file contents of the CV document.

    CheckRequest object

    Field Data type Description
    Name String Name of the company or name of the education that must be checked
    CheckType String Type of check. Possible check types are 'Work_experience' and 'Education'

    CheckScreening

    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 Unique ID 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', '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.
    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Header>
            <tns:authentication>
                <username>exampleUser</username>
                <password>examplePassword</password>
            </tns:authentication>
        </soap:Header>
        <soap:Body>
            <tns:checkScreening>
                <ScreeningID>123</ScreeningID>
            </tns:checkScreening>
        </soap:Body>
    </soap:Envelope>
    

    The above command returns SOAP structured like this:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Body>
            <tns:checkScreeningResponse>
                <ScreeningStatus>
                    <Status>[key]</Status>
                    <AvailableDocuments_ScreeningStatus>
                        <AvailableDocuments>
                            <Name>CV.doc</Name>
                            <DocumentType>CV</DocumentType>
                            <DocumentID>123456</DocumentID>
                        </AvailableDocuments>
                    </AvailableDocuments_ScreeningStatus>
                </ScreeningStatus>
            </tns:checkScreeningResponse>
        </soap:Body>
    </soap:Envelope>
    
    
    

    GetDocument

    In two stages of the screening, a report is created, which is available to retrieve from the web service. When a report is ready to be retrieved, Validata Group will request your webhook if it is in place, with a call to use the getDocument web service. As an input, 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 retrieve the most recent version of the screening report.

    Field Data type Description
    ScreeningID Integer/Long Unique ID created for the screening
    DocumentType String Type of Document. Possible document types are 'PES_Report'
    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Header>
            <tns:authentication>
                <username>exampleUser</username>
                <password>examplePassword</password>
            </tns:authentication>
        </soap:Header>
        <soap:Body>
            <tns:getDocument>
                <ScreeningID>123</ScreeningID>
                <DocumentType>PES_Report</DocumentType>
            </tns:getDocument>
        </soap:Body>
    </soap:Envelope>
    

    The above command returns SOAP structured like this:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Body>
            <tns:getDocumentResponse>
                <ScreeningDocument>
                    <Contents>[Binary data]</Contents>
                    <DocumentType>[key]</DocumentType>
                    <Name>exampleString</Name>
                </ScreeningDocument>
            </tns:getDocumentResponse>
        </soap:Body>
    </soap:Envelope>
    

    GetScreeningDocument

    This service allows for users to download associated documents to a particular screening.

    Field Data type Description
    ScreeningID Integer/Long Unique ID created for the screening
    DocumentID Integer/Long Unique ID created for the document
    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Header>
            <tns:authentication>
                <username>exampleUser</username>
                <password>examplePassword</password>
            </tns:authentication>
        </soap:Header>
        <soap:Body>
            <tns:getScreeningDocument>
                <ScreeningID>123</ScreeningID>
                <DocumentID>123</DocumentID>
            </tns:getScreeningDocument>
        </soap:Body>
    </soap:Envelope>
    

    The above command returns SOAP structured like this:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:tns="http://www.cv-ok.com">
        <soap:Body>
            <tns:getScreeningDocumentResponse>
                <ScreeningDocument>
                    <DocumentName>Document reference name</DocumentName>
                    <Name>Filename + file type</Name>
                    <Contents>[Binary data]</Contents>
                </ScreeningDocument>
            </tns:getScreeningDocumentResponse>
        </soap:Body>
    </soap:Envelope>
    
    xml