How to get started with the Veremark API

Discover how to unlock the power of Veremark’s screening engine within your application

Before you begin

Ensure you have access to the following resources and information:

• Veremark API Documentation

  • Access the comprehensive API documentation here.

• Testing Account Setup

  • Veremark will help you get access to a sandbox account and configure the necessary user profiles.
•  Authorisation Token
  • Veremark will provide an authorisation token for the testing account, enabling secure API calls.
• Criteria Creation
  • The 'Criteria' is a key aspect of the Veremark platform, these criteria represent packages of background checks tailored to meet your specific needs and will be used to request checks in your system.

Our account managers can collaborate with your team to help define and set up criterias if required. You can also learn more about creating Veremark criteria here.

 

---

 

Stages of the Background Check

Stage 1: Selecting the Background Check Criteria

The user of the customer’s application must select the appropriate criteria (a package of background checks) to initiate the process. Use the listCriterias endpoint to fetch available criteria:

👉 View listCriterias API Documentation

Stage 2: Creating a Background Check Request

Once the criteria are selected, a background check request is created on Veremark using the createRequest endpoint. This request must include the following details:

• Criteria GUID (unique identifier for the selected criteria).
• Candidate’s first name, last name, and email address.
• Job role.
• Webhook details (METHOD and URL) to receive status updates.

👉 View createRequest API Documentation

Stage 3: Receiving Status Updates via Webhook

Veremark will send status updates to the webhook URL specified in the createRequest method. The updates will notify the customer application of any changes to the background check status.

For details on webhook setup and usage:

👉 View Webhook API Documentation

Stage 4: Retrieving the Current Status and Results

Once notified via the webhook, the customer application can retrieve the latest status of the background check criteria using the retrieveRequest endpoint.

For a basic integration, the following fields should be fetched:

• Status: The current status of the background checks.
• request_url: A link to the candidate’s results on the Veremark system. This link can be displayed within the customer application for user access.

👉 View retrieveRequest API Documentation

Stage 5: Retrieving the Full PDF Report

When the background check request status is set to “Closed”, a detailed PDF report containing the results of all performed checks (as defined by the criteria) can be retrieved using the retrieveFullReport endpoint.

Requirements:

• The GUID of the request is required to generate the report.

👉 View retrieveFullReport API Documentation

Stage 6 [Optional]: Downloading Candidate Documents

If the candidate has uploaded supporting documents during the background check process, these documents can be retrieved using the retrieveDocumentDownload endpoint.

Requirements:

• The GUID of the document to be downloaded. This is available in the “documents” list within the checks response of the retrieveRequest endpoint.

👉 View retrieveDocumentDownload API Documentation

Once the setup is complete

Your integration will enable the following functionalities:

• Trigger Background Checks: Initiate background checks directly from your application (e.g., Workday) using the Veremark API.
• Real-Time Status Updates: Receive status updates for all checks associated with a specified criteria package.
• Results Access: Access a direct link to the detailed results hosted on the Veremark system.

Information flow diagram

The Veremark Statuses

Here are the various system statuses you should be aware of: