Access Screening API (2.0)

This documentation is designed to provide assistance to Access Screening customers wishing to integrate with our API

The API allows you to view your Brands, Candidates, Background Checks and create new background checks.

This page sets out a high level overview of the integration that can be created between 3rd party applications & Screening.

To understand this document the following definitions are essential:

Candidate

Individual who will be Screened, assigned to a Background Check

Workflow

Definition of a compliance process, assigned to a Brand. Often align to specific roles, or levels of screening activity

Background Check

Collection of evidence obtained from a Candidate by processing a Workflow, sometimes referred to as ‘Cases’

Brand

Organisational unit for data segmentation & configuration. Often align to Customers or Business Units

The scope of the Screening API is to support the following activities

Initiate

Start Background Checks by submitting candidate & process information

Observe

Repeatedly poll for progress of Background Checks status updates

Retrieve

Obtain the results of a Background Check (as a PDF or raw data) & update records in 3rd party applications

Every integration & application is different, however the following sections expand on the activities required for each step of the above scope.

The Add a new Background Check method is used to initiate a Background Check. 3rd party applications need to submit the following information:

1. Candidate Information - At a minimum: Title, Name & Email. Additional data such as Addresses, Contact Details & Date of Birth can also be sent

2. Brand & Workflow - Process to which the Candidate will be Screened

The Candidate Information will likely already exist in your application. The identifiers for Brand & Workflow are available in dedicated API methods.

There are two possibilities to select a Brand & Workflow.

Pre-Configuration

It may be possible to pre-configure the brand & workflow that will be suitable for a candidate, for example in an Applicant Tracking System the job for which they have applied may have a Brand & Workflow assigned.

Interactive Selection

It is also possible create an interface such as the wireframe below to allow users of your application to select the Process Information when initiating a background check

Once initiated the Background Check will move through several statuses, starting at ‘Waiting for Candidate’ and ending at ‘Completed’ or ‘Stopped’.

It is recommended to create a service that will request status updates from the Background Check List method(s) on a recurring basis - at a minimum-interval of every 30 minutes.

You may wish to update internal records as the Background Check status progresses to monitor key performance indicators etc.

When a Background Check moves to a Completed/Stopped status you may wish to extract the results of the Screening Process.

There are two primary methods of achieving this

Background Check Detail API Method

Via the Background Check Detail the granular details of a background check & candidate are available in JSON as discrete fields. For details on the possible content available please see the ‘Show detailed view of a Background Check’ section

Suitable for updating records in 3rd party applications

Background Check PDF Report

The methods in the Reporting section detail how to obtain a singular PDF file including information obtained from the Candidate, References, External Checks, Attachments etc.

Suitable for print/email or attaching to Candidate/Applicant records.

The API requires that all requests are authenticated using API Token. For security all requests must use HTTPS.

You will be assigned an API token.

All requests to the API must be sent with a HTTP Header called “Authorization”. The value of this header will start with the string literal “Token ” followed by the supplied API token, e.g.:

Authorization: Token a250105d1c477534c624fadb1b3a384567e77bab

There is space after the word "Token".

Access to the API is only allowed from whitelisted IP addresses.

You need to provide Safe Screening IP address(es) to be added to your customer profile.

We offer webhook notifications to keep you informed about key events as they happen in real-time. These webhooks can automatically send data to your system whenever specific events occur, allowing you to seamlessly integrate our platform into your existing workflows.

If you're interested in setting up webhook notifications, please contact our implementation or support team. We'll assist you with the configuration process.

You will need to provide us an https endpoint that will accept a POST request and return a 200 status code to signify you have received and processed the message. Any other status codes will be retried with an exponential backoff up to 5 times.

You may provide us any additional headers you want sent on the request.

All webhooks are sent to the same endpoint, you can check the event_type field on the payload to identify the type of webhook received.

Headers

Each webhook request will contain the following headers.

e.g

{
    "content-type": "application/json",
    "x-webhook-timestamp": "1731486900",
    "x-webhook-uuid": "3edfcafe-043f-4f59-bc8d-94a18554f9cf",
    "x-webhook-signature": "65a11518dcab2bd403958d2988f31c77be6ea34ae9b254601d0afab25e5026f9",
}

x-webhook-signature

The x-webhook-signature is an HMAC signature generated using the contents of the payload and a secret which we will provide to you. It is optional to check this signature, but we do recommend it to ensure the authenticity of the webhook request.

Below is the example of how we generate the signature. You can perform the same operation and ensure the signatures match.

Python Example

    def generate_hmac_signature(
        secret: str,
        timestamp: int,
        payload: str
    ):
        combined_payload = (
            f"{timestamp}:{payload}"
        )

        return hmac.new(
            key=secret.encode(),
            msg=combined_payload.encode(),
            digestmod=hashlib.sha256
        ).hexdigest()

C# example

using System;
using System.Security.Cryptography;
using System.Text;

public class HmacSignatureGenerator
{
    public static string GenerateHmacSignature(string secret, long timestamp, string payload)
    {
        // Combine timestamp and payload as per your Python implementation
        string combinedPayload = $"{timestamp}:{payload}";

        // Create a new HMAC using SHA256
        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
        {
            // Compute the HMAC hash
            byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(combinedPayload));

            // Convert the byte array to a hex string
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
        }
    }
}

This event is raised when ever the background check status changes.

{
    "event_type": "BackgroundCheckStatusChangedEvent",
    "event_uuid": "041322cd-265e-4a3e-9050-d85b4d2d4ab2",
    "delivery_uuid": "3edfcafe-043f-4f59-bc8d-94a18554f9cf",
    "delivery_created_utc": "2024-11-13T08:30:00.491763Z",
    "delivery_sent_utc": "2024-11-13T08:35:00.285527Z",
    "payload": {
        "customer_id": 27,
        "status": "closed",
        "uuid": "919c8d0c-c6ec-4f16-9bb3-95602f4106f1",
        "brand_id": 87,
        "workflow_id": 340,
        "reference": "appuat:1:4657",
        "updated_at": "2024-11-12T12:51:56.551198"
    }
}

This event is raised once a reference response has been received either by the contact completing the referee portal or the operator adding a manual reference response.

{
    "event_type": "ReferenceResponseReceivedEvent",
    "event_uuid": "041322cd-265e-4a3e-9050-d85b4d2d4ab2",
    "delivery_uuid": "3edfcafe-043f-4f59-bc8d-94a18554f9cf",
    "delivery_created_utc": "2024-11-13T08:30:00.491763Z",
    "delivery_sent_utc": "2024-11-13T08:35:00.285527Z",
    "payload": {
        "customer_id": 27,
        "brand_id": 70,
        "workflow_id": 267,
        "backgroundcheck_uuid": "ed7decf3-92ea-496a-b293-9132c73a7ee3",
        "backgroundcheck_reference": "",
        "reference_request_uuid": "9a3c58c7-2c00-47ba-b94b-3ce0d3881576",
        "reference_response_received_at": "2024-11-07T09:26:53.151334"
    }
}

This event is raised whenever a data check status on a background check changes.

{
    "event_type": "DataCheckStatusChangedEvent",
    "event_uuid": "041322cd-265e-4a3e-9050-d85b4d2d4ab2",
    "delivery_uuid": "3edfcafe-043f-4f59-bc8d-94a18554f9cf",
    "delivery_created_utc": "2024-11-13T08:30:00.491763Z",
    "delivery_sent_utc": "2024-11-13T08:35:00.285527Z",
    "payload": {
        "customer_id": 3,
        "status": "failed",
        "backgroundcheck_uuid": "64562cfa-95d7-46c6-8f06-89b322230a48",
        "brand_id": 20,
        "workflow_id": 93,
        "backgroundcheck_reference": "",
        "updated_at": "2024-11-13T08:30:00.481351",
        "check_id": 4580,
        "check_type_id": "dbs_direct_basic",
        "check_type_name": "DBS Basic E & W"
    }
}